update-documentation

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.