Skip to content
Skills Library
Programming · Writing

write-sysdocs

/write-sysdocs

This skill should be used when the user asks to "bootstrap/generate/initialize system docs", "propose/update/refresh system docs", "edit/fix/browse a system doc", or "surface project knowledge to system docs". Dispatches in one of three modes depending on intent.

Repository
engy ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
3
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (3). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

This skill should be used when the user asks to "bootstrap/generate/initialize system docs", "propose/update/refresh system docs", "edit/fix/browse a system doc", or "surface project knowledge to system docs". Dispatches in one of three modes depending on intent.

Triggers from the description

bootstrap/generate/initialize system docspropose/update/refresh system docsedit/fix/browse a system docsurface project knowledge to system docs
Original author description

This skill should be used when the user asks to "bootstrap/generate/initialize system docs", "propose/update/refresh system docs", "edit/fix/browse a system doc", or "surface project knowledge to system docs". Dispatches in one of three modes depending on intent.

How it works

  1. Modes
  2. MCP Tools
  3. Shared Engine
  4. Key Principles
  5. Flow Position
Original SKILL.md headings · 114 lines, 880 words
SKILL.md preview
---
name: write-sysdocs
description: This skill should be used when the user asks to "bootstrap/generate/initialize system docs", "propose/update/refresh system docs", "edit/fix/browse a system doc", or "surface project knowledge to system docs". Dispatches in one of three modes depending on intent.
---

# Write System Docs

One editing engine for workspace system documentation — prose overview and technical docs under `{workspaceDir}/system/` — with a mode switch on where the work-list comes from. Writes are always uncommitted; git + the diff viewer are the review surface.

When any mode would create or update a doc under `system/features/`, delegate to `engy:feature-docs` instead of writing it here. Feature docs are owned exclusively by `engy:feature-docs`.

## Modes

| Mode | When to use | Work-list source |
|---|---|---|
| `init` | Empty or sparse `system/` tree | Codebase discovery via Glob/Grep/Read |
| `refresh` | After project completion or memory review | Completed tasks + promoted memories |
| `interactive` | User browses or edits one doc at a time | User input, one doc per turn |

Select the mode from the user's phrasing (see trigger phrases in description) or ask when ambiguous. See `references/` for per-mode detail.

## MCP Tools

- `listWorkspaces` — discover workspaceId when not in context
- `getWorkspaceDetails` — resolve `paths.workspaceDir`, `paths.systemDir`, and `repos[]`
- `getProjectDetails` — resolve project context (refresh mode only)
- `listTasks` — fetch completed tasks (refresh mode only)
- `listMemories` — fetch promoted permanent memories (refresh mode only)
- `search` — find relevant existing system docs (skip gracefully if collection not yet available)
- `reindex` — refresh the `system` collection after all writes (Step 5)

All codebase reads use **Glob**, **Grep**, and **Read** against absolute paths in `repos[]`. All doc writes use **Write** or **Edit** against absolute paths under `{workspaceDir}/system/`. The MCP server does not expose file IO.

## Shared Engine

All three modes run through the same engine:

### Step 1: Resolve Workspace

Obtain `workspaceId` from context or via `listWorkspaces`. Call `getWorkspaceDetails({ workspaceId })` to obtain `paths.workspaceDir`, `paths.systemDir`, and `repos[]`.

`systemDir` = `{workspaceDir}/system/`

### Step 2: Build Work-List

Dispatch to the mode-specific work-list step. See:
- [`references/init-mode.md`](references/init-mode.md) — codebase discovery
- [`references/refresh-mode.md`](references/refresh-mode.md) — tasks + memories gap analysis
- [`references/interactive-mode.md`](references/interactive-mode.md) — user-driven file selection

The mode-specific step returns a set of proposed creates/edits scoped to `system/overview.md` and `system/technical/`. If any item in the work-list targets `system/features/`, emit a handoff:

> This is a feature area — running /engy:feature-docs for `<area>`.

Then invoke `engy:feature-docs` via `Skill({ skill: 'engy:feature-docs' })` for that item and remove it from the work-list. Continue with the remaining (non-feature) items using the engine below.

### Step 3: Dispatch Research Subagent

For each non-trivial create or edit in the work-list, dispatch the `engy:research` subagent:

