Why Claude is not using your skill

You wrote a SKILL.md, asked for exactly what it covers, and Claude ignored it. There are only a handful of causes, and most can be found in a few minutes by going through them in order. This guide follows Claude Code’s skills page (the sections “Skill not triggering” and “Skill descriptions are cut short”, read on 16 October 2026) and the Agent Skills specification. Other tools that read SKILL.md may behave differently; where a point is specific to Claude Code, it says so.

Step 1: can you invoke it by name?

Type /your-skill-name. If the name is not recognised, the file is not being loaded at all: go through all of step 2. If it works, Claude Code found the file, but do not skip the first item of step 2 yet: malformed YAML leaves /your-skill-name working while Claude cannot match your description. Check the YAML first, then go to step 3.

Step 2: the frontmatter and the file (check the YAML even if /name works)

• The frontmatter is not valid YAML. Claude Code’s docs say that when the YAML does not parse, the skill still loads with no fields set: /skill-name still works, “but Claude can’t match against your description”. This is the cause that looks like nothing is wrong. The usual culprit is an unquoted description containing a colon and a space, such as description: Writes a commit message: a subject and a body. Wrap the value in double quotes.
• The opening --- is not on line 1. Claude Code reads the frontmatter only when the opening --- is the file’s first line; otherwise it treats the whole file, markers included, as skill content. A blank line or a comment above it is enough to break it.
• The name contains a character Claude Code refuses, such as a zero-width space, a no-break space, a control character or < and >. These are invisible when you copy a name from a web page. Start Claude Code with claude --debug and search the log for [names] to see which name was refused.
• The name does not match the folder, or breaks the naming rules. The specification requires 1 to 64 characters of lowercase letters, digits and single hyphens, equal to the directory name. Claude Code is more forgiving than the spec, and other tools may not be.
• The file is in the wrong place. Personal skills live in ~/.claude/skills/<name>/SKILL.md and project skills in .claude/skills/<name>/SKILL.md; the folder name is the skill name, and a file sitting directly in skills/ is not a skill.

Claude Code can list the files whose frontmatter does not parse: claude plugin validate ~/.claude/skills (Claude Code v2.1.233 or later, per its docs). That covers parsing. It does not tell you whether your description would be chosen.

Step 3: it loads, but Claude does not pick it

• The description does not use the words you typed. The description is what Claude matches your request against. Say what the skill does and when to use it, using the words a person would actually write: “Use when the user asks to fill in, complete or sign a PDF form” matches “fill out this form” far better than “Helps with PDFs”. The specification itself calls that last one a poor description.
• The key use case is at the end. Claude Code cuts the combined description and when_to_use text of each skill at 1,536 characters in its skill listing (the name is not counted). Anything after that is never seen. Put the main use case first. The cap can be changed with the skillListingMaxDescChars setting.
• You have so many skills that descriptions were dropped. Claude Code keeps its whole skill listing within a budget of 1% of the model’s context window. When the listing overflows, it drops descriptions starting with the skills you use least, so a rarely used skill can end up listed by name only, with none of the keywords that would match your request. Run /doctor for the listing’s estimated cost and its biggest contributors, and /skill-doctor to see which skills are costly and unused. To free room, set skills you rarely need to "name-only" in the skillOverrides setting, shorten long descriptions, or raise skillListingBudgetFraction (for example to 0.02 for 2%).
• Two skills compete. If two descriptions share most of their distinctive words, the choice between them is left to chance, and either can win. Rewrite each to say when it applies and when it does not, or merge them.
• It is set not to run on its own. A skill with disable-model-invocation: true, or one set to "user-invocable-only" in skillOverrides, is for you to call with its slash command and is never chosen by Claude.

Step 4: check your fix without guessing

Try a few prompts that should trigger the skill and a few that should not, in a fresh session, because leftover context from writing the skill can hide gaps. If the skill ships in a plugin, claude plugin eval can measure how often it triggers. For a folder of skills of your own, Skill Ledger (free for 12 skills, in your browser, nothing uploaded) reads the files and reports the checks above with line numbers: YAML that will not parse, a name that does not match its folder, descriptions over the 1,536 cut, the size of your listing against the 1% budget, and pairs of skills with overlapping descriptions. It can also repair the mechanical problems (quote a value, fix a name) in one click and keep the old text. Its trigger tests are a word-overlap proxy, not a run of an agent, and it says so; confirm important skills in Claude Code itself.

Prefer a terminal? The same checks run as a zero-dependency Node command (node cli.mjs ~/.claude/skills, with --fix for the mechanical repairs), which exits with an error code when something needs fixing, so it fits a CI job.

The short checklist

1. Frontmatter is valid YAML (quote any value that contains a colon and a space). Check this even if /your-skill works.
2. /your-skill works? If not, check line 1, the name characters and the folder.
3. Description says what and when, in the words people type, main use first.
4. Under 1,536 characters of description plus when_to_use.
5. Listing within budget; rarely used skills set to name-only.
6. No other skill with the same distinctive words.

Skill Ledger is a product of Plainwork Digital. The guide above is free to use whether or not you use it. For writing rules in more depth, see the SKILL.md description checklist.