Guide
Do agent Skills cost tokens? Progressive disclosure explained
Yes, and the cost is predictable: roughly 100 tokens of frontmatter per installed Skill at the start of every session, plus the Skill’s full instructions (under about 5K tokens) only on the tasks that trigger it, plus bundled files only if it opens them. This three-tier design — metadata always, instructions on demand, files on demand — is why installing a detailed Skill usually costs less than pasting the equivalent prompt yourself, and why installing fifty Skills you never use is still a real bill.
Updated August 19, 2026 · first published August 19, 2026
At a glance
Side by side
| Tier | What it is | When it loads | Typical size |
|---|---|---|---|
| 1. Metadata | The SKILL.md frontmatter: name and description | Every session, for every installed Skill | ~100 tokens |
| 2. Instructions | The SKILL.md body | Only when a task matches the description | Under ~5K tokens |
| 3. Bundled files | Reference docs, templates, scripts | Only when the Skill opens or runs them | Unbounded — the Skill decides |
Why the design saves money rather than costing it
The alternative to a Skill is not free. It is you re-explaining the same procedure in a prompt each time, or a giant always-on instructions file that every request pays for. A Skill converts that constant cost into a conditional one: you pay the detail only on the tasks that need it.
That is what makes a 4,000-token review playbook economical. Used on one task in twenty, its amortised cost is a fraction of the same text living in an always-read file — while being more detailed than anything you would tolerate in an always-read file.
Where the cost actually bites
Tier 1 is the one to watch, because it scales with how many Skills you install rather than how many you use. Fifty installed Skills is roughly 5,000 tokens on every single session before you have asked anything. On an agent that ships a large pre-installed bundle, that floor exists whether you chose it or not.
The second cost is subtler and worse: triggering precision. When many descriptions overlap, the agent has to choose between them and sometimes chooses wrong — loading a plausible Skill instead of the right one. Pruning is not only a token optimisation; it makes triggering more accurate.
On the Claude API the arithmetic is explicit and per call, so a Skill attached to a high-volume endpoint is a line item you should measure before shipping rather than after.
Writing a Skill that is cheap to own
The token model rewards a specific shape, and it is the same shape that makes a Skill trigger reliably.
- Make the description precise, not long
- It is the only part always in context. Name the concrete artefacts and situations that should fire it — vague verbs cost the same tokens and match worse.
- Keep the body under ~5K tokens
- If it is longer, the extra belongs in bundled reference files the Skill opens when needed.
- Split reference material by symptom
- One file per case, rather than one large document, so a triggered Skill reads only the page it needs. The best-engineered vendor Skills all do this.
- Prefer a script over prose instructions
- A bundled script that runs is far cheaper than instructions describing how to write that code every time — and deterministic besides.
FAQ
Common questions
How many tokens does one Skill cost?
About 100 tokens of metadata per session while installed, whether or not it fires. When it does fire, add its body — typically a few thousand tokens — plus any bundled files it opens.
Is it bad to install a lot of Skills?
It has two costs. Tokens: every installed Skill contributes metadata at every session start. Precision: overlapping descriptions compete, so the wrong Skill fires more often. Five to fifteen well-chosen Skills usually beats fifty.
Do Skills use tokens when they never trigger?
Yes — their metadata does. That is the trade the design makes: a small constant cost so the agent knows what is available, in exchange for loading the expensive part only on demand.
Are Skills cheaper than MCP servers?
They are not comparable. A Skill is text loaded into context; an MCP server exposes tool definitions, which also cost context, and then performs real calls. Many workflows use both — the Skill supplies the method, the server the capability.
Related
Keep reading
- Anatomy of a SKILL.md →
The frontmatter and structure the loading model depends on.
- How to create a Skill →
Write one that triggers reliably and stays cheap to own.
- Skill vs MCP vs plugin →
Why these primitives complement rather than replace each other.