Progressive Disclosure: Why Skills Beat CLAUDE.md for Procedures

The argument for moving procedures out of CLAUDE.md and into skills is not just architectural cleanliness. There is a concrete token cost attached to where you put things, and that cost compounds with every session your agent runs.

One data point anchors the math: a 944-token skill costs approximately 53 tokens in a session where it is not invoked.

How the Skill System Works

When Claude Code loads a session, it registers your skill library by reading the description of each skill — typically a short paragraph at the top of the skill file. The description is the only content loaded at session start. The full skill content is deferred until the agent decides it needs that skill.

When the agent encounters a task that matches a registered skill, it requests the full content. At that point the 944 tokens load. Not before.

This is progressive disclosure: the description is the advertisement, and the full content only loads when purchased.

The economics:

Skill in CLAUDE.md:       944 tokens × every session = 944 tokens/session
Skill registered (used):  53 (desc) + 944 (content) = 997 tokens  ← slightly more
Skill registered (unused): 53 tokens × every session = 53 tokens/session

The crossover happens when you have multiple skills and not all of them fire in every session. In practice, that is almost always the case.

The Cumulative Math

Ten skills averaging 944 tokens each:

Configuration	Token cost per session
All 10 skills in CLAUDE.md	9,440 tokens
All 10 registered, 3 invoked per session	530 (desc) + 2,832 (3 × 944) = 3,362 tokens
All 10 registered, 1 invoked per session	530 (desc) + 944 (1 × 944) = 1,474 tokens

At 100 sessions per day, the CLAUDE.md approach costs 944,000 tokens daily for skills alone — before any actual work happens. The registered approach with typical invocation rates runs at roughly 15-35% of that.

This is not a rounding error. It is a structural cost that scales linearly with your skill library size and your agent's run frequency.

Skill Discovery: How the Agent Chooses

The agent determines which skill to invoke by reading descriptions against the current task. The description acts as a routing signal. This means your description quality directly affects invocation accuracy.

A weak description: "Deploy things."

A strong description: "Deploy a service to the production server over SSH. Handles PATH export, docker compose rebuild, and post-deploy verification. Use when deploying any backend service to production."

The strong description tells the agent exactly when to reach for this skill. The weak one leaves it ambiguous. An ambiguous description means the skill either fires when it shouldn't (wasted tokens) or fails to fire when it should (missed execution).

Write descriptions as invocation conditions: "Use this skill when X." The agent is pattern-matching against task descriptions — give it a clean pattern to match against.

The Recursive Build Loop

Skills get better with use, but only if you capture what you learn from each execution.

The loop:

1. Walk it — describe the procedure in a skill file, as best you understand it
2. Run it — invoke the skill against a real task on a real system
3. Fail it — the skill will fail or produce incomplete output on first use. This is expected.
4. Codify it — update the skill from the failure. What assumption broke? What step was missing?

By iteration 3, the skill reflects real execution rather than remembered procedure. By iteration 5, it handles edge cases you didn't anticipate when you wrote version 1. This is why skill provenance matters — a skill with no execution history is a skill with no failure record, which means it hasn't been stress-tested yet.

The recursive loop is also how you maintain skills: when a procedure changes (new tooling, new deployment target, changed API), you walk it again, run it again, fail it again, codify it again. The skill stays current with the system it describes.

The Anti-Pattern to Watch For

The failure mode is adding procedures to CLAUDE.md under the reasoning "I want to make sure the agent always knows this."

That reasoning is correct in intent but wrong in implementation. The agent does not need to know a procedure at session start — it needs to know the procedure when the relevant task comes up. That is exactly what skill registration provides. The agent has the description (the signal that the procedure exists) loaded at session start. The full content loads precisely when the task matches.

Adding procedures to CLAUDE.md "to make sure" treats the description layer as unreliable. It usually isn't — the description just needs to be written clearly. Write a good description, register the skill, and trust the system to load it when it's needed.

The exception: if a procedure is so foundational that it shapes every action the agent takes in every session, it may belong in CLAUDE.md. Branch protection rules are an example — not a procedure to invoke, but a constraint on all behavior. Everything else is a candidate for progressive disclosure.

Practical Implementation

The migration from CLAUDE.md procedures to skills is low-effort:

# Create the skill directory and its SKILL.md
mkdir -p ~/.claude/skills/deploy-mac-mini
cat > ~/.claude/skills/deploy-mac-mini/SKILL.md << 'EOF'
---
name: deploy-mac-mini
description: Use this skill when deploying any backend service to the production server. Handles Homebrew PATH export, docker compose rebuild, and liveness verification.
---

# deploy-mac-mini

## Steps
...
EOF

The format matters: each skill is a directory under ~/.claude/skills/ containing a SKILL.md with name and description frontmatter. A bare .md file dropped directly into skills/ does not register.

That's it. The skill is now registered. The next session will load only its description (53 tokens). The full content loads when the agent encounters a deployment task.

Remove the corresponding section from CLAUDE.md. Your constitution gets leaner. Your agent gets smarter. The cost curve bends down.