Documentation
Trigger phrases: "documentation", "docs", "update README", "API docs", "write docs", "document it", "write usage"
Goal: the docs must match the code. Wrong/stale docs are worse than no docs (they inspire trust and mislead).
Trigger: when a public API, command, configuration, or user-visible behavior changes.
When it is mandatory
- A public function/endpoint/CLI signature or behavior changed.
- A new feature, configuration key, or environment variable was added.
- The install/run steps changed.
- A breaking change was made (also coordinate via
release/CHANGELOG).
Checklist
How
- Identify the changed surface — extract the public signature/behavior diff from the diff.
- Find the right doc — README,
docs/, docstring, OpenAPI, command --help. If there is more than one, update them all.
- Write: what it does · how it is called (example) · input/output · limits/error cases. Short and correct.
- Verify the examples — does the command/code example actually run.
- Clean up the old — delete references to removed APIs/parameters.
- Translation: if the user-visible doc is multilingual, coordinate with
i18n-integrity.
Principles
- Single source — behavior lives in the code; the doc explains it, does not copy it (a copied doc goes stale).
- Example > paragraph — a working example beats three paragraphs.
- Minimal — don't write a giant doc no one will maintain; answer the most-asked question.
Co-authoring a longer doc (guide, tutorial, README rewrite)
For a substantial doc the content lives in the author's head, not the diff — don't guess it. Interview for intent
and audience, draft in passes, and let the user steer before you polish. The collaborative workflow (audience/intent
questions, outline-first, section-by-section drafting, revision loop): references/coauthoring.md.
Invariant rules
- Correctness > completeness — don't write a wrong doc; if unsure, flag it/ask.
- Examples must work.
- Leave no stale/dead docs.
- No secret/real credential — use a placeholder (aligned with §4).
- Don't repeat the code — don't just copy the signature; explain the usage.
1---2name: docs-writer-33description: |4 Keeps documentation in sync with the code: README, usage and related docs when a public API or behavior5 changes. Leaves no dead or misleading docs behind.6metadata:7 source: https://skillmd.com/skills/byerlikaya/docs-writer-38---910# Documentation1112<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->13Trigger phrases: "documentation", "docs", "update README", "API docs", "write docs", "document it", "write usage"1415Goal: the docs must **match the code**. Wrong/stale docs are worse than no docs (they inspire trust and mislead).16Trigger: when a public API, command, configuration, or user-visible behavior changes.1718## When it is mandatory19- A public function/endpoint/CLI signature or behavior changed.20- A new feature, configuration key, or environment variable was added.21- The install/run steps changed.22- A breaking change was made (also coordinate via `release`/CHANGELOG).2324## Checklist25- [ ] Docs are up to date for the changed public surface26- [ ] Examples **work** (copy-paste tested / mentally traced)27- [ ] Dead/misleading wording removed (no leftover old name/parameter)28- [ ] New configuration/env documented (default + whether required)29- [ ] Scope minimal — not a repetition of the code, but "why/how to use it"30- [ ] No secret/real credential in the docs (use a placeholder)3132## How331. **Identify the changed surface** — extract the public signature/behavior diff from the diff.342. **Find the right doc** — README, `docs/`, docstring, OpenAPI, command `--help`. If there is more than one, update them all.353. **Write**: what it does · how it is called (example) · input/output · limits/error cases. Short and correct.364. **Verify the examples** — does the command/code example actually run.375. **Clean up the old** — delete references to removed APIs/parameters.386. **Translation**: if the user-visible doc is multilingual, coordinate with `i18n-integrity`.3940## Principles41- **Single source** — behavior lives in the code; the doc *explains* it, does not copy it (a copied doc goes stale).42- **Example > paragraph** — a working example beats three paragraphs.43- **Minimal** — don't write a giant doc no one will maintain; answer the most-asked question.4445## Co-authoring a longer doc (guide, tutorial, README rewrite)46For a substantial doc the content lives in the author's head, not the diff — don't guess it. Interview for intent47and audience, draft in passes, and let the user steer before you polish. The collaborative workflow (audience/intent48questions, outline-first, section-by-section drafting, revision loop): **`references/coauthoring.md`**.4950## Invariant rules511. **Correctness > completeness** — don't write a wrong doc; if unsure, flag it/ask.522. **Examples must work.**533. **Leave no stale/dead docs.**544. **No secret/real credential** — use a placeholder (aligned with §4).555. **Don't repeat the code** — don't just copy the signature; explain the usage.