Context Footprint — What a Large Skill Library Actually Costs¶

Audience: Toolkit maintainers, and anyone who has heard "this toolkit has too many skills — it must blow up the context window." Scope: How Claude Code loads skills and agents, what the toolkit actually costs in tokens (measured 2026-07-21), and where the real weight is. TL;DR: The common worry — "125 skills means Claude reads 125 skills every time" — is a misconception. Progressive disclosure means you pay for descriptions always and bodies only on invocation. The real weight is in agent descriptions and fat skill bodies, not the skill count.

The claim¶

"The workflow tool is too big. With so many skills, using the workflow fills up the context fast, because Claude has to read all those skills."

It is a reasonable intuition, and it is half right. But the specific mechanism — "Claude reads all the skills" — is not how Claude Code works, and the half that is right points at a different culprit than skill count.

How Claude Code actually loads skills: progressive disclosure¶

Claude Code does not load every SKILL.md into context at session start. It uses progressive disclosure, on two levels:

Always loaded — each skill's and agent's one-line name + description (the YAML frontmatter). This is a compact catalogue the model scans to decide which skill to invoke.
Loaded only on invocation — the full SKILL.md body (often several hundred lines). It enters context only when that specific skill runs.

So a library of 125 skills is 125 one-line descriptions in the always-on catalogue — not 125 full skill files. You pay the full body cost only for the handful of skills you actually invoke in a session.

The measured numbers (2026-07-21)¶

Always-on (every session, before you type anything)¶

Component	Count	Description tokens
Skills	125	~6,800
Agents	55	~14,000
Total always-on		~20,800 tokens

Context for scale: ~20,800 tokens is roughly 10% of a 200k window, or ~2% of a 1M window. The 125 skills' share of that is only ~6,800 tokens (~3% of 200k). Adding or removing 20 skills shifts the always-on cost by ~1,000 tokens.

Per-run (full `SKILL.md` bodies — load only when invoked)¶

Phase	Body tokens
activate	7,700
2-plan	7,000
3-build	6,700
4-review	13,300
5-finalize	8,300
Full `activate→finalize` chain	~43,100 tokens

Average skill body: ~2,800 tokens. Largest: 4-review at ~13,300.

Where the weight really is¶

Three findings, each of which redirects the concern away from "skill count":

Skill count is the smallest lever. All 125 skills cost ~6,800 tokens always-on. That is the least expensive part of the system. Pruning skills for context reasons buys very little (there are better reasons to prune — see below).
Agent descriptions are 2× the skill descriptions. 55 agents cost ~14,000 tokens always-on because agent descriptions are verbose — several carry multi-paragraph <example> blocks. A single fat agent description can outweigh the ten fattest skill descriptions combined.
The "fills up fast" feeling is the invoked bodies, not the count. A full workflow run loads ~43,000 tokens of SKILL.md bodies — because the files are long (avg ~2,800 tokens; 4-review is ~13,300), not because there are 125 of them. This scales with how many phases you run, not how big the library is.

Conclusion: the toolkit is heavier than it needs to be — but the weight is in agent descriptions and fat skill/agent bodies, not the skill count. "125 skills" is the wrong number to worry about.

The full set of levers¶

Reducing context cost is a program, not a single edit. In rough order of value:

Lever	Targets	Status
Body diet — trim verbose `SKILL.md` bodies	the ~43k per-run load (biggest)	proposed (see intake)
Description diet — token budgets on descriptions, agents first	the ~21k always-on tax	proposed (see intake)
Retire dead skills — evidence-based keep/retest/retire	count and body load	SPEC-156
Scope manifest — don't list product-irrelevant skills	always-on catalogue	SPEC-123
Description optimisation — sharpen trigger accuracy	wrong-skill selection (a quality cost, not a size one)	SPEC-098 US3

Note that "retire skills" (SPEC-156) helps for quality reasons (a skill that does not beat the base model is dead weight — see The Case Against Skills) far more than for context reasons. Do not conflate the two arguments.

Reproducing these numbers¶

The measurements above are estimates at ~4 characters per token, computed from the source of truth (plugins/core-standards/skills/*/SKILL.md frontmatter and plugins/core-standards/agents/**/*.md). To re-run after any change:

python3 - <<'PY'
import re, glob, os
def desc(p):
    t=open(p,encoding='utf-8').read()
    if not t.startswith('---'): return ''
    fm=t[3:t.find('\n---',3)]
    m=re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:\s|\Z)', fm, re.S|re.M)
    return (m.group(1).strip().strip('"\'') if m else '')
sk=[len(desc(p)) for p in glob.glob('plugins/core-standards/skills/*/SKILL.md')]
ag=[len(desc(p)) for p in glob.glob('plugins/core-standards/agents/**/*.md', recursive=True) if desc(p)]
print(f"skills {len(sk)}: ~{round(sum(sk)/4)} tok | agents {len(ag)}: ~{round(sum(ag)/4)} tok | always-on ~{round((sum(sk)+sum(ag))/4)} tok")
PY

Measuring against real tokenizer counts (rather than the 4-char heuristic) would tighten the figures; the heuristic is accurate enough for the order-of-magnitude argument this chapter makes.

How to talk about this with a skeptic¶

Separate library size from per-run load. They are different numbers; conflating them is the whole misconception. The library can be large and cheap.
Lead with the measurement, not the reassurance. "Here is the always-on footprint and a typical per-run load" beats "trust me, it's fine."
Concede the valid kernel. The toolkit does carry avoidable weight (agent descriptions, fat bodies), and there is an active program to trim it (this chapter's levers, SPEC-156, SPEC-123).
Point at the evidence loop. SPEC-098 (benchmark) and SPEC-156 (keep/retest/retire audit) mean skills are measured for uplift and retired when they stop earning their keep — a stronger answer to a skeptic than defending all 125.