CLAUDE.md vs hooks vs skills: the token-cost asymmetry nobody graphs

Not the hook definition. The settings.json block that registers a hook never enters the model's context. The hook script itself runs in your shell, not in Claude. What enters Claude's context is the JSON the hook writes to stdout when a matching tool event fires. A hook that emits 30 bytes on every Bash call adds 30 bytes × N Bash calls to that session's input tokens. A hook that emits nothing on allow and a one-line reason on block adds tokens only on the blocked calls. The 400-line script behind the hook is invisible to the model.

Partly. Every installed skill puts its name and description into a per-session listing that ships in the system prompt on every turn. Anthropic's docs put that at roughly 75–150 tokens per skill with the XML wrapper, and the default skill-listing budget is skillListingBudgetFraction = 0.01, about 2,000 tokens on a 200K Sonnet or Opus context. The SKILL.md body, the actual rules, is zero tokens until the model invokes the skill. After invocation it persists in context for the rest of that session.

All of it, every turn, no gating. Our analyzer codifies it: src/lib/analyzer.ts line 264 sets estimatedTokensFireEveryTurn = totalTokens. A 6,000-token CLAUDE.md adds 6,000 input tokens to every single API call for the life of the session. A 30-turn session is 180,000 input tokens of CLAUDE.md alone before any code is read.

Hooks, by a wide margin, for the right shape of rule. A rule like 'never run a destructive SQL command without --dry-run first' belongs on a PreToolUse hook against Bash and Edit. The settings.json entry is invisible to the model. The script does the regex match locally. On 'allow' it emits nothing. The model pays only when the hook actually blocks. Compare that to a CLAUDE.md sentence saying the same thing: it bills its full byte count on every turn, including the turns where the model is formatting a JSON response and not writing SQL at all.

Because the model reads it once during the invocation turn and then keeps it in the rolling context for the remainder of the session. If a skill body is 2,400 tokens and the skill fires on turn 8 of a 30-turn session, you pay 23 × 2,400 = 55,200 input tokens for that body across the remaining turns. That is the trap: a 'rarely fires' skill that fires once still bills its body 20+ times. The defense is to keep SKILL.md bodies short, the same way you would keep a CLAUDE.md short.

CLAUDE.md sits in the system prompt prefix and is cache-eligible if you don't bust the prefix with a date or 'today' string. The skill listing sits with it and caches the same way. Skill bodies enter mid-session, so they cache from invocation onward but not before. Hook stdout enters as tool-result content and is not part of the long-lived prefix cache; it gets compressed by autocompact rules instead. On a 30-turn session with prefix cache hits, the CLAUDE.md and skill-listing input costs drop by roughly 10x. Hook stdout cost does not.

Think of it as three different bills. CLAUDE.md bills bytes × turns. Skills bill listing-bytes × turns plus body-bytes × turns-after-invocation. Hooks bill emitted-stdout-bytes × matching-tool-events. Pick the bill that maps to how often the rule actually applies. Identity and stack apply on every turn, so CLAUDE.md is correct. Workflow recipes that apply when a specific kind of work is being done belong on skills. Pre-flight gates that apply when a specific tool is about to fire belong on hooks.

Sometimes. If the rule has the shape 'when the model is about to do X, check Y, possibly stop', it maps cleanly to a PreToolUse hook. The check runs in your shell with full access to the file system, git, and any binary you have installed. Rules of the shape 'in general, prefer X over Y' do not map to hooks because there is no tool event to attach them to. Those belong on CLAUDE.md or a skill, depending on how often they apply.

The CLAUDE.md side does: AGENTS.md, .cursorrules, and .grokrules all ship verbatim into the system prompt on every turn, the same way. The conditional sibling surfaces differ. Codex has its own skills concept but no hooks. Cursor has rule files and .cursorignore but no hook-equivalent shell trigger. Grok Build has .grokrules plus tool gating. The principle holds in all four hosts: rules that apply unconditionally belong on the always-on surface, rules that apply on a specific event belong on the surface that gates by that event. The hook surface is currently the deepest in Claude Code.

Paste any of the four agent-config files (CLAUDE.md, AGENTS.md, .cursorrules, .grokrules) into the textarea on ccmd.dev. The analyzer is one TypeScript file: src/lib/analyzer.ts. It reports totalTokens, estimatedTokensFireEveryTurn (always equal to totalTokens for CLAUDE.md and siblings), and a line-by-line list of findings: bloat (over 28 words), vague, aspirational, missing_why, cache_bust, duplicate. The paid tier monitors skill-listing growth, hook-stdout volume, and CLAUDE.md drift over time so you can catch which surface is silently growing.