Why your Claude skill is not triggering

1. The folder is in the wrong place

Each agent reads skills from its own directory. The folder that holds SKILL.md goes directly inside it, one level down, for example .claude/skills/my-skill/SKILL.md. A SKILL.md placed directly in the skills directory is not found.

One folder in .agents/skills/ is read by Cursor, Codex and Gemini CLI alike.

2. The frontmatter is broken

If the YAML does not parse, the agent sees no name and no description, so it never offers the skill. Common causes:

• The file does not start with --- on line 1.
• The closing --- is missing.
• A description containing a colon, such as Use when: the user..., that is not wrapped in quotes.
• Tabs instead of spaces, or a smart quote copied from a document.
• A name with capitals, spaces or underscores. Use lowercase letters, numbers and single hyphens, 64 characters at most.

---
name: pr-describer
description: "Use when the user opens or describes a pull request. Writes a title and description from the diff."
---

3. The description is too vague

The description is the only thing the agent reads before it chooses. If it does not match the request, the skill stays unloaded. Say what the skill does, then when to use it, and use the words a person would type.

description: Helps with pull requests.

description: Use when the user opens or describes a pull request, or asks for a PR title, summary or changelog line. Writes them from the diff.

4. The name and the folder do not match

If the folder is my_skill and the name field says pr-describer, some agents will skip it or list it under the wrong name. Make both the same lowercase, hyphenated string.

5. The session has not restarted

Skills are read when a session starts. After you add or edit one, quit the agent and open a new session, then ask again.

# Claude Code: check the folder holds a SKILL.md
ls .claude/skills/*/SKILL.md

Rescan it

The scanner catches problems 2 to 4 for you: unparsed YAML, bad names, a name that does not match its folder, and a description that never says when to use the skill. Drop the whole folder so the folder name is checked too.

Questions

Why does Claude not use my skill?

Most often the folder is in the wrong place, the frontmatter does not parse, or the description does not match what you asked. The agent decides from the name and description alone, so a vague description is enough to make it skip the skill.

Do I need to restart after adding a skill?

Restart the agent or start a new session. Skills are read when a session starts, so a skill added mid-session may not appear until the next one.

Can I force a skill to run?

Naming it in your prompt helps, for example "use the pr-describer skill". If it still does not load, the problem is in the folder or the frontmatter, not the prompt.

Does the folder name matter?

Keep the folder name identical to the name field in SKILL.md. Some agents key on the folder, so a mismatch can hide the skill.

Keep reading

• Skill ScannerScore any skill in your browser. Nothing is uploaded.
• SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
• How to install Claude Code skillsThree ways to install, the folder paths, and what to do when it does not load.
• How to write a Claude skillSeven steps, a weak and a strong description, scored side by side.
• All guidesEvery guide, grouped by what you are trying to do.