Claude Skills Not Working? Fixes for Every Failure Mode

Skill failures sort cleanly by symptom, and each symptom has a short check list. Find your symptom below and work it top to bottom. (For the deeper test-and-iterate methodology once things basically work, see Testing and Debugging Skills.)

Symptom 1: the skill doesn't appear in the / menu

The skill isn't loading at all. In order of likelihood:

1. Wrong path. It must be .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (personal) — the file is SKILL.md, uppercase, inside a folder named for the skill. A bare my-skill.md directly in skills/ doesn't load.
2. Name mismatch. The frontmatter name must equal the folder name, and both must be lowercase letters, numbers, and hyphens only, max 64 characters. Deploy_Checklist fails on three counts.
3. Broken YAML. An unclosed quote, a tab, or a missing closing --- makes the frontmatter unparseable and the skill is silently skipped. Paste the frontmatter into a YAML linter if in doubt.
4. The skills directory was born mid-session. Skill files are watched live, but if the top-level skills folder itself didn't exist when the session started, restart once so it gets watched.
5. It's namespaced. Plugin skills appear as /plugin:name, and nested monorepo skills as /dir:name — check the full menu, not just the bare name.
6. user-invocable: false is set. Then it's hidden from the menu by design and only auto-invocation runs it.

Symptom 2: it never triggers on its own

The skill loads (you can run /name) but Claude never picks it up automatically. This is a description problem in nearly every case — the description is the only thing Claude sees before the skill fires:

• It's written in implementation language. "Handles VCS metadata normalization" matches nothing anyone types. Rewrite as the job plus the trigger: "Generate clear commit messages from staged changes. Use when committing code."
• It lacks a "Use when…" clause. Add one with the verbs users actually say; add when_to_use with example phrasings if the description alone isn't enough surface.
• It's being truncated. The listing budgets ~1,536 characters for description plus when_to_use combined — if your trigger phrasing lives at the end of a long description, it may never be seen. Front-load it.
• A frontmatter field is blocking it. disable-model-invocation: true forbids auto-triggering entirely, and paths: globs restrict activation to matching files — check both before rewriting anything.

Test in a fresh session each time: the session where you wrote the skill has the whole conversation biasing the routing.

Symptom 3: it fires when it shouldn't

The opposite failure, same field. A description like "Helps with git" claims half of all sessions. Narrow it to the one job, name what it does not cover if a sibling skill owns the neighboring job, and for skills that should only ever run deliberately — deploys, anything destructive — set disable-model-invocation: true and invoke by /name. If you have many skills and can't tell which descriptions collide, run the skill-auditor skill over the folder — overlap detection is exactly its job.

Symptom 4: it fires, but does the wrong thing

Loading and triggering are fine; the body is the problem:

• Steps are vague. "Write good tests" isn't a procedure. Number the steps, name the commands.
• No convention anchor. Point at a canonical example in the repo ("match the format of the last five entries") so output lands in your house style.
• No boundary. Skills inherit the model's helpfulness; without a closing line like "creating the file is the whole job — do not run the migration," scope creep is the default.
• A bundled script fails. Check the script is referenced by a path relative to the skill folder, runs from an arbitrary working directory, and — if you copied the skill from elsewhere — kept its executable bit.

Symptom 5: permission prompts interrupt the skill

The body uses tools that allowed-tools doesn't pre-approve. Two subtleties: the grant is scoped to the turn that invoked the skill and clears on your next message — recurring prompts across turns are expected behavior, not a bug — and scoped forms matter: Bash(git diff:*) approves exactly that command family, while a body that also runs git push will still prompt. List what the procedure actually runs, no more. (See the reference for the field's exact semantics.)

Symptom 6: it works in Claude Code but not elsewhere

• claude.ai: code execution must be enabled (Settings → Capabilities), and the uploaded ZIP must contain the skill folder with SKILL.md inside. Surfaces don't sync — claude.ai never sees your filesystem skills.
• Claude API: the container has no network access and no runtime package installs — a skill that fetches URLs or pip-installs works locally and fails there. Also check both beta headers and the 8-skills-per-request cap. Details in Skills on claude.ai and the API.
• Agent SDK: allowed-tools frontmatter is ignored; tool permissions come from the SDK's own allowedTools option.