Update Docs Skill
Update README.md files in the folders where code was changed. Documentation lives next to the code it describes — each component/abstraction folder has its own README.
When to Use
Activate this skill when:
- The user explicitly asks to update documentation after changes
- After completing a task that adds, removes, or significantly modifies files in a component/abstraction folder
Principles
- Co-located — Each README lives in the folder it documents
- Lean — Only document what helps a developer understand the folder's purpose, structure, and patterns
- Precise — Accurate file names, sizes, type counts, and descriptions
- Compact — No verbose prose. Use tables, bullet points, and code snippets
- Delta-driven — Only update sections affected by the change. Don't rewrite unrelated content
README Structure Convention
Each folder's README follows this skeleton (sections included only when relevant):
# folder-name/ - Short Purpose
One-sentence overview. Contains **N files**.
## Architecture
[Only if the folder has a non-obvious entry point, router, or coordination pattern]
## Components / Modules / Types
[Table or bullet list of files with one-line descriptions]
## Pattern
[Code snippet showing the common pattern, if one exists]What to Document
| Change Type | Documentation Action |
|---|---|
| New file added | Add entry to the file list with one-line description |
| File removed | Remove entry from the file list |
| File renamed | Update the entry |
| New pattern introduced | Add/update the Pattern section |
| Architecture change | Update the Architecture section |
| File count changed | Update the count in the overview line |
| New block/menu/popup type | Add to the relevant type list |
What NOT to Document
- Implementation details that are obvious from reading the code
- Function-level API docs (that's what the code and types are for)
- Changelog/history of what changed when
- TODO items or future plans
- Descriptions longer than one sentence per file
- Redundant information already in CLAUDE.md
Process
- Identify affected folders — Determine which folders had files added, removed, or significantly changed
- Read existing README — Check if a README.md exists in each affected folder
- Determine delta — Compare the change against what the README currently says
- Apply minimal update — Edit only the affected lines/sections
- Verify accuracy — Ensure file names, counts, and descriptions match reality
Scope Rules
- Only update READMEs in folders where code actually changed
- If a folder has no README yet and the change is significant (new subfolder, new abstraction layer), create one following the convention
- If the change is trivial (typo fix, minor logic tweak), skip documentation update
- Never update CLAUDE.md from this skill — that file has its own maintenance process
Examples
File added to block/
Change: Added `src/ts/component/block/ai.tsx`
Action: Edit `src/ts/component/block/README.md`
- Update file count in overview line
- Add entry under "Other Blocks":
- `ai.tsx` - AI-generated content blockNew store added
Change: Added `src/ts/store/theme.ts`
Action: Edit `src/ts/store/README.md`
- Add row to the Stores table:
| `theme.ts` | `S.Theme` | Theme management: color schemes, dark mode preferences |File removed from menu/
Change: Removed `src/ts/component/menu/legacySearch.tsx`
Action: Edit `src/ts/component/menu/README.md`
- Remove entry for legacySearch from the menu types list
- Update count if mentionedNew subfolder created
Change: Created `src/ts/component/block/ai/` with index.tsx, toolbar.tsx, preview.tsx
Action: Create `src/ts/component/block/ai/README.md`:
# ai/ - AI Content Block
AI-generated content blocks with toolbar controls and preview. Contains **3 files**.
## Files
- `index.tsx` - Main block component, renders AI content with edit/regenerate actions
- `toolbar.tsx` - Prompt input and model selection toolbar
- `preview.tsx` - Streaming preview of AI-generated content
Also update parent `src/ts/component/block/README.md` to reference the new subfolder.