Skills Beat Your 40-Page Brain Dump

(Spine Ch. 13.)

“Documentation is like term insurance: It satisfies because almost no one who subscribes to it depends on its benefits.” Alan J. Perlis, Epigrams on Programming, ACM SIGPLAN Notices 17:9, epigram 71 (1982)

Page 19 said run the canary. Page 27 said how to title an incident. The agent nailed page 27. Every time. Beautiful incident titles, perfectly capitalized, filed against outages it caused by skipping page 19. Thirty pages in the repo root, loaded on every single run, and the one instruction that would have stopped the bleeding was sitting right there in the window being politely outvoted by on-call etiquette. Every team I know has a version of that doc. Mine ran past page 10 years ago, and I kept adding to it, which is roughly the plan a drowning man has when he asks for more water.

Bottom line: A playbook the agent loads on purpose beats a 40-page CLAUDE.md it pretends it read. Skills (small, task-specific instruction bundles loaded when the job calls for them) win on every axis that matters: relevance, freshness, auditability. The mega-doc in the repo root is where instructions go to be ignored at scale.

When it bites

Your CLAUDE.md grows past page 10 and the agent starts following the parts it likes and spacing on the rest. I wrote a CLAUDE.md that opened with “be concise” and then went on for another nine pages about it.
Two tasks need contradictory instructions (terse commit messages vs verbose release notes) and the single doc serves both badly.
You update guidance and can’t tell which runs used the old version, because everything loads everything, always.
A new hire asks “which part of the doc matters for my task” and the honest answer is “nobody knows anymore.”

Why the brain dump fails

The mega-doc fails for the same reason the mega-prompt fails (Ch. 8) and the undifferentiated bucket fails (Ch. 12): undifferentiated soup. Forty pages of always-loaded instructions means:

1. Everything competes with everything. Attention is finite. Page 31’s deploy policy dilutes page 2’s stop rule. The instruction you needed is present and outvoted: the worst kind of missing, because a grep says it’s there.

2. Contradictions accumulate. Long docs contradict themselves; that’s entropy, not negligence. “Always ask before deploying” on page 6, “never block on reversible work” on page 29 (Ch. 60). The model resolves the contradiction per-run, nondeterministically. Your policy is now a coin flip. I shipped both of those sentences myself, 23 pages apart, and then spent an afternoon blaming the model for being inconsistent. The doc was inconsistent. I was the doc.

3. Nothing versions. The doc is one blob: no per-task history, no rollback for one workflow without touching the others. Guidance evolves per task at different speeds; the blob forces lockstep.

4. Nobody audits 40 pages. Not the model, not the humans. In 2005 the internet decided Chuck Norris had counted to infinity twice; nobody has ever read a 40-page CLAUDE.md once. Ask me what’s on page 34 of my own and I will confidently tell you something that is not on page 34 of my own. Length is where stale instructions hide (Ch. 58’s warning about slop applies to your own docs first).

None of this is a new idea, which is the embarrassing part. ClickHouse’s incident-response guide says a runbook should fit on one screen, be written for a stressed engineer at 3am, be tied to one alert, and get pruned after every incident that used it, because “a runbook whose first three steps are automated is three steps of noise.” That is a skill. They just called it a runbook and shipped it before I figured it out. The ops world solved this for humans on pagers and I was still stapling pages together for a model with a smaller attention span than the on-call.

The pattern

A skill is: a name, a trigger (when it loads), the procedure, and its own eval. Nothing else.

One job per skill. “How we write commit messages” is a skill. “How we engineer software” is a brain dump wearing a skill costume. If it covers two jobs, split it.
Trigger explicitly. The agent loads it because the task matches (by router, Ch. 16; by path; by keyword), not because it’s always in the window. Unloaded skills cost zero attention.
Procedure, not prose. Steps, checks, examples of good output. The test of a skill: a new agent (or a new hire) produces acceptable output reading ONLY this skill. If it needs the mega-doc too, the skill isn’t done.
Short enough to audit. If you won’t re-read it quarterly, it’s too long. Skills rot like everything else; short ones rot visibly. My ralph-loop skill (~/.agents/skills/ralph-loop/SKILL.md, 2.0K on disk, last touched 16 August 2026) is the whole outer loop of Ch. 14 in two kilobytes: it defines the idle check, caps the run at 100 iterations, and makes the agent state a truthful completion promise before it is allowed out. Two kilobytes, one job, one exit condition. There is no honest version of that file that runs thirty pages.
Eval per skill. Each bundle gets its own pass/fail check (Part VII). The mega-doc has one eval: vibes. Skills have many: verdicts.

