Claude Code Skills Not Working? Troubleshooting Guide

You installed a skill but Claude Code isn't using it. Or it's using it wrong. Or it doesn't seem to know it exists. Here's how to diagnose and fix the most common issues.

Skill not loading at all

Claude Code loads skills at session startup. If you installed a skill while a session was running, it won't be picked up until you start a new session.

Fix: end your current session and start a new one.

If it still doesn't load, check the path:

ls ~/.claude/skills/skill-name/SKILL.md

If this doesn't return the file, the skill isn't where Claude Code expects it. Common path issues:

Double-nested folder. After unzipping, you might have ~/.claude/skills/skill-name/skill-name/SKILL.md. The SKILL.md needs to be one level up:

mv ~/.claude/skills/skill-name/skill-name/* ~/.claude/skills/skill-name/
rmdir ~/.claude/skills/skill-name/skill-name

Wrong directory. Personal skills go in ~/.claude/skills/. Project skills go in .claude/skills/ within your project root. Don't mix them up — a project skill in the personal directory works everywhere, which might not be what you want.

Case-sensitive filename. The file must be named exactly SKILL.md — uppercase. skill.md, Skill.md, and Skill.MD won't work.

Skill loads but doesn't trigger

The skill is in the right place but Claude Code doesn't use it when you expect it to. This is almost always a description problem.

Open the SKILL.md and look at the description field in the frontmatter:

---
name: my-skill
description: Reviews Python code for security vulnerabilities
---

The description tells Claude when to activate the skill. If it's too vague ("helps with code"), Claude won't match it to your specific request. If it's too narrow ("reviews Flask API endpoints for SQL injection in PostgreSQL queries"), it won't trigger for general code review requests.

A good description is specific about the task but general about the context: "Reviews code for security vulnerabilities, logic errors, and style violations."

For more on this, see How to Write a SKILL.md Description That Triggers.

Skill triggers but gives wrong output

The skill is activating but the output doesn't match what you expected. This means the instructions in the SKILL.md body need adjustment.

Common issues:

Conflicting skills. If two skills cover the same task, Claude might use the wrong one. Check ~/.claude/skills/ for overlapping skills and remove the one you don't want.

Overly rigid instructions. If the skill says "always respond in bullet points" but you asked for a paragraph, Claude has to choose between your request and the skill's instructions. Rewrite the skill instructions to be guidelines, not absolute rules.

Missing context. The skill might assume a framework or language you're not using. If a testing skill assumes Jest but you use Vitest, Claude will generate Jest-style tests. Either find a skill that detects your framework, or edit the skill to match your setup.

Frontmatter parsing errors

If the SKILL.md frontmatter is malformed, Claude Code might ignore the skill entirely. The frontmatter must:

• Start on the very first line of the file with ---
• End with --- on its own line
• Contain valid YAML between the markers
• Have at least name and description fields

---
name: my-skill
description: What this skill does and when it should activate.
---

Instructions start here.

Common mistakes:

• Extra whitespace before the first ---
• Missing closing ---
• Using tabs instead of spaces in the YAML
• Special characters in the description without quotes

Permission errors (Windows/WSL)

If you're on Windows using WSL, you might get permission errors when installing skills. Fix with:

chmod -R 755 ~/.claude/skills/skill-name/

For a complete Windows setup guide, see How to Set Up Claude Code Skills on Windows.

Still not working?

Ask Claude Code directly:

"What skills do you have access to?"

Claude will list the skills it found and loaded. If your skill isn't in the list, the issue is file placement or frontmatter. If it's in the list but not triggering, the issue is the description matching.

---

Browse working, tested skills at Agensi — every skill is reviewed before listing.