Troubleshooting Skills
Most Problems Fall Into Four Buckets
When a skill misbehaves, the cause is almost always one of four categories: it doesn't trigger, it doesn't load, the wrong one is used, or it fails at runtime. Knowing the bucket points you straight to the fix. Before anything else, run the skills validator to catch structural problems early.
The four diagnostic buckets — identify which one you're in, and the fix follows directly.
Doesn't Trigger or Doesn't Load
These are the two most common. If a skill exists and validates but Claude isn't using it, the cause is almost always the DESCRIPTION — semantic matching needs overlap with how you phrase requests. If a skill doesn't even appear in 'What skills are available?', it's a structural problem.
| Symptom | Likely cause | Fix |
|---|---|---|
| Doesn't trigger | Description lacks your phrasing | Add trigger phrases; test 'profile this', 'why slow?', 'make faster' |
| Doesn't load (not listed) | SKILL.md misplaced or misnamed | Must be inside a NAMED directory; file named EXACTLY SKILL.md |
| Doesn't load (unclear why) | Loading error | Run claude --debug and look for your skill name |
Triggering → description. Loading → structure (directory + exact SKILL.md filename).
The exact filename matters
The file must be named exactly SKILL.md — all caps on SKILL, lowercase md — and it must sit inside a named directory, NOT at the skills root. A file at ~/.claude/skills/SKILL.md won't load; ~/.claude/skills/my-skill/SKILL.md will.
Wrong Skill, Conflicts, and Plugins
If Claude picks the wrong skill or seems confused between them, your descriptions are too similar — make each distinct. If your personal skill is being ignored entirely, a higher-priority skill (enterprise) with the same name is shadowing it. And if a freshly installed plugin's skills don't appear, it's usually a cache issue.
- •Wrong skill chosen → descriptions too similar; make them specific and distinct (frontend-review vs backend-review).
- •Personal skill ignored → priority conflict (Enterprise > Personal > Project) with a same-named higher skill; rename yours, or talk to your admin.
- •Plugin skills missing after install → clear the cache, restart Claude Code, and reinstall; if still missing, the plugin structure may be wrong (run the validator).
Descriptions cut short?
With many skills, descriptions get trimmed to fit the context budget, which can strip matching keywords. Run /doctor to see if the budget is overflowing and which skills are affected. Put the key use case first, or raise the budget with skillListingBudgetFraction.
Runtime Errors and the Checklist
The skill loads but fails during execution. Three usual suspects: missing dependencies (external packages must be installed — add what's needed to the skill's instructions), permission issues (scripts need execute permission — run chmod +x), and path separators (use forward slashes everywhere, even on Windows).
| Problem | Quick check |
|---|---|
| Not triggering | Improve description; add trigger phrases |
| Not loading | Check path, exact SKILL.md filename, and YAML syntax |
| Wrong skill used | Make descriptions more distinct |
| Being shadowed | Check the priority hierarchy; rename if needed |
| Plugin skills missing | Clear cache and reinstall |
| Runtime failure | Check dependencies, chmod +x, forward-slash paths |
A pocket troubleshooting checklist — match the symptom to the fix.
Next
You can diagnose any skill problem. Next we distill everything into best practices and anti-patterns for building skills that work the first time.
Key Takeaways
- ✓Skill problems fall into four buckets: doesn't trigger, doesn't load, wrong skill used, or runtime failure — identify the bucket and the fix follows.
- ✓Run the skills validator first to catch structural issues before deeper debugging.
- ✓Not triggering → almost always the description: add trigger phrases that match how you actually ask, and test variations.
- ✓Not loading → SKILL.md must be inside a NAMED directory and named exactly SKILL.md; run claude --debug to see loading errors.
- ✓Wrong skill → descriptions too similar (make them distinct); personal skill ignored → priority conflict with a higher-scope same name (rename); plugin skills missing → clear cache & reinstall.
- ✓Runtime errors → check missing dependencies, run chmod +x on scripts, and use forward-slash paths everywhere; use /doctor if descriptions are being trimmed.
Check Your Understanding
Test what you learned in this lesson.
Q1.A skill exists and validates, but Claude never uses it. What's the most likely cause?
Q2.Your skill doesn't appear in 'What skills are available?'. What structural requirement is most often the problem?
Q3.Claude keeps choosing the WRONG skill among several. What's the fix?
Q4.A skill loads but fails at runtime. Which set of checks applies?
Practice This Lesson