Why your Skill didn't trigger (and the debug order that finds it)

When a skill doesn't work, the problem almost always falls into one of six categories. The good news is that most fixes are straightforward once you know which category you're in. This lesson is the reference you'll come back to — scan the heading that matches your symptom, apply the fix, move on.

Start with the validator

Before you spend time debugging anything else, run the skills validator. It catches structural problems — missing required fields, malformed YAML, directory layout issues — before you waste time chasing runtime ghosts.

The tool is the agent skills verifier command. Installation differs by operating system, but uv is the fastest path to getting it set up:

uv tool install agent-skills-verifier

Once installed, either run it from inside your skill directory or point it at a path from anywhere. If the validator fails, fix whatever it flags before moving on to the other categories below.

Skill doesn't trigger

Your skill exists, the validator passes, but Claude isn't using it when you expect. The cause is almost always the description.

Claude uses semantic matching, so your request needs to overlap with the description's meaning. If the overlap isn't there, there's no match — and no trigger. The fix:

• Check your description against how you're actually phrasing requests
• Add trigger phrases users would actually say
• Test with variations: "help me profile this", "why is this slow?", "make this faster"

If any of those phrasings fail to trigger the skill, add the missing keywords to the description and try again.

Skill doesn't load

The skill doesn't appear in the skills list at all. Structural problem — check these things in order:

• The SKILL.md file must be inside a named directory, not at the skills root. ~/.claude/skills/pr-review/SKILL.md is correct; ~/.claude/skills/SKILL.md is not.
• The filename must be exactly SKILL.md — uppercase SKILL, lowercase md.
• The frontmatter YAML must parse — no tab characters, no unclosed strings, no missing required fields.

Run claude --debug to see loading errors directly. Look for messages mentioning your skill name — they'll often name the exact problem.

Wrong skill gets used

Claude picks a different skill than the one you wanted. Your descriptions are too similar. Make them distinct.

Being specific about what a skill does and when to use it isn't just about helping Claude decide — it's also what prevents your skill from conflicting with similarly-phrased skills. If you have two skills both described as "reviews code," one of them is going to lose a fight it didn't need to be in.

Priority conflicts

Your personal skill is being ignored, and you suspect shadowing. An enterprise, higher-priority, or identically-named skill is probably winning.

Remember the priority order: Enterprise > Personal > Project > Plugins. If your company has an enterprise code-review skill and you create a personal code-review, enterprise wins every time. Two fixes:

• Rename your skill to something more distinct (frontend-code-review, personal-review)
• Talk to your admin about the enterprise skill — but renaming is faster and more likely to succeed

Plugin skills missing

You installed a plugin but its skills don't appear. Start with the mechanical fixes:

• Clear the cache
• Restart Claude Code
• Reinstall the plugin

If skills still don't show up after that, the plugin's internal skill structure may be wrong. Run the validator against the plugin's skills directory to see what it finds.

Runtime errors

The skill loads but fails during execution. Three common causes:

• Missing dependencies — if your skill uses external packages, they have to be installed. Add installation info to the description so Claude can surface it to users.
• Permission issues — scripts need execute permission. chmod +x your-script.sh.
• Path separators — use forward slashes everywhere, even on Windows. Backslashes get interpreted as escape characters in unpredictable ways.

Quick Troubleshooting Checklist

Keep this near your keyboard:

| Symptom | First thing to try | |---|---| | Not triggering? | Improve description, add trigger phrases | | Not loading? | Check path, filename casing, YAML syntax | | Wrong skill used? | Make descriptions more distinct | | Being shadowed? | Check priority hierarchy, rename if needed | | Plugin skills missing? | Clear cache, restart, reinstall | | Runtime failure? | Check dependencies, permissions, paths |