Two checks, then read down the right list
- Ask Claude what it can see. Type "What skills are available?" in a fresh chat. The listing always contains every skill name, so if yours is missing, the problem is loading. If it is there and never fires, the problem is what Claude has to match against.
- Check the file parses. In Claude Code, run
claude plugin validate ~/.claude/skillsfor your personal skills, orclaude plugin validate .claude/skillsfor a project. It needs version 2.1.233 or newer, and it finds files whose frontmatter does not parse. - If it flags something, start the session with
--debugto see the parse error itself.
That second check matters because of one behaviour in Anthropic's own documentation: when the frontmatter is malformed, Claude Code loads the body of the file with empty metadata. So the slash command keeps working, the file looks fine, and Claude has nothing to match your request against.
Three of the causes below produce no signal in either check, because they only show themselves where the skill fails. Those are marked.
If it is missing from the list
The file is not in the shape Claude looks for.
What happens: a loose .md file sitting in the skills folder is never read. Claude wants a folder per skill with SKILL.md inside it.
Fix: ~/.claude/skills/<skill-name>/SKILL.md, or .claude/skills/<skill-name>/SKILL.md for a project. The command comes from the folder name, so renaming the name field does not change what you type.
The frontmatter is not on line one.
What happens: Claude Code reads frontmatter only when the opening --- is the very first line. A blank line or a title above it turns the whole file into plain content.
Fix: delete anything above the opening marker. Check for a stray --- further down the body too, because a horizontal rule gets read as a second frontmatter block.
Automatic loading is switched off.
What happens: a skill carrying disable-model-invocation: true keeps its description out of context entirely, so it can look missing while only ever running when you type it.
Fix: remove that line. If you downloaded the skill rather than wrote it, check this before anything else.
It is in a folder that surface never reads. Shows up only on the surface where it fails.
What happens: Cowork and cloud sessions, including scheduled ones, do not read ~/.claude/skills/ on your machine at all. They load the skills enabled on your account.
Fix: enable it for your account through Customize in the desktop sidebar, or in the skills settings on the web. Avoid naming a folder synced, which Claude Code uses for its own downloads.
Code execution is switched off. Shows up only in the Claude apps.
What happens: skills need it there, and the option can be greyed out entirely if an administrator has disabled it.
Fix: turn it on under Settings, then Capabilities. On a work account, an administrator enables it in the organisation settings.
There is a field the upload does not allow. Shows up only when you upload.
What happens: uploading to the Claude apps fails outright with a named error, such as Unexpected key(s) in SKILL.md frontmatter: argument-hint. Claude Code accepts about twenty fields. The portable format accepts six.
Fix: keep only name, description, license, compatibility, metadata and allowed-tools. Claude Code accepts all six, so writing to that set works everywhere.
If it is in the list and never fires
Your description is being shortened away. Check this before you rewrite anything.
What happens: the listing has a character budget of roughly one percent of the context window. When it overflows, descriptions get shortened, starting with the skills you use least, so the keywords yours needed are gone while the name stays.
Fix: run /doctor to see what the listing is costing, and /skill-doctor to find the ones you never call. Installing a large community pack is a common way to break a skill that used to work.
The description wrapped onto a second line.
What happens: the parse stops at the line break and what Claude ends up matching against is no longer your sentence. Reported in an issue opened on 14 September 2026 by someone whose skill had never fired in around 200 sessions.
Fix: put the whole description on one physical line, however long it gets.
It describes the skill, and not the request.
What happens: the description is the only thing Claude matches your words against, so one that says what the skill does without saying when to use it never gets picked.
Fix: say both, in the third person, using the words you actually type. Helps with documents matches nothing. A description naming the job, the moment, and what tends to be in the message does.
The prompt: rewrite a description so Claude actually picks it
If your skill is listed, the budget is fine and it still sits there, this is the one to fix. Paste your frontmatter under the prompt.
You are rewriting the description line of a SKILL.md file so that a model actually reaches for the skill when I need it. The description is the only thing the model sees before it decides, so a description that reads beautifully and matches nothing is a skill that never runs. Mine has been sitting there unused and I want to know why before I rewrite anything. WHAT I WILL PASTE BELOW My current SKILL.md frontmatter, and usually the body too. If I paste only the description, work with that and say what you could not check. ABOUT HOW I ACTUALLY WORK (I fill this in once) - What the skill does, in my own plain words: [one or two sentences, the way you would explain it to a colleague] - The real requests I would be making when I want it: [three or four, typed the lazy way you actually type them, e.g. "fix this", "why is this broken", "tidy this up", "can you check it". Not the polished version] - The things that are usually in the message when I want it: [e.g. "a pasted error message", "a spreadsheet", "a link to a document", "a half-written email", "nothing, just a question"] - When it should NOT fire: [e.g. "not for writing something new from scratch", "not for anything to do with code". Write "not sure" if you do not know] STEP 1: TELL ME WHAT IS WRONG WITH THE CURRENT ONE Check it against each of these and say pass or fail with one line of reasoning. Do not rewrite anything yet. 1. Is the whole description on one physical line? A line break here silently breaks it. 2. Is it written in the third person, describing the skill, rather than as "I can help you..."? First person causes matching problems. 3. Does it say both WHAT the skill does and WHEN to use it? One without the other is the most common failure. 4. Does it contain the actual words from my lazy request list above, or only formal synonyms of them? 5. Does it name the things that show up in the message, not just the actions? Many real requests contain no verb at all. 6. Does it say where the boundary is, so it does not shadow a neighbouring skill? 7. Is it under 200 characters? Different surfaces publish different limits, so the tightest one is the safe target. If it cannot fit, tell me what I am losing. STEP 2: GIVE ME THREE REWRITES Write three versions, each on one line, each under 200 characters, each in the third person. - Version A: the tightest one that still covers what and when. - Version B: the one that leans hardest on my lazy phrasings. - Version C: the one that leans hardest on the things in the message, for requests with no verb in them. Under each, name in one line what it would catch that the others would miss. STEP 3: GIVE ME THE TEST Write five requests, in my voice, the way I would really type them on a tired Thursday. Mix them up: some with the obvious words, some without, and include one that should NOT match, so I can check it does not over-fire. Tell me to open a fresh session and try all five, and that four out of five matching is the bar. NEVER - Never invent what my skill does. If the body does not make it clear, ask me before you write a word of it. - Never pad the description with keywords that do not describe the skill. It gets shortened when the list is crowded, and the padding is what survives. - Never tell me it looks good if it fails a check above. Say which check and why. - Never change the name field, the file layout or anything outside the description unless I ask. AT THE END Tell me plainly whether you think the description was the real problem. If the frontmatter I pasted has something else wrong with it, such as a field that is not allowed, a missing opening marker, or a stray line of three dashes in the body, say so, because no rewrite will fix those.
The honest bit
- Sometimes it genuinely is not your file. One issue opened on 18 September 2026 reports a version where none of twelve personal skills on disk registered at all. Check your version before rewriting a file that was fine.
- The rules differ by surface. A skill can work perfectly in Claude Code and fail on upload, or load on your machine and be invisible to a scheduled run. That is the single most useful thing to know here.
- The published character limits disagree. The help centre says 200 for a description, the developer docs say more. Staying under 200 is the version that passes everywhere.
- A skill you synced from your account can be moved aside. When account syncing is turned off, those skills go to a trash folder inside your skills directory rather than vanishing, so look there before rewriting from memory. A skill you wrote and deleted yourself is just deleted.
Do it now
Ask a fresh chat what skills are available, then run the validate command on your skills folder. Those two answers put you in one of the two lists above, and the list tells you which handful of causes to read.
If you want a second opinion on the file itself, skillscheck is a free open-source checker that goes past whether the file parses and warns when a description is too short or has no hint about when to use it.
A few quick questions
Do I have to restart after adding a skill?
Only the first time. Claude Code watches the skills folders and picks up edits mid-session, but if you have just created a top-level skills directory that did not exist when the session started, restart so it can watch it.
Why does my skill work when I type it but never on its own?
That is the signature of broken frontmatter. The body still loads, so the slash command runs, while the metadata comes through empty and the model has nothing to match against. Run the validate command and it will show up.
How do I zip a skill for the Claude apps?
Zip the folder, not the files. The archive should open to a single folder named after the skill, with the file inside it. Zipping the contents at the top level is a common reason an upload is rejected.