| name | update-documentation |
| description | Align all documentation layers to code after implementing a feature, adding a config key, new CLI command, new flag, or any other change. Use this skill whenever you've finished writing code and need to make sure docs are complete and consistent — including internal specs (docs/), public website (website/), LLM ingestion files (llms-full.txt), and the project memory file. Invoke proactively after any non-trivial code change, not just when the user asks.
|
Update Documentation
Run inline — do NOT spawn a subagent. Your live context of what changed is the primary
input. Delegating forces a lossy re-briefing and causes gaps.
Doc Map
Each row is a file and what it owns. Use this to reason about which files are affected by a change.
| File | Owns |
|---|
docs/SPEC.md | Authoritative algorithm steps, flags, output formats, error conditions for every command |
docs/UX.md | Prompt flows, decision matrices, flag interaction examples, sample terminal output |
docs/ARCH.md | Module list with one-liner APIs, data flow, tech decisions |
docs/ROADMAP.md | Phase status — mark phases complete here |
docs/SECURITY.md | Threat model, scan pipeline, chunking strategy |
packages/core/src/config.ts → DEFAULT_CONFIG_TEMPLATE | TOML shown to users on first run — must match schema |
website/guide/getting-started.md | First-install flow, scope, basic agent symlinks intro |
website/guide/installing-skills.md | Install behavior end-to-end: sources, scope, agent symlinks (incl. "skipped when" lists), conflict handling, multi-skill, security, flags, remove, link |
website/guide/configuration.md | Config wizard UX, TOML keys by section, example blocks |
website/guide/security.md | What skilltap scans for, thresholds, semantic scan |
website/guide/taps.md | Tap add/remove/list/update, tap.json format |
website/guide/creating-skills.md | SKILL.md format, frontmatter, verify command |
website/reference/cli.md | Every command: synopsis, flags table, behavior notes, examples |
website/reference/config-options.md | Every config key: type, default, description, full TOML example |
website/public/llms-full.txt | Generated — never edit directly. Regenerate with cd website && bun scripts/gen-llms-txt.ts after any guide or reference page changes. |
website/public/llms.txt | Manually maintained page-level index (llms.txt standard). Links to guide and reference pages — not individual commands. Update only when a new page is added/removed, the site description changes, or the Optional section changes. |
~/.claude/projects/…/memory/MEMORY.md | Phase key notes, gotchas, stable patterns for future sessions |
Rules
1. Grep before reading.
Search the changed feature's name across docs/ and website/ to find gaps and stale text.
Read only the relevant section (offset+limit), not the whole file.
2. Reason from the map.
For each piece of changed behavior, ask: which files in the map own that area? Check those.
Don't limit yourself to a fixed checklist — a change often touches multiple categories.
Examples:
- Install prompt flow change →
SPEC.md, UX.md, installing-skills.md, cli.md
- New config key →
config.ts template, SPEC.md, UX.md, configuration.md, config-options.md
- New command →
SPEC.md, UX.md, cli.md, relevant guide page(s)
- Prompt gains/loses a skip condition →
UX.md decision matrix, guide page "skipped when" list, cli.md notes
3. Guide pages own the narrative.
website/guide/ pages are where users learn behavior — update prose, code block examples, and
condition lists. website/reference/ pages need their tables kept accurate. Both matter.
4. Regenerate llms-full.txt if any website/guide/*.md or website/reference/*.md changed.
cd /home/nathan/dev/skilltap/website && bun scripts/gen-llms-txt.ts
This concatenates all pages in sidebar order into a single Markdown file for AI bulk ingestion. The script is the source of truth for page order — if a new page is added, add it to PAGES in website/scripts/gen-llms-txt.ts.
5. Update llms.txt only when page structure changes.
website/public/llms.txt is a manually maintained index following the llms.txt standard. It lists pages — not individual commands or flags. Update it when:
- A new guide or reference page is added or removed
- The site tagline / description changes
- A link in the Optional section needs updating
Do not update it for: new commands on existing pages, new config keys, flag changes, or content edits within an existing page.
6. Update MEMORY.md for new stable patterns, gotchas, or completed phases.
Keep it under 200 lines — be terse, put detail in a topic file if needed.
