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.
- Author
- zanderadam ↗
- Repository
- engy ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 3
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
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
- Modes
- MCP Tools
- Shared Engine
- Key Principles
- Flow Position
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'.