Troubleshooting Skills: A Complete Debugging Guide

When skills don't work as expected, the problem usually falls into one of a few predictable categories: the skill doesn't trigger, doesn't load, has conflicts, or fails at runtime. This guide walks through each scenario and gives you a systematic troubleshooting approach.

The Five Common Problems

1. Skill doesn't trigger — Claude doesn't activate the skill when you expect
2. Skill doesn't load — Skill doesn't appear in available skills list
3. Wrong skill gets used — Claude activates a different skill than intended
4. Priority conflicts — Higher-priority skill shadows your skill
5. Runtime errors — Skill loads but fails during execution

Let's tackle each one.

Use the Skills Validator First

Before diving into manual debugging, use the agent skills verifier command. This tool catches structural problems before you spend time debugging other things.

Installation

The easiest way to install is using uv:

uv tool install agent-skills-verifier

Alternative installation methods:

# Using pip
pip install agent-skills-verifier

# Using pipx
pipx install agent-skills-verifier

Running the Validator

From skill directory:

cd ~/.claude/skills/my-skill
agent-skills-verifier

From anywhere:

agent-skills-verifier ~/.claude/skills/my-skill

What it checks:

• SKILL.md file exists and is properly named
• Frontmatter is valid YAML
• Required fields (name, description) are present
• Field values meet constraints (length, format)
• Directory structure is correct
• Referenced files exist

Example output:

✅ SKILL.md found
✅ Valid YAML frontmatter
✅ Required fields present
✅ Name: code-review (valid)
✅ Description: 156 characters (valid)
⚠️  Script not executable: scripts/run-linter.sh
❌ Referenced file missing: references/security-checklist.md

Problem 1: Skill Doesn't Trigger

Symptom: Your skill exists and passes validation, but Claude doesn't use it when you expect.

Cause: Almost always the description.

Claude uses semantic matching. Your request needs to overlap with the description's meaning. If there's not enough overlap, no match.

Solution: Improve Your Description

❌ Weak description:

---
name: performance
description: Helps with performance
---

✅ Strong description:

---
name: performance-optimization
description: Optimizes code performance and identifies bottlenecks. Use when profiling code, analyzing performance, making code faster, reducing memory usage, or when the user asks "why is this slow?" or "how can I make this faster?"
---

Add Trigger Phrases

Include phrases users would actually say:

• "profile this code"
• "why is this slow?"
• "make this faster"
• "optimize performance"
• "reduce memory usage"
• "find bottlenecks"

Test with Variations

Try different phrasings:

• "Help me profile this" ✅
• "Why is this slow?" ✅
• "Make this faster" ✅
• "Optimize this" ✅

If any variation fails to trigger, add those keywords to your description.

Example: Before and After

