Your Claude Code skill has good instructions and still never fires — fix the description field

You write a SKILL.md, test it with the prompt you had in mind while writing it, watch it fire, and move on. Two weeks later you notice you have been typing /skill-name by hand every time, because Claude stopped picking it up on its own. Nothing about the skill changed. The instructions are still correct. The problem was never in the body of the file.

Claude never reads the instructions to decide whether to use them

A skill has two parts: YAML frontmatter and a markdown body. In a normal session, Claude Code keeps every skill's name and description loaded in context at all times, so Claude knows what is available. The markdown body — the actual instructions — only loads once a skill is invoked, either by you typing /skill-name or by Claude deciding to trigger it.

That means the entire decision of whether your skill gets used runs off the one or two sentences in description, before Claude has seen a single line of what the skill does. A precise, well-tested procedure with a vague description is invisible. A rough procedure with a sharp description gets found.

There is also a hard ceiling on how much of that description Claude sees: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing, and if you have many skills installed, Claude Code shortens descriptions further to fit a total budget (1% of the model's context window by default), dropping the ones you invoke least first. Put your primary use case in the first sentence — anything after the cutoff never reaches the model.

The two fields that control triggering

• description — what the skill does and when to use it. Claude matches your prompt against this text to decide whether to load the skill. If you omit it, Claude Code falls back to the first paragraph of the markdown body, which is usually written for a human reader, not as a matching target.
• when_to_use — trigger phrases and example requests, appended to description and counted in the same 1,536-character cap. This is the field for "use when the user says X" phrasing that would read awkwardly inside a normal description sentence.

Both are matching text, not documentation. Write them the way you would write a search index entry: the words a practitioner would type, not a tidy summary of the feature.

Two failure directions, two different fixes

Under-triggering — you ask for exactly what the skill does and Claude still does not reach for it. The description is missing the vocabulary your prompts use. If you keep asking about "PDF exports" and the description says "handles document generation," that mismatch is the whole bug. Fix: add the words your prompts contain, and put the highest-value use case first, ahead of the truncation point.

Over-triggering — the skill fires on prompts it has no business touching, because the description is broad enough to match almost anything. Fix: narrow the description to the specific case, or add explicit negative conditions — "skip when X is already handled by Y" — the same way you would write a disambiguation rule between two similar tools. If you want a workflow that should never run without you explicitly asking for it (a deploy, a commit, a message send), stop tuning the description and set disable-model-invocation: true instead — that removes the skill from automatic matching entirely and leaves it invocable only by typing /skill-name directly.

Debug it the way Claude Code debugs it

Before rewriting a description by guesswork, check the two most common causes first:

1. Does the description contain the keywords a user would naturally say when they want this skill?
2. Is the frontmatter YAML valid? A malformed frontmatter block still lets /skill-name work by hand, because Claude Code loads the body with empty metadata, but Claude has no description to match against, so automatic triggering silently stops. Running with --debug surfaces the parse error.

For anything past a quick guess, Anthropic ships a plugin that turns "does this trigger correctly" into a measured loop instead of a feeling:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official
/reload-plugins

Then, in a session: evaluate my <skill-name> skill with skill-creator. It walks you through writing a handful of realistic test cases, then runs each one in a fresh subagent — once with the skill available, once with it disabled — so leftover context from writing the skill cannot mask a gap in the instructions. The parts worth using even if you skip everything else:

• Description tuning generates should-trigger and should-not-trigger prompts, measures the actual hit rate against your current description, and proposes edits when it is firing on the wrong requests.
• Version comparison runs a blind A/B between an old and a new description so you can confirm an edit improved the hit rate before you commit it, instead of shipping a rewrite and hoping.

Where this earns the effort

It is not worth running the full eval loop on a skill you invoke by hand three times a week — just call it directly. It is worth it for anything meant to fire on its own inside a scheduled task or a recurring routine, where a silent under-trigger means the automation quietly stops doing its job and nobody notices until the output goes stale. A skill that only works when you remember to type its name is not automation — it is a shortcut you have to remember to use. See Prompts vs Skills vs Workflows vs Agents for when a skill is the right format to reach for in the first place, and the Claude Code page for the rest of what it can preload into subagents.