What this is not: 400 micro-skills nobody can find, which is the failure mode I sprinted into next, because I am nothing if not thorough about hitting both walls. Discovery is part of the design: an index, a naming convention, a router that knows the catalog. Skills you can’t trigger are brain-dump pages with extra steps.

One worked example

I have run this split. I did not instrument it, which is the part I want back, so read the next four sentences as my memory and not as a measurement. A deploy runbook. Before: 30 pages in the repo root, loaded every run, holding deploy steps, rollback steps, naming conventions, on-call etiquette and incident templates. The agent routinely skipped the canary check on page 19 while perfectly formatting incident titles from page 27. Attention bingo. After: five skills (deploy-canary, deploy-rollback, commit-format, incident-file, oncall-handoff), each loaded by trigger, each with its own three-line eval.

My recollection is that the canary stopped getting skipped once the canary skill loaded WITH the deploy task and contained nothing else. I can’t hand you a percentage, because 2026 me was too busy feeling clever to log one. Note the thing that did not happen: those 30 pages never got rewritten. They got split and triggered, and every piece came out shorter than the whole used to be. The words weren’t the problem. Loading all of them at once was.

The quiet failure that pwned me

The loud failure is the 200-page doc nobody reads. The quiet failure is subtler:

You split the doc into skills and load them ALL anyway.

Auto-loading the full catalog every run rebuilds the brain dump with extra file I/O. The loading discipline IS the pattern: trigger, relevance, absence by default. A skill library with eager loading is a mega-doc with a directory listing. Guess who did this. I split my 40 pages into a tidy set of skills, felt great about it, and then loaded all of them on every run because what if the agent needed one. Same 40 pages, more files, extra disk reads, and a smug feeling I had not earned. Chuck Norris can load the entire catalog every run and still have attention left over. You cannot. I am not Chuck Norris, I am the n00b who mistook a directory listing for a design.

Second quiet failure: skills that duplicate instead of reference. Five skills each pasting the same auth setup, drifting apart over quarters, until three of them are teaching your agent to log into a service that got renamed last spring. Shared primitives go in shared includes; skills stay deltas. DRY applies to your agent’s brain too.

Do / don’t

One job per skill. Split on contradiction, version cadence, or trigger, whichever cracks first.
Trigger by task, default to unloaded. Absent skills cost nothing.
Write procedures a stranger could execute. Steps, checks, good-output examples.
Eval each skill separately. Small bundles, sharp verdicts.

Don’t

Don’t duplicate shared setup across skills. Reference, don’t paste.
Don’t skip the index. Untriggerable skills are dead pages.

Where this sits in the book

Part I closes here: split the work (Ch. 8), dress the steps (Ch. 9), mind the wrapper (Ch. 11), budget the bucket (Ch. 12), and bundle the know-how into loadable skills instead of a monument doc. Part II opens next with the loop itself: Ralph, the outer loop that doesn’t dare stop (Ch. 14).

Sources and receipts

Thesis is Jeremy’s (skills over mega-docs), kept as practitioner claim, consistent with Ch. 8/12/57.

Verified:

ralph-loop skill file (idle-check loop, 100-iteration cap, required truthful completion promise), 2.0K, modified 16 August 2026, ~/.agents/skills/ralph-loop/SKILL.md (local, unpublished)
ClickHouse engineering guide, “Incident response process” (runbook fits one screen; written for a stressed engineer at 3am; tied to one alert; “a runbook whose first three steps are automated is three steps of noise”), accessed 9 September 2026, https://clickhouse.com/resources/engineering/incident-response-process

Open:

Canary-runbook worked example: printed as Jeremy’s recollection, explicitly not a measurement. Nothing public substitutes; the ClickHouse guide names the decay problem but publishes no before/after figures.
No external papers claimed; mechanism argued from attention-budget + Ch. 12, with the ClickHouse runbook guidance as the ops-world precedent.
Cross-refs kept honest: Ch. 8 (decompose), Ch. 12 (bucket budget), Ch. 16 (trigger routing), Ch. 20 (stop rules per skill), Ch. 58 (subtract slop), Ch. 60 (contradiction exhibit), Part VII (per-skill evals).