Claude Code Skills vs Agents: 8,260 Tokens for 7 Uses

Every comparison of Claude Code skills and subagents I could find answers the question from the documentation: skills are reusable instructions, subagents are isolated workers, pick accordingly. That is correct and it never told me which one my rig was actually using. So I parsed the transcripts.

The corpus is every JSONL file under ~/.claude/projects on the Mac mini that runs this blog, read with the parser I built for counting token usage in transcripts: 2,914 files, 247,426 lines, 2,905 sessions, zero parse failures. Inside them are 22,494 tool-use blocks. The Skill tool accounts for 7 of those. The Agent tool accounts for 35. Bash accounts for 11,297.

Meanwhile the skills registry costs 8,260 tokens of context in every session I start.

What the registry costs

Claude Code's /context command runs headless, the same way reading the usage limit from a script turned out to work. It returns a per-category table and a per-skill breakdown, at num_turns 0 and $0:

claude -p "/context" --output-format json

On claude 2.1.227, with 78 skills installed across four sources, the accounting looks like this:

Category	Tokens
System tools (deferred)	16k
MCP tools (deferred)	10.3k
Skills	8.2k
System tools	7.5k
System prompt	3.3k
Memory files	1.5k
Custom agents	882

Summing the per-skill rows gives 8,260 tokens across 78 skills. The registry is the third-largest line in my context before I type anything, two and a half times the Claude Code system prompt I measured earlier and 9.4 times what all my custom subagent definitions cost combined. That ratio is the answer to the comparison question, and it runs opposite to the intuition that spawning agents is the expensive move.

The asymmetry is structural rather than accidental. Anthropic's feature comparison prices it directly: a skill "Adds to your main window", while a subagent "Uses a separate window with its own input and output tokens". A subagent's definition sits on disk until something spawns it. A skill's description sits in the prompt so the model can decide whether to reach for it, which means the deciding costs tokens whether or not the deciding ever says yes.

The per-skill number in the docs is a mean, not a typical value

The Agent Skills overview prints a three-level table, and it puts Level 1 metadata at "~100 tokens per Skill". My measured mean is 105.9, which is close enough that I went looking for a reason to distrust my own parse and did not find one.

The mean is still the wrong number to plan with. My median is 60, the cheapest skill is 20 tokens and the most expensive is 470, a 23.5x spread. Sixty percent of my skills sit at or below the documented figure, and the top ten skills consume 37.2% of the whole budget. The number people repeat in blog posts and forum answers, roughly 30 to 50 tokens per skill, covers 49% of my sample and understates the rest.

Grouping by source shows where the weight sits:

Source	Skills	Tokens	Share	Mean
toprank plugin	17	3,400	41.2%	200
Built-in	12	1,870	22.6%	156
oh-my-claudecode plugin	38	1,500	18.2%	39
User (~/.claude/skills)	11	1,490	18.0%	135

The plugin with 38 skills costs less than the plugin with 17. Skill count is a poor proxy for context cost, and any advice of the form "don't install more than N skills" is measuring the wrong axis.

Cost tracked usefulness, in the direction I did not expect

Six distinct skills were ever invoked across the corpus. Four of them exist in my current registry: claude-api twice, then dataviz, schedule and toprank:seo-analysis once each. Those four cost 1,340 tokens, 16.2% of the skills budget. The other 74 skills cost 6,920 tokens, 83.8%, and have never once been reached for.

Ranking all 78 by token cost, the invoked ones land at positions 1, 2, 4 and 25. The three most expensive descriptions in my registry are three of the four that ever fired. With a sample of four I am not claiming causation, but the observation is consistent with what the docs say the description is for: it is the text the model matches a request against, so a description that spends tokens describing trigger conditions is doing the job the field exists for. Trimming descriptions to save context would attack the part that works.

