Skill Audit: can Claude actually read your skills? 4 steps (check the budget, /skill-doctor, cut, raise)

skill-audit.md

Skill Audit: can Claude actually read your skills?

Claude Code puts a short list of your skills into every conversation: each skill's name plus its description. Claude uses the description to decide which skill fits your request.

That list has a budget: 1% of the model's context window (Claude Code docs, "Skill descriptions are cut short"). When your skills don't fit, Claude Code keeps every name but drops descriptions, starting with the skills you use least. A skill without a description has no words Claude can match against, so it only runs when you type /its-name.

My setup on 30 Sep 2026: 118 skills, 59,112 characters of descriptions, a 30,000 character budget. 66 skills were listed by name only. 87 had never been used.

Needs Claude Code v2.1.252 or later for step 2 (claude --version).

---

Step 1: Check if you're over budget (30 seconds)

claude --debug -p "ok" > /dev/null 2>&1
grep "Skill listing over budget" ~/.claude/debug/latest

No output: you fit, stop here. A line like this means descriptions are being cut:

[WARN] Skill listing over budget: 118 skills, 59112 chars > 30000 budget — descriptions will be truncated.

Step 2: See what each skill costs and whether you use it

Inside Claude Code, run:

/skill-doctor

It lists every skill with its context cost, how often it ran, and when it last ran. Skills showing < 20 in the context column are already down to their name. The footer tells you how many were never invoked and where to turn them off.

Step 3: Cut, starting with the most expensive unused ones

What it is	What to do
A whole plugin you never use	/plugin → disable the plugin. Plugin skills can't be turned off one by one.
Your own skill you never use	Delete its folder in ~/.claude/skills/ or .claude/skills/, or turn it off in /skills.
A skill you only ever start by hand	Add disable-model-invocation: true to its frontmatter. Its description leaves the list, /its-name still works.
A skill with a long description	Put the trigger words first. The listing cuts each description at 1,536 characters anyway.

Run step 1 again. When the warning is gone, every description fits.

Step 4 (only if you really need all of them): raise the budget

In ~/.claude/settings.json:

{ "skillListingBudgetFraction": 0.02 }

0.02 = 2% of the context window. The list is sent with every message, so this costs context on every turn. Cutting first is cheaper.

---

Sources: code.claude.com/docs/en/skills (sections "Find unused skills" and "Skill descriptions are cut short"), code.claude.com/docs/en/settings-reference (skillListingBudgetFraction). Numbers above are from one machine: mine.

— Conrad · @buildwith.conrad