/generate-docs

name: generate-docs
user-invocable: true
version: 2.0.1
argument-hint: "[NN-slug | fix-n | path/glob] [--review]"
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Generate incremental, diff-driven developer guides through the project's
  detected docs adapter. Never regenerate the whole site, scaffold it, or edit
  source. Triggers: "generate-docs", "generate the docs", "document this unit".

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](references/ADAPTER_DISCOVERY.md) and resolve the adapter with evidence. `NOT CONFIGURED` stops writing. 2. Configured adapter only: before choosing any output path or format, read [adapter slots](references/ADAPTERS.md). 3. Read [generation process](references/GENERATION_PROCESS.md) 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 repo