The same 28KB costs 7,379 tokens in CLAUDE.md and 4 tokens in a skill

Re-verified 2026-08-11 on Claude Code 2.1.227, with one caveat about the headline number. The mechanism is unchanged and decisive. Measured with the floor and the configured arm in the same round, across four rounds, 28,000 identical bytes cost +7,617 tokens as a CLAUDE.md in three rounds of four and +7,328 in the fourth, where a 289-token baseline step landed between the two calls of the pair. As a skill body the same bytes cost +7 tokens in all four rounds.

But the multiplier is fragile, and that is worth saying plainly. It divides by a denominator of a few tokens. The original figures were 7,379 and 4, giving 1,845x. Today’s give 1,046.9x to 1,088.1x across the four rounds. The numerator barely moved and a three-token change in the denominator moved the ratio by roughly 40%.

This is not a claim that the version changed anything. The filler text used for the re-measurement is not the original text, and token density depends on content, so the two numerators are not strictly comparable. What the re-run establishes is the mechanism and the order of magnitude. The denominator has never been stable across this site’s own runs either: this post records the skill body at +4, while the 2.1.224 re-verification records it at +5 for the same 28,000-byte body, and today it read +7.

Read the headline as “three orders of magnitude”, not as a precise multiplier. Whether it is 1,000x or 1,800x does not change a single decision: reference material in CLAUDE.md is charged on every session, and the same bytes in a skill body are charged essentially nothing until something invokes them. The raw rounds are at reverify-2-1-227.json.

Take 28,000 bytes of project instructions. Put them in CLAUDE.md and they cost 7,379 tokens at startup. Put the identical bytes in a skill body and they cost 4 tokens. Both figures measured on Claude Code 2.1.224, both reproduced exactly across two runs.

That is a 1,845x difference for the same text, decided entirely by which file it lives in.

What a CLAUDE.md actually costs

Every row is a paired baseline: measure with no CLAUDE.md, write the file, measure again, back to back. Every figure below reproduced identically across two runs.

CLAUDE.md size	Cost at startup	Tokens per byte
~24 bytes (header only)	+106	—
2,000 bytes	+626	0.260
8,000 bytes	+2,185	0.260
28,000 bytes	+7,379	0.260

Two things fall out of that. There is a fixed overhead of 106 tokens for having a CLAUDE.md at all, before a single instruction is in it. And beyond that the cost is 0.26 tokens per byte, holding to three decimal places across a 14x range in file size. That works out to roughly 3.8 bytes per token, which is what ordinary English prose tokenises at.

So the arithmetic is easy to do in your head: a 10KB CLAUDE.md costs you about 2,700 tokens, every session, forever.

The same text in a skill costs nothing

The skills documentation says a skill’s body “loads only when it’s used, so long reference material costs almost nothing until you need it.” Measured against the alternative, “almost nothing” undersells it.

I generated one 28,000-byte block of instruction-shaped prose and placed it two ways:

Where the identical 28KB lives	Cost at startup
CLAUDE.md	+7,379 tokens
A skill body	+4 tokens

Both reproduced exactly, twice each. The skill figure is 4 tokens because that is roughly what the skill’s name and listing entry cost. The 28KB body itself contributes zero until something invokes it.

What this means for your project

The rule is not “write a shorter CLAUDE.md”. It is that CLAUDE.md and skills are priced completely differently, and most projects have them the wrong way round.

CLAUDE.md is charged on every session, whether or not any of it turns out to be relevant. That price is correct for things that must always be true: your conventions, your architecture constraints, the rules that shape every response.

A skill is charged when it is used. That price is correct for reference material: the deployment runbook, the API surface, the migration checklist, the long procedure you need once a fortnight.

If a section of your CLAUDE.md is a procedure rather than a fact, moving it into a skill takes its startup cost to approximately zero. At 0.26 tokens per byte, moving a 6KB runbook out of CLAUDE.md and into a skill saves about 1,560 tokens on every session you ever start.

You can put your own numbers in with the context cost calculator, which now takes CLAUDE.md size alongside skills and MCP tools.

How this compares to everything else measured here

Mechanism	Cost
One skill (name and listing entry)	~1.5 tokens
A skill’s body, any size	~0 tokens until invoked
One MCP tool, deferred	~15 tokens
One MCP tool, loaded upfront	~304 tokens
CLAUDE.md	0.26 tokens per byte, always

CLAUDE.md is the only item on that list with no lazy-loading escape hatch. It is also the one nearly every project has, and the one that tends to grow quietly over months.

A measurement I am not publishing

I tried to measure a 500-byte CLAUDE.md. Two runs gave +237 and −52 tokens.

A negative cost for adding content is obviously wrong. The cause is the same one that has bitten this site’s measurements before: the absolute baseline drifts by a couple of hundred tokens over a session, and at 500 bytes the expected signal is only about 236 tokens. The noise is larger than the thing being measured.

So there is no 500-byte figure here. Below roughly 2KB this method cannot separate signal from drift, and the honest move is to derive small-file costs from the per-byte rate rather than to measure them directly and quote a number that will not reproduce.

That is also why every figure above is a paired baseline captured in the same batch, and why each one was run twice before it was written down.

Measured on Claude Code 2.1.224, headless mode, usage from --output-format json, totalling input_tokens + cache_creation_input_tokens + cache_read_input_tokens.