Claude Code Says 'No Skills Found' Even Though My SKILL.md Exists: What's Wrong?

If Claude Code says "No skills found" but your SKILL.md file is sitting right there in your editor, the file exists but it isn't where Claude is looking, isn't structured in a way Claude recognizes, or wasn't saved before the session started. Four causes cover nearly every case. Claude Code reached 115,000 active developers by July 2025 (Deedy Das, Menlo Ventures, 2025). Skill discovery errors are the most common setup friction at that scale.

TL;DR: Claude Code requires SKILL.md files at .claude/skills/[skill-name]/SKILL.md. Valid YAML frontmatter with a name field, exact SKILL.md casing, and saving before session start are the three non-path requirements. Check these four things in order. At AEM, these four causes account for over 90% of skill discovery failures in new projects.

Why Does Claude Code Ignore My SKILL.md Even Though the File Exists?

The most common cause. Claude Code only finds SKILL.md files at .claude/skills/[skill-name]/SKILL.md relative to the project root. This path structure is not flexible. The project root is the directory where you opened Claude Code, not the directory where your source files live. A file even one folder level off is invisible to the scanner.

Common wrong paths:

The .claude/ directory must be at the project root, not inside a src/ folder or any other subdirectory. If you're working in a monorepo, the .claude/ directory for each project should live at that project's root.

Check your path:

ls .claude/skills/

If the output shows SKILL.md directly (without a subfolder), the skill is in the wrong place. Move it: mkdir -p .claude/skills/my-skill && mv .claude/skills/SKILL.md .claude/skills/my-skill/SKILL.md.

In 8 of our first 10 client onboarding calls, the "no skills found" issue traced to one of two things: wrong folder path or a missing name field in the frontmatter. We now walk every client through a 2-minute path check before any other troubleshooting.

Why Won't Claude Register My Skill Even With a Valid-Looking SKILL.md?

Claude parses the YAML frontmatter between the --- delimiters to discover skills. If the frontmatter is malformed or the name field is absent, Claude reads the file but doesn't register it as a skill. The file passes the filesystem scan and silently drops out of the registry, with no error message to indicate what failed.

The frontmatter must include at minimum:

---
name: my-skill-name
description: "One-line description of what this skill does and when to trigger it."
---

Four frontmatter problems that silently fail:

• Missing --- delimiters: if the file starts with the YAML content but no opening ---, or if either delimiter is missing a hyphen, frontmatter parsing fails entirely.
• Missing name field: without name, Claude has nothing to register the skill under. The description loads but the skill has no identity in the /skills listing.
• Colon in an unquoted description: description: One skill: for code review breaks YAML parsing because the second colon isn't inside quotes. Always quote the description value.
• Multiline description: YAML treats a line break in a frontmatter value as a new key. A description that wraps onto the next line creates a parsing error. The description must stay on one line.

The official Claude Code documentation confirms this behavior: "If omitted, [the name field] uses the directory name." A missing name still loads a skill by folder name, but without the description, Claude cannot match it semantically and the /skills listing shows no description (Anthropic, Claude Code Docs, 2025). Verify your frontmatter with a YAML linter. Paste it at yaml.org/spec or use python3 -c "import yaml; yaml.safe_load(open('.claude/skills/my-skill/SKILL.md').read())" to check for parsing errors.

Why Does My Skill Work on macOS but Not on Linux or CI?

The filename must be SKILL.md, with uppercase SKILL. On macOS, the filesystem is case-insensitive and skill.md works. On Linux (including WSL) and CI environments such as GitHub Actions and CircleCI, the filesystem is case-sensitive. skill.md and Skill.md are not found. Rename the file to fix it.

If you're developing on macOS but your team runs on Linux, a lowercase skill.md works locally and fails in production. Jake Wharton documented this pattern in detail: "most engineers use macOS for local development, the OS silently corrects casing mistakes, and everything seems fine until you deploy to a Linux server or run CI in a Linux container" (jakewharton.com, 2019). The fix: rename the file.

mv .claude/skills/my-skill/skill.md .claude/skills/my-skill/SKILL.md

This is a one-time fix. Claude Code documentation consistently uses SKILL.md in uppercase. Match it exactly.

Why Doesn't Claude See a Skill I Just Created in This Session?

Claude Code reads the skills directory when a session opens, not continuously. If you created or modified SKILL.md after the session started, Claude doesn't see the changes until you restart the session. This is a deliberate design decision: on-open scanning is fast and predictable; continuous polling would add latency to every session interaction.

This is a timing issue, not a structural one. The fix is to restart the Claude Code session. There is no "reload skills" command that refreshes the discovery scan mid-session.

If you're using Syncthing, Dropbox, or another sync service, check for conflict files. Sync services create duplicate filenames like SKILL (Conflict 2026-04-22).md when files are modified on two machines simultaneously. Claude Code looks for SKILL.md specifically. A conflict file sits alongside it invisibly and can cause confusion about which version is actually loaded.

"Developers don't adopt AI tools because they're impressive — they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

A METR study of experienced developers using AI coding tools found that setup friction, not model capability, was the primary driver of slower task completion (METR, July 2025). A skill that fails silently on setup fails that test. Path and frontmatter errors are the first friction that kills Claude Code adoption.

What If None of These Apply?

Two additional causes block skill discovery when the basics check out: a folder name starting with _ or . that the scanner skips, or a .claudeignore rule excluding the skills directory. Both produce the same silent failure as a wrong path. We see them surface on 2 of every 10 onboarding calls where path, frontmatter, casing, and timing are correct.

• The skill folder name matches a reserved name: skill folder names starting with _ or . are ignored by the discovery scanner. Names like _helpers or .utils won't load.

• The project has a .claudeignore file: like .gitignore, this file tells Claude Code which paths to skip. If the skills directory is inadvertently listed, all skills in it are invisible. Claude Code limits skill description text to 1,536 characters per entry in the skill listing to control context usage (Anthropic, Claude Code Docs, 2025). A .claudeignore exclusion removes the skill entirely from that listing.

For the standard troubleshooting path when skills aren't loading at all, see Why Isn't My Claude Code Skill Working?. To verify a skill loaded after fixing these issues, see How Do I Verify That Claude Loaded My Skill Content Correctly?.

FAQ

What's the exact folder path Claude Code uses to find skills? .claude/skills/[skill-name]/SKILL.md relative to the project root. The skill's folder name becomes its identifier in the /skills listing. There is no alternative path.

Do user-level skills and project-level skills load from different locations? Yes. Project-level skills are at .claude/skills/ inside the project directory. User-level skills are at ~/.claude/skills/ in your home directory. Both load in the same session but from different locations. A wrong path at either level produces the same "not found" behavior.

Can I use symlinks to point a skill folder at a shared location? Symlinks work on macOS and Linux. They don't work reliably on Windows (requires elevated permissions) or in some WSL configurations. Use actual files or git submodules for shared skill libraries instead.

Why does my skill load on macOS but not on the CI server? Almost certainly filename casing. macOS ignores casing. Linux requires exact matches. Rename skill.md to SKILL.md and commit the rename explicitly in git: git mv skill.md SKILL.md.

I added the name field but Claude still doesn't see the skill. What else could it be? Check whether the --- delimiters are intact, whether the description value is quoted, and whether the file was saved before the current session started. If all three are fine, check whether the skill folder name starts with _ or ..

Do I need to restart Claude Code after creating a new skill? Yes. Claude Code scans the skills directory at session start, not continuously. New skills created mid-session aren't visible until the session restarts.

Last updated: 2026-04-22