Claude skill not showing up or not triggering? How to fix it

1. Check whether the skill loaded at all

Ask Claude What skills are available? and type / to see the menu. If the skill is listed, skip to step 4. If not, start Claude Code with debug logging and look for errors about your skill:

2. Is it in a folder the agent reads?

• The file is named exactly SKILL.md and sits in its own folder: ~/.claude/skills/my-skill/SKILL.md or .claude/skills/my-skill/SKILL.md.
• You copied the skill folder itself, not the whole repository it came from.
• Project skills are under the directory you started Claude Code in, or one of its parents up to the repo root.
• Other agents use their own folders: Codex, for example, reads .agents/skills/ in a project and ~/.agents/skills/ for your user.

Full list of paths, per OS and per agent: where skills are stored.

3. Does the frontmatter parse?

• The opening --- must be the very first line. If anything comes before it, even a blank line or a title, the whole file is treated as plain content.
• Invalid YAML doesn't stop the skill loading; it loads with no fields, so /skill-name works but Claude never matches the description. Quote values that contain a colon.
• Field names must be exact. A misspelled field (descripton) is ignored without an error.
• Names containing characters such as <, >, control characters or zero-width spaces are refused; search the debug log for [names].

Claude Code v2.1.233 and later can list every SKILL.md whose frontmatter doesn't parse:

See the SKILL.md format guide for every valid field.

4. Listed, but never triggers

• Rewrite the description to say what the skill does and when to use it, with the words you actually type ("release notes", "changelog", "what shipped").
• Rephrase your request closer to the description, or invoke it directly with /skill-name.
• Check the frontmatter for disable-model-invocation: true, which means manual use only.
• If the skill sets paths, it only activates for matching files inside Claude's working directory, not in a sibling worktree.

5. Triggers when it shouldn't

Make the description narrower, and say what the skill is not for. If you only ever want to run it by hand, add disable-model-invocation: true.

6. The wrong skill runs

Two skills with the same name shadow each other: enterprise beats personal, and personal beats project. A skill also wins over a .claude/commands/file of the same name. Rename one, or remove the copy you don't want.

7. Many skills installed: descriptions get cut

Claude Code puts every skill's name and description in a listing with a character budget of about 1% of the model's context window. When it overflows, descriptions of the skills you use least are dropped, and without its description a skill can't be matched. Each entry (description plus when_to_use) is also capped at 1,536 characters. To fix it:

• Run /doctor to see the listing's cost and the biggest contributors, and /skill-doctor to find skills you don't use.
• Put the key use case first in long descriptions.
• Raise the budget in settings, e.g. to 2% of the context window:

{
  "skillListingBudgetFraction": 0.02
}

8. Claude follows the skill, then drifts

• The skill's text is added once when it is invoked and not re-read; after the conversation is compacted only its start may remain. Invoke it again, and put the most important instructions at the top.
• Word guidance so it applies to the whole task ("run the tests after every edit", not "run the tests").
• Rules that must hold every time belong in a hook, which runs on every matching event regardless of the model. A skill can register hooks with its hooks field.

9. Personal skills disappeared

Look in ~/.claude/skills/.trash/. Before Claude Code v2.1.280, a manifest.json file in ~/.claude/skills/ could move skill folders there. Move the folder back before the trash is cleaned up (30 days by default). Skills synced from your claude.ai account live separately in a synced subfolder.

Still stuck?

Reinstall from a known-good source: every skill page in the directory has a copy-ready install command and the full SKILL.md, so you can compare it with your copy. The install guide covers the skills CLI, manual install and plugin marketplaces.