Adding one 5-token skill costs 47,544 tokens
Not because the skill is expensive. Because touching anything Claude Code caches throws away the cached prefix, and the next session pays to rebuild all of it.
Measuring what CLAUDE.md costs left an obvious question unanswered: 7,379 tokens for a 28KB CLAUDE.md is a lot, but is it charged once or on every message?
Once, mostly. A warm session re-reads it from cache for a fraction of the price. The thing that actually costs you is not the file’s size, it is changing it.
A warm session is 14.6x cheaper than a cold one
Four identical invocations in a row, same project, same 28,028-byte CLAUDE.md:
| Run | Cache created | Cache read | Reported cost |
|---|---|---|---|
| 1 (cold) | 50,442 | 15,636 | $0.512 |
| 2 | 0 | 66,078 | $0.033 |
| 3 | 0 | 66,078 | $0.033 |
| 4 | 0 | 66,078 | $0.033 |
Runs 2 through 4 are identical to the token. The first run pays to build the cache; every run after it reads the same 66,078 tokens back at roughly a fifteenth of the cost.
So the honest version of yesterday’s finding is: a large CLAUDE.md costs its full token price when the cache is cold, and about a tenth of that when it is warm. It is still charged on every single message, just cheaply.
One character undoes all of it
Appending a single x to a 28KB CLAUDE.md:
| State | Cache created | Cache read | Reported cost |
|---|---|---|---|
| Warm | 0 | 66,078 | $0.033 |
| After a 1-character edit | 47,544 | 18,543 | $0.485 |
| Next run | 0 | 66,087 | $0.033 |
Reproduced twice. One byte of change costs 47,544 tokens of cache recreation and a 14.6x jump in reported cost for that run. The next run is warm again.
Note that 18,543 tokens survive every invalidation. That is the stable prefix ahead of the changed content, and it stays cached. Everything after it is rebuilt.
Adding a 5-token skill costs exactly the same
This is the part worth internalising. A minimal skill costs about 1.5 tokens of listing space, five at most. Adding one to a warm project:
| Change | Cache created | Reported cost |
|---|---|---|
| Add one small skill | 47,543 | $0.485 |
| Remove that skill | 47,540 | $0.485 |
| Edit CLAUDE.md by one character | 47,544 | $0.485 |
All within about five tokens of each other. The size of the change is irrelevant. Invalidation is all-or-nothing on the cached prefix, so a five-token skill and a five-thousand-token rewrite cost precisely the same to apply.
What does not invalidate the cache
Two controls, both important, because “everything busts the cache” would be a much less useful finding:
| Action | Cache created | Invalidated? |
|---|---|---|
touch CLAUDE.md, content unchanged |
0 | No |
| Write an unrelated file in the project | 0 | No |
The touch result means invalidation is content-hashed, not modification-time based. Rewriting a file with identical content costs nothing, which matters if your tooling regenerates config files on every run.
The unrelated-file control confirms this is specifically about what goes into the cached prefix, not about filesystem activity in general.
What this changes about how you work
The practical rule is that config changes are the expensive operation, not config size.
If you are tuning a CLAUDE.md or installing skills, batch the edits. Ten separate one-line changes, each followed by a session, cost ten full re-caches. The same ten changes made at once cost one.
It also reframes the advice from the previous measurement. Moving a runbook out of CLAUDE.md and into a skill still saves its per-session token weight, but do it in one pass rather than incrementally, because each intermediate state charges you a full rebuild.
And if you have tooling that rewrites CLAUDE.md or regenerates a skills directory on every run, check whether it produces byte-identical output when nothing has changed. If it does, you pay nothing. If it reorders a key or restamps a date, you pay 47,544 tokens every time.
Scope and caveats
The absolute numbers here are for one specific project: a 28,028-byte CLAUDE.md on Claude Code 2.1.224, running claude-opus-5[1m] at the standard service tier. Your cached prefix will be a different size, so your creation figure will differ. The structure of the result, that any change costs a full rebuild of everything after the stable prefix, is what carries over.
total_cost_usd is the API-equivalent cost Claude Code reports for the run. On a subscription it is a notional figure rather than a charge, but it is the right number to reason about if you are billed per token.
Every figure reproduced across at least two runs, with warm and cold states measured back to back in the same batch.