Why Claude Code Skills Don't Fire on the Right Request
You write a Claude Code skill, drop it into .claude/skills/, and ask Claude to do the exact thing the skill covers. Claude answers from its own judgment instead, as if the file does not exist. You rephrase the request, try again, get the same generic answer, and eventually give up and do the task by hand. The skill was supposed to save that time, not cost it twice.
A Claude Code skill is a markdown file with YAML frontmatter that Claude loads automatically when the description field in that frontmatter matches what you asked for. Nothing else decides whether it fires. Not the file's location inside a well-organized folder, not how carefully you wrote the instructions in the body, not how obviously relevant the skill is to a human reading it. Only the description text, compared against your request.
What Makes a Claude Code Skill Trigger?
Claude Code reads the description field of every installed skill before it answers you, and picks a skill only when that description's wording lines up with your request. The comparison happens against the description string specifically, not the skill's file name, not its folder, and not its body content.
That means two skills with near-identical bodies but different descriptions behave completely differently. A skill whose description reads "Frontend component scaffolding" will not fire when you ask to "add a login form," even though scaffolding a login form is exactly what it does. The description never mentions forms, login, or authentication, so nothing in your request lines up with it.
Rewrite that same description as "Scaffold frontend components, including forms, auth screens, and login flows, following the project's existing component patterns," and the same skill now fires on the same request, with the same body content and the same file location. Nothing about the skill's logic changed — only the words in one YAML field. This is the whole mechanism, and it explains why a skill can look correct on review and still fail in practice: a human reading the body understands the intent immediately, but Claude Code never reads the body to decide whether to load it.
Why Does a Skill Silently Fail to Trigger?
There is no error message when a skill does not fire. Claude just answers the request a different way, and unless you already know the skill exists, you have no signal that it was skipped. The common causes:
The description is written like internal documentation instead of a matching pattern — it explains what the skill does for a teammate reading the repo, not what someone would type to invoke it. The description is too broad, so a more specific skill or Claude's own defaults win the match instead. Two skills describe overlapping territory, and the one that loads first or reads more directly wins, leaving the other dormant. The frontmatter itself has a YAML syntax error, which usually makes Claude Code skip the file rather than crash loudly. Or the skill lives outside the directory scope Claude Code is actually reading for that project — user-level versus project-level .claude/ paths are not interchangeable.
Scope is the one cause that looks like a triggering problem but isn't. A skill installed at the user level is available across every project on the machine; a skill placed inside one project's .claude/ directory is only visible inside that project. Copying a skill folder between machines or projects without checking which level it landed on is a common way a skill that worked yesterday goes quiet today.
| Symptom | Likely cause | Fix |
|---|---|---|
| Skill never fires, no error shown | Description wording doesn't match real user phrasing | Rewrite description with the exact verbs and nouns people type |
| Wrong skill fires instead | Overlapping descriptions between two skills | Narrow each description to non-overlapping trigger language |
| Skill worked once, then stopped | A newer skill with broader wording now wins the match | Tighten the older skill's description or merge the two |
| Skill installed but invisible | Malformed YAML frontmatter | Validate the frontmatter block against the SKILL.md spec |
| Works in one project, not another | Skill sits at the wrong directory scope | Confirm project-level vs user-level .claude/ placement |
How Do You Fix a Skill That Won't Trigger?
Work through the description first — it is the highest-odds fix and the fastest to test.
- Rewrite the description using the actual words a person says out loud, not a summary written for a teammate.
- List every phrasing variant you can think of for the same request and fold the common ones into the description.
- Check every other installed skill for wording that overlaps this one, and separate the two vocabularies.
- Validate the YAML frontmatter block on its own — a missing colon or bad indent silently drops the file.
- Confirm the skill sits in the directory scope Claude Code actually reads for the project you're testing in.
- Ask Claude directly to invoke the skill by name once, to confirm the file itself works before you debug the matching.
- Re-test with the original phrasing that failed, not a rephrased version, so you know the real trigger is fixed.
Doing this for one skill is a ten-minute fix. Doing it for a growing library of skills, subagents, and slash commands that all need non-overlapping wording is a different kind of job — you're maintaining a small taxonomy, and it gets harder every time you add another skill.
At that point it's usually faster to start from descriptions that already avoid this problem than to keep hand-tuning your own. BuyCoded's Claude Code Skills & Subagents Pack ships 34 skills, 4 subagents, and 23 slash commands with descriptions already written to avoid overlap across web, backend, data, payments, testing, and DevOps work — so the trigger-matching problem is solved before you install the first file.
Should You Just Write Your Own Skills Instead?
Writing your own is a reasonable answer if you only need one or two skills for a narrow, personal workflow — the description-tuning cost stays small, and you already know exactly what wording you type. It stops being reasonable once you're covering a dozen categories of work, because every new skill you add has to be checked against every existing one for overlapping wording, and that checking cost grows faster than the skill count. At ten skills you're comparing roughly forty-five pairs of descriptions by hand every time you add an eleventh.
The usual objection is that a pre-built pack can't know your project's specific conventions the way a skill you wrote yourself would. That's true for the body content, which still needs to match how your team works — but it's not true for the triggering problem this article is about. Trigger-matching is a property of the description wording alone, and a pack built to cover non-overlapping ground across web, backend, data, payments, testing, and DevOps solves that part before you've written a single project-specific instruction. You still get to edit the body to fit your stack; you just stop debugging why the skill didn't fire in the first place.
The mechanism is the same either way: Claude Code loads a skill when the frontmatter description matches your request, not when the skill is merely relevant. Whether you write the descriptions yourself or start from a set that already accounts for this, that one rule is what decides whether your skill fires.
If you want the full library instead of debugging descriptions one at a time, browse the BuyCoded catalog — the skills pack installs as a Claude Code plugin in one command and every asset ships with a description already tuned to trigger correctly.
More troubleshooting notes on Claude Code, Cursor, and AI coding tools live on the BuyCoded blog index.
Frequently asked questions
Why does my Claude Code skill never trigger even though it's installed?
Claude Code matches your request against the skill's frontmatter description text, not its file name, folder, or body content. If the description doesn't contain wording close to what you actually typed, the skill is skipped with no error message. Rewriting the description to match real phrasing is the first fix to try.
Can two Claude Code skills conflict with each other?
Yes. If two skills have descriptions that cover similar ground, Claude picks one and the other stays dormant for requests it should have handled. The fix is narrowing each description to distinct wording so their trigger conditions no longer overlap.
Does the location of a skill file affect whether it triggers?
Yes, but only at the level of scope. A skill placed at the wrong directory — user-level instead of project-level .claude/, or vice versa — may not be visible to Claude Code for that project at all. Once it's in the right scope, the description text is what decides triggering, not the exact path within that scope.
How do I test if a Claude Code skill's description is written correctly?
Ask Claude to perform the task using the exact phrasing you expect real usage to look like, without naming the skill. If it fires, the description matches. If it doesn't, try the request again after explicitly naming the skill to confirm the file itself works, then revise the description's wording rather than the skill's logic.
Is a malformed frontmatter block a common cause of skills not loading?
It's less common than a mismatched description, but it happens. A missing colon, wrong indentation, or an unclosed quote in the YAML frontmatter can cause Claude Code to skip the file entirely. Validating the frontmatter block on its own, separate from the rest of the skill, isolates this quickly.