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 block

New 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 mentioned

New 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.