Reduce skill token usage

How a skill loads

Claude Code's docs add three details. The description text in the skill listing is cut at 1,536 characters. A skill set to disable-model-invocation keeps its description out of context. And once a skill has loaded, its content stays in context for the session; after automatic compaction, re-attached skills share a 25,000-token budget, with the first 5,000 tokens of each.

Estimate your own

Paste a SKILL.md and see its always-loaded and on-trigger cost against the recommended limits. It uses the scanner's estimator and runs in your browser.

What real skills cost

The free ProSkills skills, measured on the files they ship with. Always-loaded is the name and description. On trigger is the SKILL.md body. On demand is every other text file in the folder.

Before and after

Same skill, same information. On the left the 120-row error table sits inside SKILL.md. On the right it moved to error-codes.md, and the body points to it in one line. Both are made up for this page. The numbers are the scanner's.

The trigger cost fell from 6,494 to 173 tokens. The reference file still costs 6,329 when it is read, and that happens only for tasks that need a code.

Six ways to cut

1. Make the description exact. Cut anything that is not a trigger phrase or what the skill produces.
2. Move tables, catalogues and long examples into reference files, one level below SKILL.md.
3. Delete advice a capable agent already follows. A rule it would obey without being told is pure cost.
4. Say each thing once. Repeated reminders at the top and the bottom double the cost.
5. Keep one worked example, not five. Put extras in an examples file.
6. Turn off auto-invocation for skills you only run by name, where your tool supports it.

For a whole-setup audit that finds token waste across instructions files, skills and tools, see Context Diet ($9). To compare where each kind of instruction loads, read skills vs CLAUDE.md vs MCP.

Sources

• Agent Skills specification: progressive disclosure
• Claude Code: skills (description budget, compaction)

Questions

How many tokens does a skill use?

Two amounts. The name and description sit in context all session, usually around 100 tokens or less per skill. The SKILL.md body loads only when the skill triggers, and the spec recommends under 5,000 tokens. Reference files cost nothing until they are read.

Does an unused skill cost tokens?

Yes, a little. Its name and description are listed so the agent can decide when to use it. That is why a short, exact description matters more than a long one, and why many installed skills add up.

How are tokens counted here?

The estimator divides characters by four and rounds up. That is the same method the scanner uses. It is within about 10 percent of real tokenizers for English and code, so use it to compare drafts, not to bill anything.

What is the fastest way to cut a skill down?

Move any table, catalogue or long example into a reference file, and name that file in SKILL.md with a line on when to open it. The content stays, but it stops loading on every trigger.

Keep reading

• Skill ScannerScore any skill in your browser. Nothing is uploaded.
• SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
• Progressive disclosure for skillsThree levels of loading and how to split a skill across them.
• Skills vs CLAUDE.md vs MCPWhen each loads, what it costs in context, and which to reach for.
• All guidesEvery guide, grouped by what you are trying to do.