| name | writing-docs |
| description | Use when writing or editing any documentation in this repo — READMEs, DESIGN.md, the implementation plan, reference docs, markdown files, module and function docstrings, and code comments. Defines what each kind of doc is for and how to write it. |
Writing docs
The documentation standards are the single source of truth in the project CLAUDE.md (§ "Writing
docs"), which is loaded every session — so they already apply to the docs you write while planning and
implementing, not just when this skill is invoked.
Invoke this skill to run a focused pass: review docs you have written or are editing against the
CLAUDE.md standards and revise where they diverge. Work through them in this order:
- Each doc has one job — does each doc answer its one reader's one question, and nothing else?
- The funnel — does each fact live at the highest altitude where it is that reader's concern, and
never repeat below it?
- The rules — explain don't list; concrete over abstract; justify every fact for its reader;
simpler is not shorter; plain English with no decoration; match the code's words; never hand-edit
generated docs (
docs/telemetry-reference.md).
Read the full standards (including the worked example) in CLAUDE.md before reviewing.