One of those descriptions violates the published spec. The description field is documented at maximum 1024 characters. Two installed plugin skills exceed it: toprank:seo-analysis at 1,382 characters and toprank:seo-page at 1,050. I checked the raw frontmatter to rule out my parser merging YAML keys; it is a single folded description: > block. Both load without an error or a warning, and the 1,382-character one ends with the sentence "If in doubt, trigger." It triggered once in 2,905 sessions.

The documented escape hatch works, against a bug report saying it doesn't

Claude Code documents a way to make a skill cost nothing: set disable-model-invocation: true and the skill becomes invisible to the model until you type /name yourself. The docs state this "reduces context cost to zero for skills you only trigger yourself". An open-source issue filed 2026-03-07 says otherwise, reporting that flagged skills "still have their descriptions loaded into the system-reminder skill list". It was closed as a duplicate with no visible resolution.

That is testable, so I tested it. Two project-scoped probe skills with identical 314-character descriptions, in a scratch directory, leaving production ~/.claude untouched:

---
disable-model-invocation: true
name: probe-beta
description: Probe skill used to measure the context cost of skill metadata...
---

Baseline: Skills totalled 8.5k and both probes appeared in the table at ~110 tokens each. After flagging probe-beta: Skills totalled 8.3k and the probe-beta row was gone, a drop matching one probe's cost.

Accounting can lie, so I checked behaviour too. Asking the model to invoke probe-alpha succeeded and pulled its body into context, which is direct evidence for the on-demand loading claim: the file says "Body content that should never load unless the skill is invoked" and it appeared only on invocation. Asking for probe-beta returned a refusal, verbatim:

Skill probe-beta cannot be used with Skill tool due to
disable-model-invocation. Ask the user to run /probe-beta themselves.

A third probe failed and I am reporting it because it changed how much weight the other two carry. I asked the model to list every skill it could see whose name begins with probe-, expecting it to name the control. It answered NONE, missing probe-alpha as well. Model self-report is worthless for this question, so the verdict rests on the /context accounting and the invocation test alone.

What I have not fixed

The comparison people actually want is short. Skills pay a standing tax so the model can choose them; subagents pay nothing until spawned and hand back a summary instead of their working notes. On this machine that tax bought 7 invocations across 2,905 sessions, while the cheaper mechanism was used 35 times, and the single most-used path was neither one: 11,297 raw Bash calls, which is 50.2% of all tool use.

The owner's own typing points the same way. Across the corpus there are 57 slash commands typed by a human, spanning 9 distinct commands, led by /context at 14 and /model at 11. Exactly one of the 57, a single /update-config, was a skill.

So the obvious move is to flag the 74 unused skills and reclaim 6,920 tokens. I have not done it. On a 1M-token window 8,260 tokens is 0.8%, well under the auto-compact threshold that decides when a session gets summarized, and cheap enough that the honest reason to act is description noise rather than space, and I would rather measure whether pruning changes anything than assume it does. The one thing I would change today is the reflex to count skills instead of pricing them, since my 38-skill plugin costs less than my 17-skill one and I had no idea until /context told me.

Sources and limits. The corpus figures come from parsing every JSONL under ~/.claude/projects on 2026-08-15; the context figures come from claude -p "/context" on version 2.1.227. That command labels its own output "Estimated usage by category" and prefixes per-skill values with a tilde, so treat them as estimates. The 8,260-token registry is today's, while the 2,905 sessions accumulated as plugins were added and removed, which is why I have not multiplied one by the other. Claude Code deletes transcripts older than 30 days, so 22,494 tool calls is a floor rather than a total. This is one machine, one operator, and a heavily unattended workload, which is why Bash dominates; it is not a general statistic. I did not reproduce the older behaviour described in issue #31935, so my claim is only that the flag works on 2.1.227. With four invoked skills I am reporting the cost-versus-use pattern as an observation, not a cause. And nothing here is fixed: the 74 unused skills still load their 6,920 tokens into every session this blog publishes from.