Docs Writer

Use this skill to produce or update the documentation a project keeps in docs/ (or wherever the project's convention points): the material a new contributor, an on-call engineer, or a future maintainer reaches for when the code alone doesn't answer their question.

Scope — what this skill owns vs. neighbors

Several other skills already own specific document types. Don't duplicate them — call them out or hand off instead:

This skill owns everything else that lives in docs/:

• Architecture overviews — how the system fits together, its major components, data flow, key design decisions in prose (linking out to individual ADRs rather than re-litigating them)
• Setup / onboarding guides — how a new contributor gets the project running locally
• Module / component docs — what a subsystem does, its responsibilities, how it's invoked, its internal structure
• API reference docs — endpoints, request/response shapes, error codes (for internal or external consumers reading Markdown, not generated OpenAPI output)
• Operational runbooks — how to deploy, roll back, debug a known failure mode, or respond to an incident for a system that's already built

If a request is really "write me a README" or "record this decision," say so and point at the right skill instead of stretching this one to cover it.

Before writing

Read before writing — a doc that contradicts the code is worse than no doc:

1. Read the code, not just its interface — the actual behavior, not what a docstring claims it does.
2. Check for an existing doc on the same topic. Update it in place (preserving anything still accurate) rather than creating a competing second file. Grep docs/ for related filenames and headings first.
3. Check the project's own conventions — an existing docs/ structure, a doc-style guide, or patterns in neighboring files — and match them over anything below. This skill's templates are a fallback for projects with no established convention, not a house style to impose everywhere.
4. Identify the reader. A setup guide is written for someone with zero context on this repo; an architecture overview is for someone who already knows how to code but not this system; a runbook is for someone mid-incident with limited patience for exposition. Calibrate explanation depth to that reader, not to how much you know.

Where files go

Default layout when the project has no established convention:

docs/
├── architecture/       # system overviews, data flow, major subsystems
├── guides/              # setup, onboarding, how-to
├── reference/           # module/API reference docs
├── runbooks/            # operational procedures, incident response
└── adr/                 # owned by adr-writer — don't write here directly

Pick a kebab-case.md filename that names the subject, not the doc type (payments-service.md, not payments-architecture-doc.md). If the project already has a flatter or differently-organized docs/, follow that instead of imposing this tree.

If docs/ doesn't have an index/landing page and the project would benefit from one (more than ~3 docs), offer to create or update docs/README.md linking to what exists, grouped by category.

Writing the doc

Pick the closest template from references/ and adapt it — none of these are fill-in-the-blank forms, they're a starting shape:

Cross-cutting rules that apply to all of them:

• State the why, not just the what. Code already shows what a function does; a doc earns its keep by explaining why the system is shaped this way, what it's optimized for, what a reader would otherwise have to reverse-engineer.
• Write for durability. A doc gets read long after the session that produced it — don't reference "the current fix," "the refactor we just did," or anything else that only makes sense with today's context. State the invariant, not the history that produced it.
• Prefer a diagram over a paragraph of spatial description. When a data-flow, sequence, or component-relationship claim would take a paragraph of "X talks to Y which then calls Z," reach for mermaid-diagrams (or c4-architecture for system-level structure) instead — link or embed it rather than describing it in prose.
• Link, don't restate. If an ADR already explains why a decision was made, link to it instead of re-explaining the tradeoffs. If the README already has the quick-start, link to it instead of duplicating it.
• Show real interfaces. Pull actual function signatures, endpoint paths, config keys, and error names from the code — don't invent plausible-looking placeholders.
• Keep it current or say so. If a section describes something that's mid-migration or known to be incomplete, say that plainly rather than presenting it as settled.

After writing

• If you created a new file under docs/, check whether it should be linked from docs/README.md (or equivalent index) and from the repo's root README.md docs section, if one exists.
• If the doc describes something the project's ENGINEERING_PRACTICES.md-style conventions say should have an ADR (a major architecture, persistence, auth, or deployment choice) and none exists yet, mention that to the user rather than silently folding decision rationale into the doc — that's adr-writer's job.

Inputs

• The subject to document (a system, module, workflow, or subject area) and, if known, which category it falls into (architecture / setup / reference / runbook)
• Read access to the relevant source code and any existing docs on the topic
• The project's docs location, if it differs from docs/

Outputs

• One or more Markdown files under docs/ (or the project's equivalent), following the closest template in references/, cross-linked with related existing docs