Why does my Claude Code skill never trigger?

Almost always the trigger description in SKILL.md is too vague or too narrow to match how a real request is phrased. The instructions can be correct and the skill still never fires.

How does skill triggering work?

The agent matches the user's request against each installed skill's short frontmatter description, not the full file contents, and only reads the rest of the skill once that description matches.

How do I test whether a skill triggers correctly?

Try several real phrasings of the request the skill is for, plus a few adjacent requests it should not handle, and check the skill fires only on the first group.

Guides

Why skills do not trigger

The most common complaint about a new skill is not that it does the wrong thing. It is that it never runs at all. The agent has it installed, the instructions are fine, and it still sits unused while the agent answers freehand or reaches for a different skill.

This almost always comes down to one field: the description in the SKILL.md frontmatter. That single line is what the agent checks against the user's actual request, and it is far easier to write a description that reads well than one that matches well.

How triggering actually works

When a user makes a request, the agent is not reading the whole content of every installed skill. It is matching the request against each skill's short description and deciding, skill by skill, whether this request is what the skill says it is for.

That means the description has to do two jobs at once: describe the skill's job specifically enough to fire on the requests it should handle, and narrowly enough to stay out of the way on requests it should not.

The common failure: vague or overbroad descriptions

A description like "helps with git" or "for writing better code" fails in the direction people do not expect. It does not usually fail to trigger; it triggers on too much, gets used on the wrong requests, and then looks unreliable even though the underlying instructions were fine.

The opposite failure is a description so narrow or so jargon-heavy that it never matches ordinary phrasing. A skill described only in the exact terms its author used internally will miss the plainer way a real user asks for the same thing.

Before and after

Worked example

The same skill, described two ways.

Before: "Helps with git." Fires on merge conflicts, branch strategy questions and general git troubleshooting, none of which the skill actually covers.
After: "Use when writing a commit message for the currently staged changes." Fires only on commit-message requests, which is what the skill's instructions actually do.

The instructions did not change. Only the trigger description did.

A good description names the concrete situation the skill is for, in words close to how a user would actually ask, and says nothing about situations the skill does not cover. State what it is for, not what it is generally about.

How to test triggering yourself

Write down five or six ways a real user might phrase the request the skill is for, in their own words rather than the skill's vocabulary.
Try each phrasing against the agent and note whether the skill fires, and whether it should have.
Also try two or three adjacent requests the skill should not handle, to check the description is not too broad.
If it under-fires, the description is probably too narrow or uses words a real request would not. If it over-fires, narrow the description to the specific situation, not the general topic.

This is exactly what a routing simulation does automatically: it runs the trigger description against a range of requests and reports where the skill would and would not fire, so the gap shows up before a real session hits it.

Want a routing simulation run against your own trigger description?

Open Skill Check