generate-docs

Generate Docs

Turn the knowledge produced by a unit of work into developer documentation a contributor can read on the project's docs website — incrementally, as a by-product of shipping, so a public repo's docs stay current instead of rotting. A commit says what changed; a guide says how to use it ("how do I create a domain event and where do I register its handler").

Turn contract — verify before ending the turn

✓ The docs adapter was resolved through the Step 0 detection checklist and the
  outcome (adapter name, or NOT CONFIGURED) is stated in the report
✓ Every generated/updated page is WRITTEN to disk (paths listed in the report)
  and carries the provenance frontmatter — or zero pages were written and the
  report says exactly why
✓ The verify step was RUN (docs build command or link check) and its result
  pasted — never assumed
✓ Artifact language: explicit user instruction > the project's declared docs
  language > English. The CONVERSATION language never decides
✓ The fixed report block is printed, then the closing `→ Next:` block, as the
  ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

After finishing a unit of work — execute-phase recommends this skill at close-out when the project declares a docs site: document what the unit changed while the context is fresh.
On demand for a specific area: generate-docs src/domain/events/.
--review — export the latest review-change report as a docs page so humans can review findings from the website.
Not for writing SPECs/planning docs (plan-feature), session journals (log-session), or reviewing code (review-change produces the findings; this skill only publishes an existing report on request).

Progressive loading — resolve the docs route

The reference allowlist is exactly the three paths below. Read them in this order; every selected resource is normative and one hop from this entrypoint.

Every invocation: read adapter discovery and resolve the adapter with evidence. NOT CONFIGURED stops writing.
Configured adapter only: before choosing any output path or format, read adapter slots.
Read generation process and execute the scope, incrementality, map/review, verify, and report steps.

Do not load steps 2–3 after NOT CONFIGURED. Missing required resource → stop; never guess an adapter, output path, or fixed contract.

Allowed & forbidden (fixed lists — no interpretation)

Allowed:

Writing/updating pages under the adapter's guides location
Updating only the adapter's declared manual sidebar config when the adapter table requires it
Running the declared docs build/verify command
Reading anything (diff, code, docs)

Forbidden — never, even if it "would help":

Whole-project doc regeneration (the incrementality checklist is the only page selector)
Editing source code, tests, or any config other than the adapter's declared manual sidebar config
Scaffolding a docs site (installing Astro/Starlight, creating configs)
Writing outside the adapter's content locations, except that declared manual sidebar config
Pages without the provenance frontmatter
Committing or pushing (the unit's workflow owns the commit)

Return exactly

GENERATE DOCS — adapter: <starlight|docusaurus|markdown|NOT CONFIGURED> — scope: <scope>

| Page | Action | Source-unit | Subject paths |
|---|---|---|---|
| <content-path> | created|updated | <NN-slug> | <paths> |

Map: regenerated (<command>) | n/a — no map command declared | invalid output — <reason>
Review export: <page path> | not requested | no report available
Verify: <command + exit code | links checked: <n>, broken: 0 | n/a — not configured>
Pages: <n> written, <n> skipped by incrementality checklist
Decision: PASS | FAIL | NOT-CONFIGURED

FAIL only when the verify step is red or a written page had to be reverted; NOT-CONFIGURED per Step 0.5; PASS otherwise (including 0 pages).

Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables:

No slash-command menu — where this skill says /<skill>, open that skill's SKILL.md and follow it literally in a fresh conversation.
No per-skill model:/effort: — writing guides is structured summarization over a diff: a mid-tier model suffices; never below the tier that can read the project's language accurately.
No argument passing — state the scope in the invocation message ("generate docs for 01-generate-docs"); the Process step 1 order still applies.

Relationship to other skills

execute-phase recommends this skill at unit close-out when the documentation map declares a docs site (hand-off via → Next: — never composed in-turn).
audit-docs detects orphan/stale generated pages via the provenance frontmatter.
init-workspace records the Docs site declaration this skill's Step 0 reads.
Not a review: findings/quality belong to review-change.

Done when

The adapter outcome is stated with evidence; every selected page is written with provenance frontmatter; the verify step ran and is green (or the NOT-CONFIGURED report was printed and nothing was written).

The fixed report block was returned, then:

→ Next: commit these pages with the unit's close-out (they ride the unit's PR)
  · unit already closed → commit as docs(<unit>): generated guides on the unit's branch
  · adapter NOT CONFIGURED → add the Docs site block to the documentation map, then re-run /generate-docs