A skill exists; Claude isn't using it correctly. The skill doesn't get invoked when it should; gets invoked when it shouldn't; or produces wrong output.
This page covers diagnosis and fixes.
The user asks for something the skill should handle; Claude doesn't invoke it.
Causes:
Fix: refine the description. Add explicit triggers ("when user asks for X").
Claude invokes the skill for unrelated requests.
Causes:
Fix: narrow the description. Add explicit skip conditions ("not for Python files").
Claude invokes the skill; produces unexpected results.
Causes:
Fix: clarify instructions. Add explicit examples. Specify pre-conditions.
Get a clear test case. The user request that should invoke the skill; the actual behavior.
If reproduction is intermittent, the issue may be in description matching — sometimes Claude invokes; sometimes doesn't.
Read SKILL.md. Pretend you're Claude:
Invoke the skill explicitly; see what happens. If invocation produces wrong output, the issue is in instructions. If invocation never happens via natural language, the issue is in description.
Skills rarely work perfectly first time. Adjust; test; adjust.
Description: "helps with code style" User: "make this more readable"
Did the description match? If no: what would have matched? Add those terms.
Add explicit triggers:
TRIGGER when:
- User asks to refactor for readability
- User says "clean up this code"
- File contains code-smell patterns
Add explicit skips:
SKIP when:
- File is configuration (yaml, json without code)
- User explicitly says "don't refactor"
If users invoke the skill in unexpected ways, add examples:
## Examples
User: "make this prettier" → invoke this skill
User: "format this JSON" → DON'T invoke; use formatter instead
If the skill's behavior depends on other skills:
This skill assumes brainstorming has happened. If not, invoke brainstorming first.
When a skill changes, you may want to track versions. Skill files don't have built-in versioning, but you can:
For widely-distributed skills, semantic versioning helps users know about breaking changes.
Try the skill in real conversations. Does it work for the cases you care about?
Document expected behavior:
## Tests
Case 1: User asks "do X"
Expected: skill invokes; produces Y
Case 2: User asks "do unrelated thing"
Expected: skill does NOT invoke
Run through them periodically.
Specifically test:
A skill with 2000 lines of instructions has problems. Too much for Claude to apply consistently. Refactor: shorter primary instructions; references to detail.
A skill with 5 lines of "use best practices" doesn't constrain behavior. Specific instructions produce specific outputs.
User CLAUDE.md says one thing; skill says another. Per system prompt, user instructions win — but the skill author may not have known.
Document explicit precedence in skill if relevant.
Skill says "do A then verify" but doesn't actually verify. User assumes verification happened. False sense of completion.
Make verification explicit and traceable.
Skills used during development that shouldn't run in normal use. Either don't ship them, or guard with explicit triggers.
When a skill misbehaves:
Most issues fall into one of these.