Troubleshooting

Fresh

Quick Diagnosis

Common Issues

Skill Not Triggering

Step	Action
1	Check description includes keywords users would naturally say
2	Verify skill appears in "What skills are available?"
3	Try rephrasing request to match description more closely
4	Invoke directly with /skill-name to confirm it works
5	Check that disable-model-invocation is NOT set to true

Skill Triggers Too Often

Step	Action
1	Make the description more specific and narrow
2	Add disable-model-invocation: true for manual-only control
3	Remove generic keywords from description

Claude Doesn't See All Skills

Skill descriptions consume context space. The budget is 2% of context window (fallback: 16,000 characters).

Diagnose:

/context

Look for a warning about excluded skills.

Fix:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000

Skill Name Conflicts

Conflict Type	Resolution
Same name at different levels	Higher priority wins: enterprise > personal > project
Skill vs command (same name)	Skill takes precedence
Plugin skills	Use plugin-name:skill-name namespace (no conflicts)

Subagent Skill Returns Nothing

Cause: context: fork set but skill content has no actionable task.

Fix: Ensure skill content contains explicit task instructions, not just guidelines:

# BAD - guidelines without a task
---
context: fork
---
Use these API conventions when writing code...

# GOOD - explicit task
---
context: fork
---
Research $ARGUMENTS:
1. Find relevant files
2. Analyze the code
3. Summarize findings

YAML Frontmatter Parse Error

Common causes:

• Missing --- delimiters (need both top and bottom)
• Incorrect indentation
• Unquoted special characters in values
• Missing space after colon

Example of correct YAML:

---
name: my-skill
description: "This skill does: something special"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
---

Supporting Files Not Found

Cause: Relative paths in SKILL.md don't resolve correctly.

Fix: Use relative paths from the skill directory:

See [reference.md](reference.md)       # Same directory
See [scripts/run.sh](scripts/run.sh)   # Subdirectory

Getting Help

• Ask Claude: "What skills are available?"
• Check context: /context
• Official docs: code.claude.com/docs/en/skills
• Related: Subagents, Plugins, Hooks