You installed a skill, restarted, and asked the exact question it was built for. Claude shrugged and did its own thing. So now you have a Claude skill not working with no error message to point at, which is the worst kind of broken. Go down this list in order and stop at the first thing that fails.
If you are asking why is my Claude skill not loading, here are the four causes ranked by how often they bite: the folder is in the wrong place, the frontmatter is malformed, the description is too weak for Claude to ever pick the skill, or you have so many skills the listing got truncated. The first two are binary, either right or wrong, so check those first.
Step 1: Is the folder where Claude actually looks?
This is the cause behind most "claude skill not loading" reports, and it is the cheapest to verify. A skill is a directory. SKILL.md is the entrypoint inside it, and the directory name becomes the command. Per the Claude Code skills docs, a personal or project skill lives in exactly two places:
- Personal, all your projects:
~/.claude/skills/<skill-name>/SKILL.md - Project, this repo only:
.claude/skills/<skill-name>/SKILL.md
The most common mistake is nesting. People drop the file at ~/.claude/skills/SKILL.md with no directory around it. Others unzip a download into ~/.claude/skills/my-skill/my-skill/SKILL.md and end up with a doubled folder. Claude looks for <a-directory>/SKILL.md exactly one level down, so a loose file or an extra folder loads nothing, and you get a "claude code skill not found" when you invoke it by name.
Two more traps catch people here. The filename is SKILL.md, capitalized exactly that way. And if you just created ~/.claude/skills/ for the first time this session, restart Claude Code, because a top-level directory that did not exist at startup is not watched until you do. For install paths across the apps and other CLIs, see how to install a Claude skill.
Step 2: Is the frontmatter valid YAML with the right fields?
If the folder is right and the skill still will not load, the frontmatter is next. A claude skill not showing up in the / menu usually traces back here. Every SKILL.md opens with YAML frontmatter fenced by --- markers. Miss the opening --- on line one and the whole block is parsed as body text, so the metadata never registers and Claude never learns the skill exists:
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
The validation rules are stricter than most people expect. The name field maxes out at 64 characters, accepts only lowercase letters, numbers, and hyphens, and cannot contain the reserved words "anthropic" or "claude." So a skill named claude-helper, or one with an uppercase letter or a space, gets rejected outright. The description must be non-empty and under 1024 characters.
Then there is plain YAML breakage, sneakier because the fields look fine to a human. A colon inside an unquoted description (description: Deploys to prod: staging then live) makes the parser read the rest as a broken mapping, and a tab where YAML wants spaces does the same. If fields that look correct still refuse to load, paste the frontmatter into any YAML linter. Half the time it is a stray character you would never spot by rereading.
Step 3: Claude skill not working because it loads but never triggers
This is the case that drives people up a wall. The folder is right, the YAML parses, the skill is installed and fine, and Claude still solves your question some other way. That is a claude skill not triggering problem, and it almost always comes down to the description.
The mechanism is worth understanding, because it explains every fix. At startup Claude does not read your skill body. It reads only the name and description from every installed skill's frontmatter, then matches the user's message against that text. The body does not exist yet at that moment, so a description that reads like a label instead of a trigger never fires. The skill authoring best practices guide is blunt about the fix. Write it in third person, and state both what the skill does and when to use it. Their canonical example is Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. You get a capability clause, then a "Use when" clause that names the words a real user would type. Compare Helps with documents, which is dead on arrival because it matches everything and so distinguishes nothing.
At trigger time, that one field is the whole ballgame.
If your skill installed clean but never fires, rewrite the description before you touch the body. That field is the entire matcher. The full playbook is in how to write a SKILL.md description.
Step 4: Too many skills, and the listing got truncated
Rarer, but real once your collection grows. Claude loads every skill's name, but the descriptions share a character budget. Overflow it and the docs are explicit about what happens. Descriptions for the skills you invoke least get shortened or dropped first, which strips the keywords Claude needed to match your request. The skill is still loaded. Its trigger text just got cut.
Run /doctor to see whether the budget is overflowing and which skills are hit. This one has its own post, so if you are over budget, the fixes are in the Claude Code skill listing budget.
How to confirm a skill is actually loaded
Before and after every change above, run one check. Ask Claude directly: What skills are available? This is the exact verification step the docs recommend, and it splits the problem in half. If your skill is in that list, it loaded and the metadata is valid, so the cause is Step 3 or Step 4. If it is absent, you are still on Step 1 or Step 2. Pair it with /doctor to catch budget overflow, which the list will not show on its own.
Two of these four buckets exist only because hand-authoring a SKILL.md is fiddly, and they have nothing to do with what your skill actually does. Skills built with Knack ship with frontmatter that passes the name and description rules, plus a description written as a trigger and tested against real phrasing. That makes Step 2 impossible and Step 3 arrives already handled. What remains is location, one ls away from confirmed.
Most of the time, the answer to a skill that will not work is one wrong character or one folder too deep. Run the list, find the layer, and fix that layer only.