Skill does not trigger, what to check in 10 steps before you type /command again

You wrote a skill, it sits at ~/.claude/skills/<name>/SKILL.md, and Claude acts as if it does not exist. You say "take a look at that code review" and get a generic answer instead of the skill logic you put in place. That is not rare. Skills are a probabilistic mechanism, not a deterministic one. Claude decides per prompt whether the trigger description matches, and that goes wrong more often than you would think. Here is the debugging path I walk when a skill does not run.

1. SKILL.md is in the right place

First check. A skill needs exactly this structure, ~/.claude/skills/<skillname>/SKILL.md. The directory can be nested deeper with helper files or bundle scripts, but the SKILL.md has to sit directly in the skill root. If you named it skill.md (lowercase) or README.md, nothing triggers. Claude only scans SKILL.md with a capital S.

Test: ls ~/.claude/skills/*/SKILL.md. If your skill is not in the list, that is already the problem.

2. The frontmatter is valid YAML

Skills load through the frontmatter. If the YAML is broken, Claude skips the skill without a warning. Typical killers: quotes that do not close, tabs instead of spaces, comments with # in the middle of a multi-line value, wrong indentation on allowed-tools.

Quick check: yq eval ~/.claude/skills/<name>/SKILL.md or simply paste it into a YAML linter. If that passes, the frontmatter is syntactically fine. If you do not have yq, open the file in an editor with YAML highlighting and see whether the colours look right.

3. The description is not documentation, it is the trigger

Here lies the main mistake that 90 percent of my skill problems came from. The description in the frontmatter is not a description for humans, it is the trigger Claude reads to decide whether the skill fits. If it says "helps with code topics", that never triggers cleanly because "code topics" is too general.

Write concretely. Instead of "for code review", better "use this skill when the user asks to review, audit, or critique TypeScript or JavaScript code for bugs, security issues, or performance problems". That is a trigger description, not marketing copy. Anthropic documents that explicitly on the skills page under troubleshooting, and in practice it is by far the most important lever.

4. Check the description length

Skills have a description length limit. If you write an 800-character explanation into the frontmatter, at some point it gets cut off and the trigger part falls out. Anthropic lists that in the troubleshooting section as "skill descriptions are cut short".

A rule of thumb that works for me: two sentences, the first says what the skill does, the second says when it should trigger. If you want to give more context, that belongs in the skill body, not in the frontmatter.

5. Check the allowed-tools block

If your skill sets allowed-tools and one of the tools does not exist in the current setup, Claude can refuse the skill. A typical case: you allowed Bash and Edit in the skill, but the session runs plan mode which blocks Edit. Then the skill does not trigger, or triggers without being able to do its work.

Quick fix if you are unsure: comment out allowed-tools temporarily. If the skill triggers then, you know it was the permission problem. Afterwards put it back with the right tools.

6. Plan mode plus skills, what happens together

Skills do trigger in plan mode too, but they cannot write or execute anything. If your skill depends on Edit or Bash, it looks like it is not running. It is running, but Claude answers in the plan layer instead of acting.

Test: switch plan mode off with Shift+Tab and send the same prompt again. If the skill fires now, you only had a plan mode artefact. Note that down, because next time it will look exactly like a broken trigger.

7. Test the skill prompt explicitly

If you are not sure why the skill does not trigger, tell Claude directly. "There is a skill <name> under ~/.claude/skills/, look into the SKILL.md and use it for the following task." That bypasses the probabilistic trigger mechanism and Claude loads the skill manually.

If that works, the skill is technically fine and your problem is only the trigger description. If that does not work either, the skill itself is broken or in the wrong place.

8. settings.json, check whether skills are enabled

In ~/.claude/settings.json there can be a block that enables or disables skills selectively. If you once played with skills.disabled or a plugin set it, your skill can be switched off globally.

cat ~/.claude/settings.json | grep -i skill. If there is something there excluding your skill, out with it. Global settings are more common here than project-local ones, so if you have several Claude setups, look everywhere.

9. Conflict with other skills

If you have three skills with similar trigger descriptions, Claude may pick the wrong one. For example code-review and security-audit often overlap, because code review almost always has security aspects. Claude then triggers sometimes one, sometimes the other, and you think your own skill is broken.

Test: deactivate the other skills temporarily (rename SKILL.md to SKILL.md.bak) and send the prompt again. If your skill now triggers reliably, you have a trigger conflict. The fix is to sharpen the boundaries between the trigger descriptions or to merge the skills.

10. A bundle script not firing is not the same as a skill not triggering

Last trap. A skill can trigger and still do nothing visible, because its bundle script is broken. Claude loads the body, calls the script, the script crashes silently, Claude answers with what it learned from the body. Looks like "skill does not trigger" but is "skill triggers, script crashes".

Test: in the skill directory call the script manually with the same arguments Claude would use. If it crashes by hand, you know where to look. Stderr output from skill scripts is normally swallowed in Claude Code, so you have to test that outside the session.

What next

If the skill triggers now, write into your own memory or an internal CHANGELOG what the actual error was. Most skill trigger problems repeat, and the third time round you do not want to walk all 10 steps again. Store the pattern, debug faster.

If you want to go deeper into skill composition, look at the playbook erste-eigene-skill-in-30-min (/playbooks/erste-eigene-skill-in-30-min), it covers bundle scripts and allowed-tools in detail. For the next step after skills (when is a subagent better, when an MCP tool) the comparison in lesson L4-04 (/levels/4/04-hooks-und-skills) is worth it.

Source

• Skills docs, troubleshooting section: https://code.claude.com/docs/en/skills
• Frontmatter spec and skill activation verified there on 2026-05-23