What 1,000 skills actually cost you: 1,474 tokens

Skills are cheap. Not “cheap relative to their usefulness” cheap, but very nearly free, and considerably freer than the documentation implies.

claude -p --output-format json reports real token usage, so this is measurable rather than arguable. Total prompt tokens is input_tokens + cache_creation_input_tokens + cache_read_input_tokens.

The numbers

Configuration	Delta vs baseline
1 skill	+5
10 skills	+31
40 skills	+80
1,000 skills (3.9MB on disk)	+1,474

Against a baseline of roughly 58,300 tokens for an empty project, a thousand skills is a 2.5% increase. Marginal cost settles around 1.4 tokens per skill, which is about what a name costs.

Body size does not matter, at all

The documentation says a skill’s body “loads only when it’s used, so long reference material costs almost nothing until you need it.” That is true, and the margin is wider than “almost nothing” suggests:

Skill body	Delta
200 bytes	+5
28,000 bytes	+5

Identical. A 28KB body, roughly 7,000 tokens of text, contributes exactly zero to startup. Whatever reference material you want to park in a SKILL.md, park it. It costs nothing until invoked.

I also confirmed the body does not leak. Asked for a value that appears only in an uninvoked skill’s body, with instructions not to invoke or read anything, the answer was UNKNOWN. Invoked explicitly, the same skill returned the value on both runs.

Description length does not matter either

This is the part that surprised me. The docs describe a listing budget scaling at 1% of the context window, a 1,536-character cap on each entry’s combined description and when_to_use, and descriptions being shortened when the listing overflows. All of that implies description text consumes context in proportion to its length.

Measured, it does not:

Configuration	90-char descriptions	1,500-char descriptions
10 skills	+31	+31
40 skills	+80	+80

Forty skills carrying 60,000 characters of description text cost the same 80 tokens as forty skills carrying 3,600 characters. Both figures reproduced exactly.

What I could not determine

Descriptions clearly do reach the model. With five skills under opaque names (alpha, bravo, charlie…), where only charlie’s description mentioned aquariums, a request for “the aquarium code” returned charlie’s payload on two of three runs. So relevance matching works off description text that my measurement says costs nothing.

I do not know how both of those are true at once. It may be that the listing is delivered through a channel the reported usage does not count, or resolved lazily. I measured the cost, not the mechanism, and I am not going to guess at the mechanism.

Note also the 2-of-3. The third run declined to pick a skill. That inconsistency is why there is no claim here about how reliably relevance matching fires: it did not reproduce cleanly, so it is not a finding.

The methodology trap, which cost me the first set of numbers

My first pass produced a delta of negative 258 tokens for adding skills. Adding content appeared to remove context.

The baseline had moved. Measured at the start of the session an empty project reported 58,618 tokens; measured an hour later, with no skills present and nothing else changed, it reported 58,329. A 289-token drift with zero configuration difference, which is larger than most of the deltas being measured.

The relative deltas were fine throughout. One skill measured +5 before the drift and +5 after. Only the absolute anchor moved.

So: measure a paired baseline in the same batch as every configuration. Every number in this post was produced by wiping the skills directory, measuring, applying the configuration, and measuring again, back to back. Any token measurement quoted against a baseline captured earlier in a session is unreliable, and if you are benchmarking anything in Claude Code, that is the first thing to control for.

Practical upshot

Stop rationing skills. At 1.4 tokens each, the context argument against installing a large library of them does not survive contact with a measurement. Write long bodies, put real reference material in them, and give each one a description long enough to actually match on.

The real cost of a big skill collection is a crowded listing and the model picking the wrong one, not tokens.

All measurements against Claude Code 2.1.223, headless mode, reported usage from --output-format json.

---

Re-verified 2026-08-07 against Claude Code 2.1.224. The body-size and per-skill findings hold unchanged: a 200-byte body and a 28,000-byte body both still cost +5 tokens. The 1,000-skill figure measured +1,461 on 2.1.224, down 13 tokens from the +1,474 recorded here on 2.1.223. The conclusion is unaffected. Full re-run: every measurement on 2.1.224.

---

Superseded 2026-08-14, on Claude Code 2.1.231. Every measurement in this post was made without --setting-sources project, on a machine with its own configuration loaded, and that turns out to decide the answer. Run in isolation on a clean project, the same forty skills cost 1,570 tokens rather than 80, and description length is charged at 0.276 tokens per character rather than being free. Run on the configured machine, in the same round on the same version, forty skills cost 152: a 10.2x gap from the flag alone. So this post measured what a configured machine costs, which is real, rather than what a skill costs. Why a configured machine is cheap is not established, and the obvious explanation, that it already has enough skills to be past the point where the price collapses, is refuted by counting them. The body-size result is the one thing that held under both conditions. Full re-measurement and the control that found it: the same forty skills cost 1,558 tokens, or 152.