Claude Code Skill Not Recognized — Troubleshooting Guide

If you've created a skill — a reusable recipe card that tells Claude how to handle a repeated task — in Claude Code, but typing /skill-name produces no response, or the skill never fires on its own, the cause is almost always a small mistake in the file's location, name, or format. This guide walks you through each possible cause in order. Expect to spend about 10–15 minutes.

Before you start — prerequisites

Make sure the following are in place before working through this guide.

• Claude Code must already be installed. If it isn't, follow the official installation guide first.
• You need to be able to open and use a terminal — the text window where you type commands.
• Some bundled skills require Claude Code v2.1.145 or later. The version check is covered in Step 4 below.

Quick glossary

• Skill — A custom command recipe you register with Claude Code. Created from a single SKILL.md file.
• SKILL.md — The markdown file that holds a skill's instructions. The name must be exactly SKILL.md.
• Frontmatter — Optional settings written between --- markers at the very top of the file. Used to set the skill name, invocation mode, and similar options.
• Bundled skills — Skills that ship with Claude Code by default: /debug, /code-review, /run, /verify, /batch, /loop, /claude-api, and others.
• Personal skills folder — ~/.claude/skills/. Skills here are available in every project.
• Project skills folder — .claude/skills/ inside a specific project. Skills here work only in that project.
• disableBundledSkills — A settings key that hides all bundled skills when set to true.

Step 1 — Check the file location

The most common reason a skill is not recognized is that SKILL.md lives in the wrong folder. According to the official documentation, Claude Code looks for skills in exactly two places.

• Personal skills folder (available in all projects): ~/.claude/skills/skill-name/SKILL.md
• Project skills folder (current project only): project-root/.claude/skills/skill-name/SKILL.md

For example, a skill called summarize-changes that you want everywhere must live at exactly this path:

~/.claude/skills/summarize-changes/SKILL.md

Run this command to check whether the file is actually there:

ls ~/.claude/skills/summarize-changes/

Success looks like: SKILL.md appears in the output. If you see "No such file or directory," the path is wrong. Create the correct directory and move the file:

mkdir -p ~/.claude/skills/summarize-changes
mv /wrong/path/SKILL.md ~/.claude/skills/summarize-changes/SKILL.md

If you used the older .claude/commands/ folder structure, your files still work — the documentation confirms both formats are supported. New skills are best placed under .claude/skills/.

Step 2 — Check the file name

The file name must be exactly SKILL.md — uppercase, no variations. Names like skill.md, Skill.md, or SKILLS.md will not be recognized.

Confirm the exact name with:

ls -1 ~/.claude/skills/summarize-changes/

Success looks like: SKILL.md appears with that exact casing. To rename a file with the wrong case:

mv ~/.claude/skills/summarize-changes/skill.md \
   ~/.claude/skills/summarize-changes/SKILL.md

⚠️ Note for macOS users: macOS file systems are often case-insensitive by default, so skill.md and SKILL.md may look the same in Finder. Claude Code, however, expects the exact casing — always save the file as SKILL.md.

Step 3 — Check the frontmatter format

Frontmatter is optional. If you include it, incorrect formatting can cause the entire skill to be ignored. Frontmatter must be wrapped by --- lines at the very top of the file.

If frontmatter feels complicated, skip it entirely for now. The skill name is derived automatically from the directory name — a file at ~/.claude/skills/summarize-changes/SKILL.md becomes /summarize-changes with no frontmatter needed.

Step 4 — Check the Claude Code version

According to the official documentation, the bundled skills /run, /verify, and /run-skill-generator require Claude Code v2.1.145 or later. If your version is older, those commands will be missing or non-functional.

Check your current version:

claude --version

Success looks like: A version number of 2.1.145 or higher. If it's lower, update with:

npm install -g @anthropic-ai/claude-code

After updating, close the terminal completely and open a fresh window so the new version takes effect.

Step 5 — Check whether bundled skills are disabled

If built-in skills like /debug, /code-review, or /run are missing, the disableBundledSkills setting may be turned on. When this key is set to true, all bundled skills are hidden.

Open either ~/.claude/settings.json (personal) or .claude/settings.json (project) and look for:

"disableBundledSkills": true

Change true to false, or delete the line entirely, then restart your session.

Common blockers and fixes

Directory name uses uppercase or underscores

The skill directory name should use lowercase letters and hyphens only. A folder named SummarizeChanges or summarize_changes may produce an unexpected command name or fail to register. Rename it to summarize-changes and restart the session.

Session not restarted after creating or editing the skill

⚠️ Important: Claude Code reads skill files when a session starts. If you create or edit a skill file while a session is already running, the change won't be picked up until you exit and start a new session. Press Ctrl+C or type exit to close the current session, then run claude again.

Skill placed in a non-default directory

According to the documentation, skills outside the two default locations must be explicitly registered in settings. If you stored a skill in a custom path, verify that path is configured as an additional skills directory. For the exact setting name, consult the version of the official docs that matches your installed Claude Code version.

SKILL.md body is empty or too brief

If the skill file contains no instructions or only a single vague line, Claude may not know when or how to invoke it automatically. Write enough content to explain clearly: what situation calls for this skill, and what steps Claude should follow.

If nothing works after all five steps

Try these additional actions in order:

1. Close the terminal completely, open a fresh window, and start Claude Code again.
2. Type /help to see the list of commands Claude Code currently recognizes. Check whether your skill name appears.
3. Reduce the skill file to its simplest possible form — no frontmatter, just one paragraph of plain instructions — and test again. This confirms whether the file itself is being loaded at all.
4. Create a brand-new test skill in the personal folder (~/.claude/skills/test-skill/SKILL.md) with minimal content. If that test skill works, the problem is specific to something in your original skill's name or content.

Success looks like: Typing /skill-name causes Claude to follow the instructions in the skill file, or — if you set invocation: auto — Claude mentions and runs the skill on its own when the context is relevant.

Next steps — getting more from skills

Once your skill is recognized, consider these additions.

• Add supporting files: Place reference files (such as a checklist.md) inside the skill directory. You can reference them from SKILL.md for richer, more precise instructions.
• Try bundled skills first: Before building custom skills, explore what /debug, /code-review, and /run can already do. Build custom skills for the gaps they don't cover.
• Keep project-specific skills in the project folder: If a skill applies to only one codebase, put it in that project's .claude/skills/ rather than the personal folder — it stays organized and won't clutter other projects.