Claude Skills Not Working? Nine Checks to Run

A skill that does not trigger, does not appear, or does not load is almost always one of a small set of configuration errors. Work through this checklist in order; the first few checks resolve most cases. If you are still setting the skill up, the guide to creating a skill describes the full format.

1. Check the file name and folder layout

The file must be named SKILL.md — uppercase, exactly. Not skill.md, not Skill.MD, not SKILLS.md. It also has to live inside its own named folder:

~/.claude/skills/
└── excel-reports/
    └── SKILL.md      ✅ correct

~/.claude/skills/SKILL.md   ❌ loose file, ignored

2. Confirm you used the right directory

There are two valid locations, and mixing them up is the most common path mistake:

• ~/.claude/skills/ — personal skills, available in every project.
• .claude/skills/ (at your project root) — project skills, committed with the repo.

If you put a skill in the project folder but are running Claude from a different directory, it won’t be found. Verify your working directory, and remember that project skills only load for that project.

3. Restart the session

Skills are scanned when a session begins. If you added or edited a skill mid-session, Claude has not seen the change. Start a fresh session (in Claude Code, exit and relaunch; in Claude Desktop, restart the app) and try again.

4. Fix the description — this is the #1 cause

If the skill loads but never fires, the problem is the description. Claude only sees each skill’s name and description until it decides to use one, so the description must name the exact situation. Compare:

State what the skill does and when to use it, in the third person, and include the words users actually type. The Skill Creator writes these for you if you are unsure.

5. Keep the frontmatter valid

The YAML block at the top must be well-formed: opening and closing --- lines, valid keys, and no stray tabs. A broken frontmatter block means the whole skill is skipped silently. Avoid unescaped angle brackets and colons inside unquoted values. Keep the description within its length limit (roughly a couple of sentences — long descriptions get truncated).

6. Confirm that the skill is enabled

In Claude Desktop, skills are governed by settings/permissions — confirm the feature and the specific skill are switched on. In Claude Code, check that you are not in a restricted permission mode that blocks skill loading, and that no disable-model-invocationflag is set in the frontmatter if you expect automatic triggering.

7. Clear the permissions / temp blocker

If a skill runs a bundled script and fails, the cause is often filesystem permissions on the working or temp directory (for example a locked-down /tmp). Ensure Claude can read the skill folder and write to its scratch directory, and that the bundled files are readable (not chmod 000).

8. Try invoking it explicitly

To isolate whether the problem is discovery or triggering, invoke the skill by name (e.g. /excel-reports in Claude Code). If explicit invocation works but automatic does not, the skill is installed correctly and the description is the thing to fix (back to step 4).

9. Update Claude and check the changelog

Skills are a relatively new capability and the loading behavior has changed across releases. Make sure Claude Code / Claude Desktop is up to date; an old version may not support skills the way current docs describe.

Still stuck?

Rebuild the skill from a known-good template using the Skill Creator, or study a well-structured official skill like the PDF skill or MCP Builder and mirror its frontmatter. When in doubt, start from something that already works and change one thing at a time.

Frequently asked questions