# Update Docs

> Update README documentation in the folder of changed components/abstractions to reflect code changes — keeps docs lean, precise, and in sync

- Skill: `anyproto/update-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add anyproto/update-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anyproto/update-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: anyproto (https://skillmd.com/u/anyproto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/anyproto/update-docs

---


# 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

1. **Co-located** — Each README lives in the folder it documents
2. **Lean** — Only document what helps a developer understand the folder's purpose, structure, and patterns
3. **Precise** — Accurate file names, sizes, type counts, and descriptions
4. **Compact** — No verbose prose. Use tables, bullet points, and code snippets
5. **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):

```markdown
# 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

1. **Identify affected folders** — Determine which folders had files added, removed, or significantly changed
2. **Read existing README** — Check if a README.md exists in each affected folder
3. **Determine delta** — Compare the change against what the README currently says
4. **Apply minimal update** — Edit only the affected lines/sections
5. **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.
```