| name | claude-md |
| description | Keep CLAUDE.md current and lean — capture this session's durable learnings into it (default), or `audit` it for stale commands, drift, and bloat. Enforces the line budget either way. |
| argument-hint | [audit?] |
| disable-model-invocation | true |
CLAUDE.md loads every turn for every developer; this skill is how it earns that. Two modes: default captures learnings from the current session; audit checks the whole file against reality.
Capture (default)
Scan THIS conversation for durable, project-level learnings. A learning qualifies only if ALL of these hold:
- It would prevent a repeat mistake. The user corrected you, a command failed in a non-obvious way, or a constraint surprised you.
- It's not derivable from the code. Claude can re-discover file structure and signatures; it can't re-discover "the staging DB is the one named
prod_replica".
- It's durable. True next month, not just this task. Session-specific state belongs in
/catchup handoff, not here.
- It's not already covered by CLAUDE.md, a rule in
.claude/rules/, or enforced by a hook.
For each qualifying learning (usually 0-3 per session — finding none is a fine outcome):
- Draft it as ONE line, with the why if it isn't obvious:
Use \make test-fast` for iteration — `make test` spins up Docker (3 min).`
- Pick its destination: command fixes → Commands section; constraints with a path scope → suggest a path-scoped rule instead; everything else → the matching CLAUDE.md section.
- If it contradicts an existing line, propose editing that line, not appending a second truth.
Present all candidates with AskUserQuestion (multiSelect — let the user pick which to keep), then apply only the selected ones.
Audit (when $ARGUMENTS contains audit)
Check every line of CLAUDE.md against reality:
- Commands: does each documented command still exist (
package.json scripts, Makefile targets, etc.) and match its description? Run --help/--dry-run variants where cheap.
- Paths and names: do referenced directories, files, and tools still exist?
- Duplication: lines that repeat
.claude/rules/ content, hook-enforced behavior, or standard conventions Claude already knows — propose deletion.
- Leftovers: any
> REPLACE: template blocks — propose deletion.
- Staleness candidates: claims contradicted by recent code (cross-check anything that smells off against the source).
Report findings as a table (line → problem → proposed fix/deletion), confirm, apply.
Budget check (both modes, always last)
grep -cv '^[[:space:]]*$' CLAUDE.md
Under 25 non-blank lines = healthy. 25-50 = list the longest sections, propose trims. Over 50 = the additions don't go in until something comes out — propose the trade explicitly ("add line X, delete lines Y-Z").
Rules
- NEVER write without user confirmation.
- Adding is guilty until proven innocent: every line must pay for itself every session.
- One line per learning. If it needs a paragraph, it belongs in a rule or in docs, with at most a pointer here.
- Don't touch
CLAUDE.local.md — that's the user's personal space.
