Why your Claude Code skill never triggers

You wrote a skill. The instructions in the body are good. And Claude never uses it.

Almost every case comes down to one of five causes. Work through them in this order, from the cheapest check to the most involved.

How a skill gets chosen

Claude Code does not read every skill in full. At startup it loads only the name and description of each installed skill. The docs say Claude uses the description to decide when to invoke a skill automatically. The body of SKILL.md loads only after that decision, when the skill is actually used.

That has one consequence that explains most problems: the description is the trigger. A well-written body cannot rescue a description that does not match what you ask for, because the body is never read.

1. Check that the skill is found at all

Before you edit anything, rule out the boring causes:

• The file is named exactly SKILL.md, inside a folder named after the skill.
• The folder is in a location Claude Code reads: ~/.claude/skills/<skill-name>/ for personal skills or .claude/skills/<skill-name>/ inside a project.
• The frontmatter is valid YAML, opens and closes with ---, and has a description.

A skill that Claude Code cannot discover will never fire, whatever the description says.

2. Check that automatic use is not switched off

Three frontmatter fields change how a skill is invoked:

• disable-model-invocation: true prevents Claude from invoking the skill on its own. Only you can run it, with /skill-name.
• user-invocable: false hides the skill from the / menu. Claude can still invoke it.
• paths limits automatic loading to files that match the given glob patterns. Outside those files, the skill stays quiet.

If your skill has one of these and you expected automatic use, that is the answer.

3. Rewrite the description as a trigger

This is the cause behind most silent skills. A description written like documentation says what a skill is. A description written as a trigger says when to reach for it.

Before:

description: Release management helpers

After:

description: Generates release notes and changelogs from git history. Use when the user asks for release notes, a changelog, or what shipped since the last version.

The second version names the task and the situations in which someone would ask for it. The official examples use the same pattern: what the skill does, then "Use when the user asks...".

Anthropic's wording is about specific contexts and key terms rather than exact quotes, so you do not need to guess a literal sentence. You do need the words a person would really use. If you would say "what changed since the last release", make sure "changed" and "release" appear in the description.

4. Put the important part first

The combined description and when_to_use text is truncated at 1,536 characters in the skill listing. A long description can lose its ending, and the ending is often where the trigger phrases were. Move the use case to the front. The details are in this post on description limits.

5. Look for a competitor

If two skills have overlapping descriptions, Claude has to pick one, and it may not be the one you wanted. Read the descriptions of your related skills side by side. If they describe the same situation, sharpen each of them so that a request clearly belongs to one. Merging the two is sometimes the better fix.

This gets worse as the library grows. A library of 60 skills with vague descriptions usually collides more often than one of 10.

Confirm the fix with data

After you change a description, do not rely on a single test prompt. Use the skill for a few days and check whether it fires. Claude Code's transcripts record every skill invocation, so you can count them. Four ways to see which skills you actually use covers /skill-doctor, OpenTelemetry, a short script and a menu bar app.

Fixing it in place

SkillKeeper is a Mac menu bar app that shows how often each skill fires and lets you rewrite a description or add and remove trigger phrases in the same popup. Trigger phrases are written into the skill's description, the same field the checklist above is about, so the edit is exactly the fix described in step 3. Skills that never fire are easy to spot, and it can archive the ones you decide to retire.

Everything runs locally. It reads your transcripts and SKILL.md files on your Mac and sends none of their contents anywhere.