CLAUDE.md vs Skills vs Hooks: Progressive Disclosure

A lean CLAUDE.md beats one giant context file because everything in CLAUDE.md is read on every task, so each extra line steals attention from the work at hand. Keep CLAUDE.md to the few rules that are always true. Put step-by-step "how to do X" detail into skills that load only when the task needs them — the on-demand layer that keeps your Claude Code setup focused. Let hooks enforce the non-negotiables in code. That split is progressive disclosure, and it is the single biggest reliability upgrade for a coding agent.

Why does a giant CLAUDE.md make the agent worse?

Because CLAUDE.md is loaded into the context window at the start of every session, before the model has even seen your request. A 50-line file is cheap. A 600-line file — with frontend conventions, release steps, three migration playbooks, and a style guide — is paid in full on a one-line typo fix.

Two things break. First, signal dilutes: the rule that actually matters for this task sits next to forty rules that don't, and the model weighs them roughly the same. Second, the file rots. Nobody re-reads 600 lines to check whether a rule is still true, so stale instructions linger and quietly contradict newer ones. You end up debugging your own documentation.

The honest version: more context is not more control. Past a point, it is less. In our experience building B2B sites with this stack, the agent gets more predictable as CLAUDE.md gets shorter — because what's left is only the stuff that's true everywhere.

What is progressive disclosure for a coding agent?

Progressive disclosure means the agent sees a small, always-true core up front, then pulls in deeper instructions on demand — only when the task calls for them. It is the same idea behind a good README that links to detailed docs instead of inlining all of them.

For a coding agent the three layers are: CLAUDE.md for always-on rules, skills for on-demand procedures, and hooks for enforced gates — together they form the agentic workflow that runs each task. CLAUDE.md answers "what is always true here?" A skill answers "how do I do this specific thing, the moment I need to?" A hook answers "what must never slip through, whether or not the model remembered?" Keep each layer in its lane and the agent reads less, stays focused, and is easier to correct when it drifts. This is the backbone of how we run our supervised research-plan-build-review-ship loop, covered in building websites with Claude Code.

What belongs in CLAUDE.md vs skills vs hooks?

Sort every instruction by one question: when does the agent need this? Always — it's CLAUDE.md. Only for certain tasks — it's a skill. Never optional, must be enforced — it's a hook.

A simple test: if you wrote a rule down and hoped the agent follows it every time, ask whether it should be a hook instead. Prose in CLAUDE.md is a request. A hook is a guarantee. The most reliable setups move their truly non-negotiable rules — no destructive git, no committing secrets, always run the build — out of hope and into hooks.

Why are skills better than one big instructions file?

Because a skill is loaded by relevance, not by default. The migration playbook only enters the context window when the agent is actually doing a migration. The rest of the time it costs nothing. That is the whole win: depth without weight.

Skills also have a name and a description, which means the agent can choose the right one instead of scanning a wall of text and guessing. You get cleaner routing, and you get reuse — the same skill works across every project that needs that job, while CLAUDE.md stays project-specific. We package our recurring jobs (fetch a site, set its look, plan content, build, run SEO) as skills for exactly this reason. The shape of that loop is in spec-driven development with Claude Code, and the team-of-helpers idea is in our Claude Code subagents explainer.

One caution, because honesty matters here: skills are not magic. A skill the agent never loads helps nobody. So the trigger — the description that tells the model when to reach for it — matters as much as the steps inside. Write the description for the task, not for yourself.

How short should CLAUDE.md actually be?

Short enough that you'd happily read the whole thing before every task — because that is exactly what the agent does. There's no hard line count, but a useful gut check: if you can't skim it in under a minute, it's doing two jobs and one of them belongs in a skill.

A healthy core file usually holds four things and nothing else: what the project is, the handful of hard rules that are always true, the safety constraints, and a short routing table that says "for this kind of task, load that skill." Everything that starts with "when doing X, here's how…" is a skill in disguise. The smell of a file that's drifting: it keeps growing, and every contributor adds "just one more important rule." When that happens, the fix is never a longer file — it's moving detail down a layer.

How do I migrate from a bloated CLAUDE.md without breaking things?

Do it in small, reversible passes rather than one big rewrite, and keep a human in the loop reviewing each step. The goal is to subtract safely, not to redesign everything at once.

1. Audit. Read the current file and tag each rule: always-true, task-specific, or should-be-enforced.
2. Extract skills. Move every "how to do X" block into its own named skill with a clear trigger description.
3. Promote hooks. Take the rules you can't afford the model to forget and implement them as hooks.
4. Slim the core. Leave only mission, hard rules, safety, and a routing table pointing at the skills.
5. Test on real tasks. Run your three most common workflows and watch what the agent reaches for.
6. Tighten. If it loaded the wrong skill, fix the description, not the steps. If it skipped a rule, that rule probably wanted to be a hook.

Assign one owner for this structure so it stays coherent, and revisit after any workflow that went sideways — the failures tell you exactly what to move.

FAQ

What is the difference between CLAUDE.md and a skill?

CLAUDE.md is loaded on every task and holds rules that are always true for the project. A skill is loaded only when its job comes up and holds the step-by-step procedure for that job. Use CLAUDE.md for "what's always true," and a skill for "how to do this specific thing."

Should hard rules live in CLAUDE.md or in hooks?

If a rule must hold every time regardless of whether the model remembered it, put it in a hook so it runs automatically. Prose in CLAUDE.md is a request the agent usually honors; a hook is enforced in code. Keep critical gates — build must pass, no destructive git, no secrets committed — as hooks, and use CLAUDE.md to explain the intent.

How long should CLAUDE.md be?

Short enough to read before every task, since the agent reads it on every task. There's no fixed limit, but if it keeps growing or takes more than a minute to skim, detail has leaked in that belongs in a skill. Continuous growth is a sign your routing is failing, not that you need a bigger file.

Does progressive disclosure slow the team down?

No — it usually speeds things up. The agent reads less per task, finds the right procedure faster, and drifts less, which means fewer correction cycles. The upfront cost is splitting one file into layers once; the ongoing benefit is a smaller, clearer core that's easier to maintain.

What if the agent never loads the right skill?

That's almost always a description problem, not a steps problem. The model picks a skill from its name and description, so write the trigger in the words of the task ("migrating WordPress to Next.js," not "the big move"). If a skill keeps getting missed, sharpen its description or add an explicit routing line in CLAUDE.md.

Can the same approach work for migrations and SEO work?

Yes. Package recurring jobs as skills with clear triggers — a WordPress to Next.js migration skill, an AEO skill for ranking in ChatGPT and Perplexity — and the agent loads each only when that work comes up. Your core stays lean while your depth grows in the layer that's free until it's needed.