Agent Skills Not Working? The 2026 Troubleshooting Guide
You installed a Claude Code skill. It should fire when you ask about CI audits, or API optimization, or whatever the skill promises. Instead, you get silence. Or the wrong skill activates. Or "Error: unknown skill."
You're not alone. Across GitHub issues, Reddit threads, and Discord channels, skill loading failures are the #1 support topic for Claude Code power users.
This guide covers every common failure mode, with exact diagnostic commands and fixes you can run in 30 seconds.
The 30-Second Triage
Before diving deep, run these five checks. They resolve ~80% of issues:
| # | Check | Command |
|---|-------|---------|
| 1 | Does SKILL.md exist at the right path? | find ~/.claude/skills -name SKILL.md |
| 2 | Is the YAML frontmatter valid? | See linting section below |
| 3 | Are your skill descriptions too similar? | Check for overlapping trigger phrases |
| 4 | Did you restart after editing? | Full session restart, not just /clear |
| 5 | Is it a known version bug? | claude --version and check release notes |
If all five pass, read on for deeper fixes.
Failure #1: Skill Never Triggers (Silent Failure)
Symptoms: You installed a skill, but it never activates—no error, no mention, nothing. Root cause (90% of cases): Path problem. TheSKILL.md file isn't where Claude Code expects it.
``
Correct structure:
~/.claude/skills/
my-skill/
SKILL.md ← Must be exactly this name, in a subfolder
REFERENCE.md ← Optional, loaded on demand
scripts/ ← Optional helper scripts
`
Diagnostic:
`bash
List all discovered skill files
find ~/.claude -type f -name 'SKILL.md'
Check folder permissions
ls -la ~/.claude/skills/*/
`
Fix:
`bash
Create the correct structure if missing
mkdir -p ~/.claude/skills/my-skill
Move SKILL.md into the subfolder (not directly in skills/)
mv ~/.claude/skills/SKILL.md ~/.claude/skills/my-skill/SKILL.md
Fix permissions
chmod -R 755 ~/.claude/skills/
`
Common mistake: Extracting a ZIP that puts SKILL.md directly in ~/.claude/skills/ instead of ~/.claude/skills/. The folder name matters—it becomes the skill identifier.
Failure #2: Wrong Skill Activates
Symptoms: You ask for X, but skill Y fires instead. Or you get unpredictable routing.
Root cause: Overlapping description fields in your SKILL.md frontmatter. Claude Code matches skills to your prompt by comparing your request against the description field. When two skills claim similar territory, the router guesses—and often guesses wrong.
Example of bad descriptions (too similar):
`yaml
Skill A
description: "Use for code review and PR analysis"
Skill B
description: "Use for reviewing pull requests and code analysis"
`
Fix: Make the first sentence of each description hyper-specific about when to use it and when not to:
`yaml
Skill A — now specific
description: "Use for automated CI audit reports and pre-merge safety checks. Not for general code review or style feedback."
Skill B — now specific
description: "Use for human-style PR code review with inline suggestions, style feedback, and architecture commentary. Not for CI pipeline checks or automated audit reports."
`
The less-is-more rule: Fewer, well-differentiated skills beat a large collection of overlapping ones. If two skills cover similar territory, merge them or delete one.
Failure #3: YAML Frontmatter Errors (Silent Parse Failures)
Symptoms: Skill file looks fine to the eye, but Claude Code ignores it entirely.
Root cause: YAML syntax errors—especially multiline strings and indentation mistakes—cause the parser to silently skip the skill.
The #1 offender: Multiline description with | or >:
`yaml
BREAKS:
description: |
This is a multiline description
that will cause silent parse failure.
`
Fix: Use single-line descriptions only:
`yaml
WORKS:
description: "Use this skill for automated database migration safety checks and schema diff reviews."
`
Quick YAML lint:
`bash
Extract and lint frontmatter
awk '/^---/{p=!p;print;next} p{print}' ~/.claude/skills/my-skill/SKILL.md | yamllint -
Or just check the first 10 lines manually
head -10 ~/.claude/skills/my-skill/SKILL.md
`
Required fields: At minimum, your frontmatter must have name: and description:. Everything else is optional.
Failure #4: Edits Don't Take Effect
Symptoms: You edited SKILL.md, but Claude Code still behaves as if the old version is loaded.
Root cause: Claude Code caches skill metadata in the session. A simple /clear or /compact does not reload skills from disk.
Fix: Restart the session. Close the IDE tab, end the terminal session, or quit and reopen Claude Code entirely. This is the only reliable way to flush the skill cache.
The rule: After any structural change to a skill (name, description, triggers, adding/removing skills), restart the session. Content-only changes (like updating a reference doc) don't require a restart.
Failure #5: Version-Specific Regressions (2026)
Several Claude Code point releases have introduced (and later fixed) skill-related bugs. If troubleshooting doesn't help, check your version.
Known bad versions:
| Version | Bug | Status |
|---------|-----|--------|
| v2.1.38 |
Skill tool disappeared; skills ran as sub-agents | Fixed in later release |
| v2.0.74 | Built-in commands (
/help, /agents) returned "Unknown skill" | Fixed |
| v2.1.73 | Deadlock when many skill files changed at once (e.g.,
git pull in a large skills repo) | Fixed |
Check and update:
`bash
claude --version
If you're on a known-bad version, update:
(follow official update instructions for your platform)
`
If you're on the latest version and hitting what looks like a regression, search GitHub Issues for your version number.
Failure #6: Windows / WSL Path Issues
Symptoms: Loaded 0 unique skills in debug output, despite correct file structure.
Root cause: On Windows/WSL, skills stored on the Windows filesystem (/mnt/c/...) are not discovered. Claude Code expects skills inside the Linux filesystem.
Fix:
`bash
Move skills into the WSL home directory
mv /mnt/c/Users/you/.claude/skills/* ~/.claude/skills/
Fix permissions (critical on WSL)
chmod -R 755 ~/.claude/skills/
Confirm
find ~/.claude/skills -name SKILL.md
`
Then restart Claude Code. This is a known issue being tracked on GitHub.
Failure #7: Plugin Shows as Installed But Not Enabled
Symptoms: You ran claude plugin install, the plugin appears in installed_plugins.json, but skills from the plugin don't show up.
Root cause: A known bug where installation doesn't automatically enable the plugin.
Fix:
`bash
claude plugin enable @
`
Or manually edit
~/.claude/settings.json:
`json
{
"enabledPlugins": {
"plugin-name@marketplace-name": true
}
}
`
Master Diagnostic Script
Run this to get a complete picture of your skill setup in one shot:
`bash
#!/bin/bash
echo "=== Claude Code Skills Diagnostic ==="
echo ""
echo "1. Version:"
claude --version 2>/dev/null || echo " claude CLI not found in PATH"
echo ""
echo "2. Skill files found:"
find ~/.claude -type f -name 'SKILL.md' 2>/dev/null | while read f; do
name=$(basename "$(dirname "$f")")
desc=$(awk '/^---/{p=!p;next} p{print}' "$f" | grep -E '^description:' | head -1)
echo " $name — $desc"
done
echo ""
echo "3. Permission check:"
find ~/.claude/skills -type d -not -perm -755 2>/dev/null | while read d; do
echo " FIX: chmod 755 $d"
done
echo ""
echo "4. Enabled plugins:"
cat ~/.claude/settings.json 2>/dev/null | grep -E 'enabledPlugins' -A 20 || echo " No enabledPlugins found"
echo ""
echo "=== Run /skills in Claude Code to verify loading ==="
`
Prevention: Skill Hygiene Checklist
Once your skills are working, keep them that way:
1. One skill, one job. If a skill does "code review + deployment + notification," split it into three.
2. First sentence is the trigger. Make it say exactly what prompts should activate this skill.
3. Test after install. Run an explicit prompt like "use
to do X" to confirm it loads.
4. Version your skills. Add a
CHANGELOG.md in each skill folder so you know what changed.
5. Keep durable rules in
CLAUDE.md. Skills can fail; .claude/CLAUDE.md` always loads. Put critical project rules there.
Still Stuck?
- Check the Claude Code docs
- Search GitHub Issues for your specific error message
- Browse curated, vetted skills at AGI Store — every listed skill passes a structural validation check before publication