```
Task({
  subagent_type: 'engy:research',
  prompt: '<topic> — context: workspaceId=<workspaceId>, workspace=<slug>, repos=<repos[]>'
})
```

The `engy:research` agent **requires the numeric `workspaceId`** in the prompt (it errors with `Error: workspaceId missing from prompt` if absent) — pass the integer from Step 1, not the slug.

The subagent returns a `## Findings` digest with cited sources. Hold the digest for Step 4.

If the digest reports no results — the line `No relevant prior knowledge found for this question.` or footer `Distinct findings: 0 (after dedup)` — omit the `<!-- engy:research -->` marker block from the doc and write `No prior knowledge found.` inline under `## Sources` instead (no `memoryRefs:` frontmatter key either).

If the work spans distinct domains (e.g., backend + frontend), run one Task call per domain and merge the digests.

### Step 4: Propose and Write

Apply the work-list using the doc format defined in [`references/doc-format.md`](references/doc-format.md).

- **Interactive mode:** show a before/after diff (or content preview for new files) and wait for explicit user approval before writing. Never write silently.
- **Init and refresh modes:** write directly — changes are uncommitted and visible in the diff viewer.

Confirm every write path stays inside `systemDir`. In interactive mode, resolve with `realpath -m` via Bash and refuse any path whose canonical form escapes `systemDir`.

After writing all docs, ensure each affected directory has a `README.md` with the empty index markers. See `references/doc-format.md` for the README template.

### Step 5: Reindex

After all writes:

```
reindex({ workspaceId, collection: 'system' })
```

This populates `<!-- INDEX START --> ... <!-- INDEX END -->` blocks in each README with an ordered link list and refreshes the search index for the `system` collection.

### Step 6: Print Summary

Print a summary of all files written (disposition, path, one-line rationale) and remind the user: "Changes are uncommitted — review in the diff viewer, then commit or revert."

## Key Principles

- **Scope only `system/overview.md` and `system/technical/`** — feature docs (`system/features/`) are owned by `engy:feature-docs`; delegate and do not write them here.
- **Write in place, never `.draft`** — overwrites are uncommitted working-tree changes; the diff viewer and git are the safety net.
- **No automatic commit** — writes land as working-tree changes for the user to review.
- **Cite sources** — when research findings inform a doc, cite inline under `## Sources`. When there are none, say so explicitly.
- **Read before editing** — always Read an existing file in full before proposing an edit.

## Flow Position

**Init:** starting a new workspace or when `{workspaceDir}/system/` is empty or sparse.

**Refresh:** after `/engy:review-memories` promotes key memories at project close, or standalone when the user wants to refresh system docs.

**Interactive:** incrementally updating system docs as the codebase evolves, or after `init` to refine generated content one file at a time.

**Related:** `/engy:feature-docs` — sole owner of `system/features/<area>.md`.
Files in this package (5)
  • SKILL.md 6 KB
  • references/doc-format.md 4 KB
  • references/init-mode.md 3 KB
  • references/interactive-mode.md 4 KB
  • references/refresh-mode.md 3 KB

Versions

The database has no other skills named write-sysdocs.

Database snapshot: 13.11.2026 · package version 77d4bc8961dd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 80vc:docs
    Use when you need to analyze a codebase and initialize, update, or summarize project documentation.
  • 100docs-init
    Bootstrap agent-ready project documentation in docs/ plus an AGENTS.md entry point, tailored to the project type (backend, frontend, fullstack, mobile). Focuses on flows and conventions an AI agent needs before changing code. Marks anything that cannot be derived from code and…
  • 85write-the-docs
    Write or edit project documentation. Use when writing a README, design doc, or module doc.
  • 100documentation
    Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.
  • 100project-docs
    Generate project documentation from codebase analysis — ARCHITECTURE.md, API_ENDPOINTS.md, DATABASE_SCHEMA.md. Reads source code, schema files, routes, and config to produce accurate, structured docs. Use when starting a project, onboarding contributors, or when docs are missing…
  • 98check-third-party-docs
    Refresh this repo's cached upstream/third-party docs and propose improvements to the local skills/docs that wrap those tools. Use when the user says 'check for updated third party docs', 'check for updated third-party docs to improve our docs', 'refresh the cached docs', or 'sync upstream docs'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.