generate-docs
Generate, refactor, or update project documentation from source code or a git diff, auto-scaffolding a full docs/ hierarchy or applying targeted updates to existing docs. Use when user says "document
SKILL.mdskills/generate-docs/SKILL.md
GitHubGenerate Docs
Generate, refactor, or sync project documentation. One skill, two modes — chosen automatically from the state of the workspace and the intent of the request.
docs/ absent ──────────────► CREATE MODE (references/create.md)
docs/ present + diff/change ─► UPDATE MODE (references/update.md)
docs/ present, no diff hint ─► ASK the user which mode is meant
Critical Rule
Loading this skill's files. Reference files live under references/ in this skill's own directory. Resolve them relative to the skill directory — never the workspace root. When a step tells you to read a reference, read it completely (to EOF) before acting.
Shared content — writing standards, anti-patterns, the module CONTEXT.md symlink rule, and the quality checklist — lives once in references/shared.md. Both modes load it; never duplicate it into a mode file.
Mode Selection
- Check whether
docs/exists in the workspace. docs/does not exist → create mode. Nothing to sync yet; scaffold from scratch. Load references/create.md.docs/exists AND the request references a diff, patch, PR, or "changes to reflect" → update mode. Load references/update.md.docs/exists AND intent is ambiguous (no diff mentioned, no clear "regenerate everything" signal) → ask the user: "Do you want me to (a) regenerate/extend the docs from the current codebase, or (b) sync the docs with a specific set of changes?" Proceed with the mode they confirm.
Commands
| Trigger Pattern | Mode | Reference |
|---|---|---|
| "document the project", "write docs", "create a README", "generate architecture docs" | Create | references/create.md |
| "update the docs", "sync the docs with the diff", "reflect these changes in the documentation" | Update | references/update.md |
Anti-patterns to Avoid
See references/shared.md for the full list. In addition, specific to mode dispatch:
- ❌ Running create mode when
docs/already exists and a diff was clearly provided — that's update mode's job. - ❌ Running update mode when
docs/does not exist — there is nothing to update; use create mode. - ❌ Guessing the mode when genuinely ambiguous instead of asking the user.