← Blog · 2026-10-15

Claude Code Skill Not Triggering? A 10-Point Checklist

Shortcut: paste your file into our free SKILL.md validator. It catches the YAML and field-name mistakes below in a few seconds, and nothing leaves your browser.

The symptom is always the same. You type /weekly-client-update and the skill runs perfectly. You say "do Acme's Friday update" and Claude writes something from scratch.

Here's the checklist, cheapest checks first. Every item is drawn from the Claude Code skills docs.

First, a 10-second test

Ask Claude Code: "What skills are available?"

• Your skill isn't listed: it didn't load. Jump to items 6 to 9.
• It's listed but never used: the problem is how Claude matches it. Start at item 1.

1. The description doesn't use the words you actually say

Claude only sees each skill's name and description until it decides to load one. If your description says "Generates stakeholder status communications" and you say "Friday update for Acme," there's nothing to match.

Fix it with two parts: what the skill does, then when to use it, written in your own words.

description: Writes the weekly client status email from my notes and open tasks. Use when I ask for a client update, Friday update, weekly recap or status email.

You can also add a when_to_use field with trigger phrases or example requests. It's appended to the description. More on this in How to write a SKILL.md description Claude actually triggers on.

2. The front matter isn't on line 1

Claude Code only reads front matter when the opening --- is the file's first line. A blank line, a title or a comment above it means the whole file, markers included, is treated as plain instructions. The skill loads without a description.

3. The YAML doesn't parse

This one fails quietly. If the YAML between the markers is malformed, the skill still loads with no fields set. That's why /skill-name keeps working while automatic triggering doesn't.

The usual culprit is an unquoted colon inside the description:

description: Drafts proposals. Use when: a client asks for a quote   # breaks
description: "Drafts proposals. Use when a client asks for a quote"  # fine

To find it, start Claude Code with --debug and look for the parse error. On v2.1.233 or later you can also run claude plugin validate .claude/skills (or ~/.claude/skills for personal skills).

4. A field name is misspelled

Claude Code ignores fields it doesn't recognize, without an error. Field names use lowercase words joined by hyphens, with one exception, when_to_use. So disable_model_invocation, allowed_tools or Description are silently skipped.

5. You turned off automatic use

If the front matter has disable-model-invocation: true, Claude can't load the skill on its own, and its description isn't even in context. That's right for /deploy or /send-invoice, but not for a skill you want picked up automatically.

6. paths limits when it can load

With a paths field set, Claude only loads the skill automatically while working on files that match those globs. A proposal skill limited to proposals/** won't fire while you're editing clients/acme/notes.md.

7. It's in the wrong place

The skill has to be a folder with a file named exactly SKILL.md:

• Personal (all your projects): ~/.claude/skills/<skill-name>/SKILL.md
• Project (commit it for the team): .claude/skills/<skill-name>/SKILL.md

The older .claude/commands/<name>.md files still work too. One catch: skills in a .claude/skills/ folder below where you started Claude don't load until Claude reads or edits a file in that subfolder. Start from the right folder, or run /add-dir with the path on recent versions.

8. You're running in the cloud, not on your machine

Cloud sessions, routines and Cowork don't read ~/.claude/skills/ on your laptop. A routine that calls a personal skill reports that the skill wasn't found. Commit the skill to the repo's .claude/skills/ for cloud sessions, or enable it on your claude.ai account for Cowork.

9. The name is reserved or collides

• A folder named synced or anthropic-skills (or starting with anthropic-skills:) doesn't load.
• Invisible characters such as a zero-width space, or a < in the name, stop it loading.
• When the same name exists in both places, the personal skill beats the project one. You may be editing the copy that never runs.

10. Too many skills, so your description got dropped

Claude Code keeps every skill's name in the listing but has a character budget for descriptions, about 1% of the model's context window. When it overflows, it drops descriptions starting with the skills you use least. A new skill you've never invoked is first to lose its description.

What to do:

• Run /doctor for the listing's context cost, and /skill-doctor (v2.1.252+) to find skills worth turning off.
• Put the key use case first. Each skill's description plus when_to_use is cut at 1,536 characters anyway.
• Raise the budget with the skillListingBudgetFraction setting (for example 0.02 for 2%), or set low-priority skills to "name-only" in skillOverrides.

The opposite problem: it triggers too often

Make the description narrower, or add disable-model-invocation: true so it only runs when you type /skill-name.

And if Claude stops following it halfway through

Claude Code adds the skill's content once and doesn't re-read the file later. After a long conversation is compacted it may keep only the start of the skill. Put the critical rules at the top, invoke the skill again after compaction, and move any rule that must hold every time into a hook.

Tools that help

• SKILL.md validator: checks name and description rules, misspelled fields and YAML problems.
• SKILL.md builder: writes a correctly quoted description from "what it does" and "when to use it."

If you run a solo consulting or freelance practice: the free 3-skill sample has three working skills: client follow-ups, meeting-to-tasks and invoice chase. The full Solo Consultant Kit is $29.