Agent Skills Not Working? Common Problems and Solutions

Tried to use Agent Skills but they won't work?

This article covers common problems and their solutions.

Skill Not Recognized

Symptoms

• Skill doesn't appear in /skills
• Slash command doesn't work

Checklist

1. Is the directory structure correct?

Copy# ⭕ Correct structure
~/.claude/skills/my-skill/SKILL.md

# ❌ Wrong: SKILL.md placed directly
~/.claude/skills/SKILL.md

# ❌ Wrong: skill.md (lowercase)
~/.claude/skills/my-skill/skill.md

Place SKILL.md (uppercase) inside a directory named after the skill.

2. Is the frontmatter correct?

Copy---
name: my-skill
description: Skill description
---

• name and description are required
• Verify enclosed by ---
• Check for YAML syntax errors

3. Is encoding UTF-8?

Files saved with BOM (common in Windows Notepad) may not be recognized. Save as UTF-8 without BOM.

Skill Not Auto-Applied

Symptoms

• Natural language requests don't use the skill
• A different skill is used instead

Solutions

1. Make description more specific

Copy# ❌ Vague
description: Check code

# ⭕ Specific
description: Review TypeScript PR for security and performance

Claude uses the description to choose skills, so include relevant keywords.

2. Invoke explicitly with slash command

Don't rely on auto-application:

Copy/my-skill

Skill Output Doesn't Match Expectations

Symptoms

• Output too long/short
• Wrong format
• Off-topic content

Solutions

1. Add output examples to SKILL.md

Copy## Output Example

[Expected output example here]

Copy

Concrete examples guide Claude toward similar output.

2. State constraints explicitly

Copy## Constraints

- Output under 100 characters
- Respond in English
- Maximum 3 bullet points

3. Add context when invoking

Copy/code-review
Target file: src/auth.ts
Focus: Security

Multiple Skills Conflicting

Symptoms

• Can't predict which skill will be used
• Unintended skill gets used

Solutions

1. Differentiate descriptions

For similar skills, clearly separate their purposes:

Copy# Skill A
description: Review frontend React components

# Skill B
description: Review backend API endpoints

2. Disable unused skills

Copymv ~/.claude/skills/old-skill ~/.claude/skills/_disabled_old-skill

Different Behavior Across Tools

Symptoms

• Works in Claude Code but not Codex CLI
• Output differs between tools

Causes

• scripts/ execution varies by tool
• Tool-specific features (Claude Code subagents) don't work elsewhere

Solutions

1. Use basic features only

For portability, make skills work with just the SKILL.md body.

2. Create tool-specific versions

If necessary, maintain separate skills:

Copy~/.claude/skills/code-review-claude/SKILL.md
~/.codex/skills/code-review-codex/SKILL.md

Skill Updates Not Reflecting

Symptoms

• Edited SKILL.md but behavior unchanged

Solutions

1. Cache issue

Try restarting Claude Code.

2. Different skill being used

Run /skills to check loaded skills and verify yours appears.

Still Not Working?

Debug Steps

1. Test minimal config: Reduce problematic skill to minimum content
2. Test other skills: Do other skills work?
3. Check official docs: Any spec changes?

Information to Gather

When reporting issues, include:

• Tool and version
• SKILL.md contents
• Command executed
• Error messages (if any)

Summary

Most common issues come from:

1. Directory structure problems
2. Frontmatter mistakes
3. Vague descriptions

Check these three points first.

Testing verified skills from the Skills list can also help isolate problems.

Related Articles

• How to Set Up Skills in Claude Code - Review your setup
• 7 Tips for Better Productivity - Master skill usage
• How to Create Your Own Skills - Learn proper syntax
• What Are Agent Skills? - Back to basics