Documenting Code
Update only useful documentation. Start from code facts, identify the reader, and
make the smallest doc change that helps that reader act correctly.
Role-gated action
Detect capability from tools, not prose:
- Write-capable role: edit docs and run validation.
- Read-only role: apply nothing; emit proposed edits in the output contract.
Reader model
Choose the reader before writing.
Human reader:
- Make docs scannable: clear title, short overview, focused sections, examples.
- Keep docs short. Link to detail instead of creating long reads.
- Use Mermaid diagrams only when they answer a real structure, flow, lifecycle,
ownership, or trade-off question.
- Match the existing docs style. Do not invent fonts, colors, or custom visual
treatment unless the docs system already supports it.
Agent reader:
- Write terse operational instructions for LLMs.
- Prefer headers, bullets, numbered steps, and exact contracts.
- Remove generic knowledge, duplicate rules, pretty formatting, diagrams, tables,
long rationale, and advice the model already knows.
- If the task is to review or score agent instructions, use
reviewing-instructions.
Code reader:
- Comments and docstrings explain contracts, constraints, invariants, side
effects, error behavior, and non-obvious decisions.
- Delete comments that paraphrase code.
- Avoid comments in tests unless they explain non-obvious external behavior or
why an edge case matters.
Language references
Load only references matching changed implementation files:
- C# /.NET:
references/csharp.md
- Go:
references/go.md
- Java/Kotlin:
references/java-kotlin.md
- Python:
references/python.md
- Rust:
references/rust.md
- TypeScript:
references/typescript.md
- Web:
references/web.md
Mixed languages: load each matching reference. Unknown language: use this file
only.
Workflow
- Identify scope from the user request or changed files. Do not ask if scope is clear.
- Read relevant implementation, tests, and existing docs before writing.
- Decide reader type: human, agent, code reader, or mixed.
- Check docs against current behavior. Code wins unless the user says docs define the intended contract.
- Use
looking-up-docs only when external API syntax or behavior is uncertain.
- Use one bounded read-only subagent only for large doc audits; verify its claims before editing.
- Update the smallest useful docs. Do not create speculative docs.
- Verify with the narrowest docs or repo checks available.
What to update
- README usage, setup, or quick start when user-visible behavior changes.
- API docs when parameters, outputs, errors, side effects, or examples change.
- Architecture docs when boundaries, data flow, ownership, deployment units, or
major trade-offs change.
- Agent instructions when skills, agents, hooks, commands, tools, routing, or
operating rules change.
- Generated catalogs only through their source files and generator scripts.
- Code comments/docstrings only when they add useful contract or reasoning value.
Rules
- No promotional filler.
- No dead, future, or speculative behavior.
- No ADRs or
docs/adr/ changes unless explicitly requested.
- Keep private paths, secrets, tokens, and internal credentials out of docs.
- Prefer runnable examples. If an example cannot be run, state why.
- For human docs, favor a compact diagram over paragraphs only when the diagram
improves understanding.
- For agent docs, optimize for token efficiency over visual appeal.
Verification
Run the narrowest relevant checks, for example:
markdownlint-cli2 '**/*.md'
make lint-markdown
make validate
Also run documented commands or examples when practical. If a check is missing or
not practical, state the reason and run the closest available check.
Output
Write-capable role:
## Documentation Update
Updated:
- `path` — <what changed and reader served>
Verified:
- <check>: passed | skipped (<reason>)
Issues: none | <remaining issue>
Read-only role:
## Proposed Changes
### Change 1: <brief description>
File: `path/to/doc`
Action: CREATE | MODIFY | DELETE
Reader: human | agent | code
Code:
<doc content or patch-sized replacement with enough context>
Rationale: <code fact that makes this stale or missing>
Failure handling
- Ambiguous scope: ask one scoped question.
- Missing changed-file context: inspect
git diff --name-only; if unavailable,
ask for paths.
- No stale docs found: say so and report what was checked.
- Docs/code conflict: report the conflict; update docs to code unless user says docs are intended contract.
- Validation failure: report the exact failure and do not claim docs are current.
1---2description: Create or update human-facing docs, agent-facing instructions, architecture3 docs, API docs, README content, and useful code comments from implementation facts.4 Use when docs are stale, missing, or must reflect code changes. NOT for code-quality5 review, prompt scoring, speculative docs, or ADRs unless explicitly requested.6name: documenting-code7metadata:8 source: https://skillmd.com/skills/alexei-led/documenting-code9---1011# Documenting Code1213Update only useful documentation. Start from code facts, identify the reader, and14make the smallest doc change that helps that reader act correctly.1516## Role-gated action1718Detect capability from tools, not prose:1920- Write-capable role: edit docs and run validation.21- Read-only role: apply nothing; emit proposed edits in the output contract.2223## Reader model2425Choose the reader before writing.2627Human reader:2829- Make docs scannable: clear title, short overview, focused sections, examples.30- Keep docs short. Link to detail instead of creating long reads.31- Use Mermaid diagrams only when they answer a real structure, flow, lifecycle,32 ownership, or trade-off question.33- Match the existing docs style. Do not invent fonts, colors, or custom visual34 treatment unless the docs system already supports it.3536Agent reader:3738- Write terse operational instructions for LLMs.39- Prefer headers, bullets, numbered steps, and exact contracts.40- Remove generic knowledge, duplicate rules, pretty formatting, diagrams, tables,41 long rationale, and advice the model already knows.42- If the task is to review or score agent instructions, use `reviewing-instructions`.4344Code reader:4546- Comments and docstrings explain contracts, constraints, invariants, side47 effects, error behavior, and non-obvious decisions.48- Delete comments that paraphrase code.49- Avoid comments in tests unless they explain non-obvious external behavior or50 why an edge case matters.5152## Language references5354Load only references matching changed implementation files:5556- C# /.NET: `references/csharp.md`57- Go: `references/go.md`58- Java/Kotlin: `references/java-kotlin.md`59- Python: `references/python.md`60- Rust: `references/rust.md`61- TypeScript: `references/typescript.md`62- Web: `references/web.md`6364Mixed languages: load each matching reference. Unknown language: use this file65only.6667## Workflow68691. Identify scope from the user request or changed files. Do not ask if scope is clear.702. Read relevant implementation, tests, and existing docs before writing.713. Decide reader type: human, agent, code reader, or mixed.724. Check docs against current behavior. Code wins unless the user says docs define the intended contract.735. Use `looking-up-docs` only when external API syntax or behavior is uncertain.746. Use one bounded read-only subagent only for large doc audits; verify its claims before editing.757. Update the smallest useful docs. Do not create speculative docs.768. Verify with the narrowest docs or repo checks available.7778## What to update7980- README usage, setup, or quick start when user-visible behavior changes.81- API docs when parameters, outputs, errors, side effects, or examples change.82- Architecture docs when boundaries, data flow, ownership, deployment units, or83 major trade-offs change.84- Agent instructions when skills, agents, hooks, commands, tools, routing, or85 operating rules change.86- Generated catalogs only through their source files and generator scripts.87- Code comments/docstrings only when they add useful contract or reasoning value.8889## Rules9091- No promotional filler.92- No dead, future, or speculative behavior.93- No ADRs or `docs/adr/` changes unless explicitly requested.94- Keep private paths, secrets, tokens, and internal credentials out of docs.95- Prefer runnable examples. If an example cannot be run, state why.96- For human docs, favor a compact diagram over paragraphs only when the diagram97 improves understanding.98- For agent docs, optimize for token efficiency over visual appeal.99100## Verification101102Run the narrowest relevant checks, for example:103104```bash105markdownlint-cli2 '**/*.md'106make lint-markdown107make validate108```109110Also run documented commands or examples when practical. If a check is missing or111not practical, state the reason and run the closest available check.112113## Output114115Write-capable role:116117```markdown118## Documentation Update119120Updated:121122- `path` — <what changed and reader served>123124Verified:125126- <check>: passed | skipped (<reason>)127128Issues: none | <remaining issue>129```130131Read-only role:132133```markdown134## Proposed Changes135136### Change 1: <brief description>137138File: `path/to/doc`139Action: CREATE | MODIFY | DELETE140Reader: human | agent | code141142Code:143<doc content or patch-sized replacement with enough context>144145Rationale: <code fact that makes this stale or missing>146```147148## Failure handling149150- Ambiguous scope: ask one scoped question.151- Missing changed-file context: inspect `git diff --name-only`; if unavailable,152 ask for paths.153- No stale docs found: say so and report what was checked.154- Docs/code conflict: report the conflict; update docs to code unless user says docs are intended contract.155- Validation failure: report the exact failure and do not claim docs are current.