Why half your Claude Code skills never fire (and how to fix the descriptions)

Claude Code decides which skill to use by reading the description field of every available skill and matching it against what you asked for. That single fact explains almost every case of a skill that sits installed and never runs: the description says what the skill is, and nothing a user would ever type looks like that.

I found the scale of this by measuring my own install rather than by theory. On September 21, 2026, across 383 installed skill directories, 136 descriptions named a trigger condition and 247 did not. Just under two-thirds of what I had installed was asking the model to guess.

How selection actually works

The skills documentation describes the mechanism plainly: skills are discovered from ~/.claude/skills/ and the project's .claude/skills/, and each one contributes a name and a description. When you make a request, those descriptions are what the model has to work with.

This has one consequence worth internalising. The description is not documentation for humans who might browse your skills folder. It is the interface between a sentence a user typed and a workflow you wrote, and it is the only part of the skill the model sees before deciding.

The instructions inside the skill can be excellent. If the description does not win the match, none of them run.

The rule that decides it

Write the description as a trigger, in the user's words.

Here is the same skill described both ways:

# never fires
description: A comprehensive test-driven development workflow with
  red-green-refactor enforcement and coverage reporting.

# fires
description: Use when adding tests, fixing a failing test, starting a new
  feature that needs tests first, or when the user says "write tests",
  "TDD", or "increase coverage". Enforces red-green-refactor.

The second one is worse prose and better engineering. It contains the phrases a person actually types, including the lazy ones, and it names situations rather than qualities.

Three specifics that matter more than they should:

1. Use the wrong words on purpose. People type make this less AI-sounding, not apply editorial de-optimization. The description should contain what they type.
2. Name the situation, not the capability. when the user is about to publish a page beats publishing workflow support.
3. Say what it is not for. In a crowded domain this does more work than anything else, because it is what lets a neighbouring skill win cleanly.

Why this gets worse the more you install

Selection is competitive, so description quality is relative rather than absolute.

In my install, 31 skill names start with blog, 26 with seo and 20 with geo. Those three clusters overlap heavily in subject matter. A perfectly good description for a blog-auditing skill still loses if thirty other skills describe something adjacent in similar words, and none of them draw a boundary.

This is the part that surprised me: adding a skill can make an existing skill stop firing. Nothing broke and nothing changed in the older skill. It simply acquired a competitor, and the model now has to distinguish two things that their authors never wrote against each other.

Which reframes the maintenance job. A skills folder is not a collection of independent tools. It is a routing table, and routing tables need to be edited as a whole.

The ten that could never have fired

Two smaller findings from the same measurement, both worth checking on your own install:

• Ten directories had no SKILL.md at all. They sat in the skills folder looking like skills. They could not load under any circumstances.
• Six skills had a SKILL.md with no description field. Nothing to match against, so nothing ever matched.

Neither produced an error. Both are the characteristic failure mode of this whole system: things do not break, they quietly never happen, and a quiet non-event generates no signal at all. It is the same reason a skill that never fires can sit there for months while you conclude that skills are overrated.

If you want a reference for what a well-formed description looks like, the official Anthropic skills repository is the useful sample set, and the Agent Skills announcement covers the design intent behind putting so much weight on one field.

The audit, which takes about twenty minutes

Run this on your own install before installing anything else.

1. List every skill directory and check each has a SKILL.md. Delete or fix the ones that do not.
2. Read every description and ask: does this say when to use it? If not, rewrite it as a trigger.
3. Group by domain. For every cluster of three or more, rewrite the descriptions against each other so each names its boundary.
4. Delete anything you cannot justify. An unused skill is not free, because it competes in every selection.
5. Test the ones that matter. Phrase a request the lazy way and see whether the right skill fires.

Step five is the one people skip and the only one that produces evidence.

When to stop fixing and just say the name

Sometimes the right answer is to give up on automatic selection.

If a skill is important, runs rarely, and sits in a crowded domain, the cheapest fix is to invoke it by name rather than to keep tuning a description so it beats thirty neighbours. That is not a workaround. Automatic selection is a convenience, and convenience is worth exactly what it costs to maintain.

The version of this that applies to packs: a pack of forty skills only works if its forty descriptions were written as one routing table. That is most of what you are paying for, and it is checkable before you buy, because the descriptions are visible. CodeForge is built that way deliberately, with each skill naming the step it owns and the step it hands off, and Humanizer Pro is three skills rather than thirty for the same reason.

If you are earlier than any of this, start with whether you need a paid pack at all, then the six I actually use.