# Why half your Claude Code skills never fire (and how to fix the descriptions) > Claude Code picks a skill by reading descriptions. In a 383-skill install only 136 said when to fire. The rule that decides it, and how to rewrite the rest. - URL: https://www.agentskillpacks.com/blog/why-claude-code-skills-dont-trigger - Author: İsmail Günaydın - Published: 2026-09-21 - Updated: 2026-09-21 ## Quick answer Claude Code selects a skill by matching your request against each skill's description, so a description that says what the skill is rather than when to use it gives the model nothing to match. In a 383-skill install I measured, only 136 descriptions named a trigger condition. The fix is rewriting the description, not the skill. 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](https://code.claude.com/docs/en/skills) 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: ```yaml # 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](https://github.com/anthropics/skills) is the useful sample set, and the [Agent Skills announcement](https://www.anthropic.com/news/skills) 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](/products/codeforge) is built that way deliberately, with each skill naming the step it owns and the step it hands off, and [Humanizer Pro](/products/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](/blog/free-vs-paid-claude-code-skills), then [the six I actually use](/blog/best-claude-code-skills-for-indie-developers). ## FAQ ### Does Claude Code use skills automatically? It can, and whether it does depends almost entirely on the description field. Claude Code reads the available skill descriptions and matches your request against them, so a description that explains what a skill is without saying when it applies will usually lose to one that names the situation. You can also invoke a skill by name. ### Why does my skill never get picked? Most often because its description describes the skill rather than the trigger. "A comprehensive testing workflow" tells the model what it is. "Use when the user asks to add tests, fix a failing test, or raise coverage" tells the model when to reach for it. The second one fires. ### Do overlapping skills interfere with each other? Yes. If several skills plausibly match a request, the model has to pick one, and near-identical descriptions make that a coin flip. Skills in the same domain need descriptions written against each other, each naming what it handles and what it leaves to its neighbour. ### Can subagents use skills? A subagent works from the tools and instructions it is given, so treat skill availability as something to state explicitly in the delegation rather than something to assume. If a subagent must follow a workflow, name the skill in its prompt instead of hoping selection goes your way. ### How many skills is too many? There is no hard limit, and the practical ceiling arrives sooner than people expect because selection quality degrades before anything breaks. If you cannot name what each installed skill does and when it fires, you are past it.