Cutting a CLAUDE.md without losing a fact

A CLAUDE.md is loaded in full into every session started under it, so its size is a recurring tax, not a one-off cost. ~/.claude/scripts/claude-md-weight.sh measures every file on the machine and owns the size threshold — read the number there, never re-type it in prose. (Restated numbers are exactly what that script measures.)

The four buckets

Sort every paragraph. This is the whole method.

Refinements that decide the hard cases:

• A measured-wrong rule stays. "This looks like an obvious improvement but was measured to be wrong" is a guard, because without it a session re-derives the wrong belief from the same evidence. State it as a rule, never as a story.
• Money-path, auth and secrets rules stay, always.
• The measurement itself goes to the skill. The rule is the guard; the falsifying control, the numbers and the retraction narrative are domain knowledge.
• When a belief here turns out wrong, delete the wrong sentence. Do not strike it through and explain. Keep a retraction only where a future session would independently re-derive the wrong belief from the same evidence.
• Never hand-type a count, an inventory or a file list. Derive it, or omit it. This construction has drifted repeatedly — "eighteen scripts" when there were nineteen, "Eight plugins" when there were ten, a plist count written from memory.
• Each script is the source of truth for its own numbers (retentions, weights, thresholds, tiers). Prose describes them and must never restate them.

An extracted skill only helps if something loads it

A skill loads when the model decides to invoke it. So the line that survives in CLAUDE.md must name the skill AND the situation. Copy this shape:

Scheduled jobs and ~/.claude/scripts/: load the scheduled-jobs skill before creating, editing, moving or diagnosing any of them. It holds the reasons; jobs-inventory.sh derives the current state.

A bare "see the X skill" is not a trigger and will not fire.

Skill frontmatter: name kebab-case (prefix with the repo name for a project skill); description naming the situation that should trigger it, not just the topic.

Prerequisite 1 — a wholesale .claude/ gitignore silently voids the work

A project skill written under a repo that ignores .claude/ wholesale is untracked and lost on a fresh clone. Narrow first to .claude/agent-memory/, agent-memory-local/, worktrees/, then prove both directions:

git check-ignore -v .claude/skills/x/SKILL.md   # must report NOTHING
git check-ignore -v .claude/agent-memory/x      # must STILL report a match

Per-agent memory must never become tracked. See memory-and-plans.

Prerequisite 2 — a CLAUDE.md can be a load-bearing input to a check

Documentation here is sometimes parsed. Before moving or deleting a section:

grep -rn "CLAUDE\.md" scripts src bin tools .github 2>/dev/null

Split the hits into comments that mention it (repoint the prose) and code that reads it (repoint the path). After repointing, corrupt the moved artifact on purpose and confirm the verifier goes red — a check that now reads a file with no matching section can throw, pass vacuously, or match nothing, and only the deliberate failure tells you which.

Measured in vigie: scripts/verify-strata.mjs parses a CLAUDE.md section and pins its bolded rows against the @keyframes in tokens.css. Moving the section made npm run verify throw, while npm test and astro build both stayed green.

Verification — line coverage, and make it fail once first

Every substantive original line must appear in the new CLAUDE.md or in a skill.

git show HEAD:CLAUDE.md > /tmp/before.txt   # BEFORE editing
# after:
while IFS= read -r line; do
  [ ${#line} -lt 40 ] && continue
  grep -qF -- "$line" CLAUDE.md .claude/skills/*/SKILL.md 2>/dev/null \
    || printf 'UNCOVERED: %s\n' "$line"
done < /tmp/before.txt

-F and -- are not optional. Without them grep silently mis-parses any line starting with - and reports garbage — that bug produced a fake clean pass once.

Then delete a known sentence and confirm it is reported. A check that has never produced the opposite answer is not evidence.

An uncovered line is not automatically a bug — a deleted count or a deleted retraction story is a correct uncovered line. But you must be able to name the bucket for every one.

The method that has worked twice

Move the reasoning into skills; keep only what a session must see unprompted. Nothing is deleted except hand-typed counts and archaeology. Project skills live at <repo>/.claude/skills/<name>/SKILL.md; machine-wide ones at ~/.claude/skills/<name>/SKILL.md.