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.

1. Every invocation: read adapter discovery and resolve the adapter with evidence. NOT CONFIGURED stops writing.
2. Configured adapter only: before choosing any output path or format, read adapter slots.
3. 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