Before (doesn't trigger reliably):

---
name: api-design
description: API design help
---

After (triggers consistently):

---
name: api-design
description: Designs RESTful APIs following best practices. Use when creating endpoints, designing APIs, building REST services, or when the user asks about API structure, endpoint naming, or HTTP methods.
---

Problem 2: Skill Doesn't Load

Symptom: Skill doesn't appear when you ask Claude "what skills are available?"

Causes:

1. Incorrect directory structure
2. Wrong file name
3. Invalid YAML frontmatter
4. Syntax errors

Check Directory Structure

❌ Wrong:

~/.claude/skills/
└── SKILL.md  # Wrong — must be in named directory

✅ Correct:

~/.claude/skills/
└── code-review/
    └── SKILL.md  # Correct

Check File Name

The file name must be exactly SKILL.md:

• ✅ SKILL.md
• ❌ skill.md
• ❌ Skill.md
• ❌ SKILLS.md
• ❌ skill-name.md

Check YAML Frontmatter

❌ Invalid:

--
name: code-review
description: Reviews code
--

✅ Valid:

---
name: code-review
description: Reviews code
---

Three dashes, not two.

Use Debug Mode

Run Claude Code with debug flag:

claude --debug

Look for messages mentioning your skill name:

Loading skills from ~/.claude/skills...
✅ Loaded: code-review
❌ Failed to load: api-design (invalid YAML)
✅ Loaded: testing

This often points you straight to the problem.

Problem 3: Wrong Skill Gets Used

Symptom: Claude activates a different skill than you intended.

Cause: Descriptions are too similar.

Solution: Make Descriptions Distinct

❌ Too similar:

Skill 1:

---
name: code-review
description: Reviews code
---

Skill 2:

---
name: security-review
description: Reviews code for security
---

Both mention "reviews code" — Claude might pick the wrong one.

✅ Distinct:

Skill 1:

---
name: code-review
description: Performs comprehensive code reviews checking style, performance, and best practices. Use when reviewing pull requests or auditing code quality.
---

Skill 2:

---
name: security-review
description: Performs security audits checking for vulnerabilities, authentication issues, and OWASP Top 10. Use when reviewing security, checking for exploits, or auditing authentication.
---

Now the descriptions are clearly different.

Problem 4: Skill Priority Conflicts

Symptom: Your skill is ignored even though it exists.

Cause: A higher-priority skill with the same name is shadowing yours.

Priority Hierarchy

1. Enterprise (highest)
2. Personal (~/.claude/skills)
3. Project (.claude/skills)
4. Plugins (lowest)

Example Conflict

Your company has an enterprise code-review skill. You create a personal code-review skill with additional checks.

Result: Enterprise skill loads (highest priority). Your personal skill is ignored.

Solutions

Option 1: Rename your skill (recommended)

---
name: my-code-review  # Unique name
description: Personal code review with extra checks
---

Option 2: Remove conflicting skill

If you don't need the lower-priority skill, delete it.

Option 3: Talk to your admin

If the enterprise skill needs updating, request changes from your administrator.

Check Which Skill Loaded

Ask Claude:

What skills are currently loaded?

Claude will list active skills and their sources (enterprise, personal, project, plugin).

Problem 5: Plugin Skills Not Appearing

Symptom: Installed a plugin but can't see its skills.

Solution: Clear Cache and Reinstall

Step 1: Clear cache

rm -rf ~/.claude/cache

Step 2: Restart Claude Code

Completely quit and restart the application.

Step 3: Reinstall plugin

Uninstall and reinstall the plugin through the plugin manager.

Check Plugin Structure

If skills still don't appear, the plugin structure might be wrong.

❌ Wrong:

my-plugin/
└── SKILL.md  # Wrong — must be in skills/ directory

✅ Correct:

my-plugin/
└── skills/
    └── skill-name/
        └── SKILL.md

Run the validator on the plugin:

agent-skills-verifier my-plugin/skills/skill-name

Problem 6: Runtime Errors

Symptom: Skill loads and triggers correctly, but fails during execution.

Common Causes

1. Missing Dependencies

Error:

Command not found: eslint

Solution:

Install required dependencies:

npm install -g eslint

Document dependencies in your skill:

---
name: code-review
---

**Requirements:**
- ESLint must be installed globally
- Prettier must be installed globally

2. Permission Issues

Error:

Permission denied: scripts/run-linter.sh

Solution:

Make scripts executable:

chmod +x scripts/run-linter.sh

3. Path Separator Issues

Error:

File not found: references\security-checklist.md

Solution:

Use forward slashes everywhere, even on Windows:

❌ references\security-checklist.md

✅ references/security-checklist.md

4. Referenced Files Missing

Error:

File not found: references/api-guide.md

Solution:

Ensure all referenced files exist:

ls -la references/api-guide.md

If missing, create the file or update the skill to remove the reference.

Systematic Troubleshooting Process

Step 1: Run the Validator

agent-skills-verifier ~/.claude/skills/my-skill

Fix any errors it reports.

Step 2: Check Skill Loads

Ask Claude:

What skills are available?

If your skill isn't listed, check:

• Directory structure
• File name (must be SKILL.md)
• YAML frontmatter syntax

Step 3: Test Triggering

Try multiple phrasings:

• "Help me [task]"
• "I need to [task]"
• "Can you [task]?"

If none trigger, improve your description.

Step 4: Check for Conflicts

Ask Claude:

Which code-review skill is loaded?

If the wrong one loads, check priority hierarchy.

Step 5: Test Execution

Activate the skill and watch for errors. Check:

• Dependencies installed
• Scripts executable
• Paths use forward slashes
• Referenced files exist

Debug Mode

Run Claude Code with debug flag for detailed logging:

claude --debug

What you'll see:

Loading skills from ~/.claude/skills...
✅ Loaded: code-review
   Source: personal
   Description: Performs comprehensive code reviews...

✅ Loaded: api-design
   Source: project
   Description: Designs RESTful APIs...

❌ Failed to load: testing
   Error: Invalid YAML frontmatter
   File: ~/.claude/skills/testing/SKILL.md

Skills loaded: 2
Skills failed: 1

This shows exactly which skills loaded, which failed, and why.

Common Error Messages

"Invalid YAML frontmatter"

Cause: Syntax error in frontmatter

Fix: Check for:

• Three dashes (not two)
• Proper indentation
• No tabs (use spaces)
• Quotes around values with special characters

"Skill directory not found"

Cause: Skill not in named directory

Fix: Move SKILL.md into a directory:

mkdir ~/.claude/skills/my-skill
mv SKILL.md ~/.claude/skills/my-skill/

"Description too long"

Cause: Description exceeds 1,024 characters

Fix: Shorten description or move details to skill body

"Name contains invalid characters"

Cause: Name uses uppercase, spaces, or special characters

Fix: Use lowercase, numbers, and hyphens only:

• ❌ Code Review
• ❌ code_review
• ✅ code-review

Troubleshooting Checklist

Skill Doesn't Trigger

• [ ] Run validator
• [ ] Check description includes trigger phrases
• [ ] Test with multiple phrasings
• [ ] Add keywords users actually say
• [ ] Make description more specific

Skill Doesn't Load

• [ ] Run validator
• [ ] Check directory structure (must be in named directory)
• [ ] Check file name (must be SKILL.md)
• [ ] Check YAML frontmatter (three dashes)
• [ ] Run claude --debug to see loading errors
• [ ] Restart Claude Code

Wrong Skill Gets Used

• [ ] Check descriptions for similarity
• [ ] Make descriptions more distinct
• [ ] Add specific trigger phrases
• [ ] Test with different phrasings

Priority Conflicts

• [ ] Ask Claude which skill loaded
• [ ] Check priority hierarchy
• [ ] Rename skill to avoid conflicts
• [ ] Remove lower-priority duplicate

Plugin Skills Missing

• [ ] Clear cache: rm -rf ~/.claude/cache
• [ ] Restart Claude Code
• [ ] Reinstall plugin
• [ ] Run validator on plugin skills
• [ ] Check plugin directory structure

Runtime Errors

• [ ] Check dependencies installed
• [ ] Make scripts executable: chmod +x scripts/*.sh
• [ ] Use forward slashes in paths
• [ ] Verify referenced files exist
• [ ] Check script output for errors

Real-World Examples

Example 1: Skill Not Triggering

Problem: Created a testing skill, but Claude doesn't use it when I ask "write tests for this component."

Original description:

description: Testing helper

Solution: Add trigger phrases

description: Writes unit tests for React components. Use when creating tests, writing test files, testing components, or when the user asks to "write tests", "add test coverage", or "test this component".

Result: Skill now triggers reliably.

Example 2: Skill Not Loading

Problem: Created skill but it doesn't appear in available skills.

Original structure:

~/.claude/skills/
└── testing.md  # Wrong file name

Solution: Fix structure

~/.claude/skills/
└── testing/
    └── SKILL.md  # Correct

Result: Skill loads successfully.

Example 3: Priority Conflict

Problem: Created personal code-review skill, but enterprise skill loads instead.

Solution: Rename personal skill

---
name: my-code-review  # Unique name
description: Personal code review with extra checks
---

Result: Both skills available with distinct names.

Example 4: Runtime Error

Problem: Skill triggers but script fails.

Error:

Permission denied: scripts/run-linter.sh

Solution: Make script executable

chmod +x scripts/run-linter.sh

Result: Script executes successfully.

Advanced Debugging

Check Skill Loading Order

Ask Claude:

List all loaded skills with their sources

Claude will show:

Loaded skills:
1. security-review (enterprise)
2. code-review (personal)
3. api-design (project)
4. react-testing (plugin)

Test Skill in Isolation

Temporarily disable other skills:

1. Move other skills out of .claude/skills/
2. Restart Claude Code
3. Test your skill
4. Move other skills back

This helps identify conflicts.

Validate Referenced Files

If your skill references other files, verify they exist:

ls -la references/security-checklist.md
ls -la scripts/run-linter.sh
ls -la assets/review-template.md

Check Script Output

Run scripts manually to see errors:

./scripts/run-linter.sh

Fix any errors before using in skill.

Prevention Best Practices

1. Use the Validator Before Sharing

Always run the validator before committing or publishing:

agent-skills-verifier ~/.claude/skills/my-skill

2. Test Thoroughly

Before sharing a skill:

• Test activation with multiple phrasings
• Verify all referenced files exist
• Run scripts manually
• Test in clean environment

3. Document Dependencies

List required tools and packages:

---
name: code-review
---

**Requirements:**
- Node.js 18+
- ESLint installed globally
- Prettier installed globally

4. Use Descriptive Names

Avoid generic names that might conflict:

❌ review, test, deploy

✅ frontend-code-review, react-component-test, aws-deployment

5. Keep Descriptions Specific

Be explicit about when the skill should activate:

description: Writes unit tests for React components using Jest and React Testing Library. Use when creating tests, writing test files, or when the user asks to "test this component" or "add test coverage".

Quick Reference

Skill Doesn't Trigger

→ Improve description, add trigger phrases

Skill Doesn't Load

→ Check directory structure, file name, YAML syntax

Wrong Skill Used

→ Make descriptions more distinct

Priority Conflict

→ Rename skill or remove duplicate

Plugin Skills Missing

→ Clear cache, restart, reinstall

Runtime Error

→ Check dependencies, permissions, paths

Lesson Reflection

Before moving on, consider these questions:

Have you encountered any of these troubleshooting scenarios in your own work? Which fix would have saved you the most time?

How would you set up a process to validate skills before sharing them with your team? Would you:

• Run validator in CI/CD?
• Create a pre-commit hook?
• Document testing checklist?
• Require peer review?

Conclusion

Most skill problems fall into predictable categories:

1. Doesn't trigger → Fix description
2. Doesn't load → Fix structure
3. Wrong skill → Make descriptions distinct
4. Priority conflict → Rename or remove duplicate
5. Plugin missing → Clear cache and reinstall
6. Runtime error → Fix dependencies, permissions, paths

Start with the validator tool — it catches most structural problems automatically. Use claude --debug for detailed loading information. Test thoroughly before sharing.

With systematic troubleshooting, you can quickly identify and fix skill issues, ensuring your skills work reliably for you and your team.