Why Your Claude Skill Isn't Triggering

You wrote a SKILL.md, the folder is in the right place, the frontmatter is valid YAML — and Claude still doesn't use it. This is one of the most common complaints about Claude Skills, and it almost never comes down to a broken file. It comes down to one field: description.

Claude only reads the description to decide

Claude doesn't read your skill's full instructions before deciding whether to use it — that would be far too expensive to do for every skill on every request. Instead, it reads a short list of names and descriptions, and matches your request against those descriptions alone. If the description doesn't clearly cover the situation you're in, the skill simply never gets considered, no matter how good the instructions inside it are.

That single mechanism explains almost every "my skill isn't working" report. The file is fine. The description is the whole interface.

The activation rate is worse than you'd expect

Developers who've tracked this carefully report activation rates around 50% for a typical hand-written description — a coin flip on whether a clearly relevant skill fires. The pattern behind the failures is consistent: descriptions that are too vague ("helps with code") never match anything specific, and descriptions that are too narrow only match the exact phrasing the author imagined, not the dozens of ways a real person actually asks.

What actually works: what + when, stated directly

A description needs two things in it, explicitly: what the skill does, and when it should be used. Not one or the other — both. "Fills PDF forms" tells Claude the capability but not the trigger. "Use when the user has a PDF form" tells Claude the trigger but not the capability. Put together, they cover both sides of the match:

• Weak: "Helps generate documentation."
• Better: "Generates API reference docs from TypeScript source. Use when the user asks for documentation, a reference guide, or asks what a function/module does."

The second version gives Claude concrete trigger phrases to match against, not just a category label.

Imperative phrasing measurably outperforms passive phrasing

There's a specific, testable finding worth building into your habit: descriptions written as a direct imperative instruction, paired with an explicit negative constraint ("ALWAYS invoke this for X. Do not attempt Y without it."), activated reliably in testing, while softer, passive-voice descriptions activated only around three-quarters as often. The instruction-plus-constraint pattern removes the ambiguity that passive descriptions leave for Claude to guess at.

Other common failure modes

• Too many skills, each with a long description — if the combined description text is too large, some of it may not even reach Claude's context, and skills near the end simply aren't visible to be matched.
• Name-only reliance — expecting Claude to infer purpose from a kebab-case name alone. The name is an identifier, not a trigger; it does essentially no matching work on its own.
• YAML that silently breaks — a colon or quote in the description that isn't escaped can corrupt the frontmatter parse, which looks identical to "the skill just isn't triggering" from the outside.

Check yours before you ship it

Before assuming a triggering problem is a Claude problem, rule out the two things that are actually in your control: is the description specific about both what and when, and is the YAML itself valid once your description includes real punctuation. Both are quick to check against a working example rather than guessing.