Debugging
SKILL.md errors that stop a skill
Most “my skill does not work” reports are structural: the file is valid Markdown but invalid as a skill. These are the five failures we see most, and the fix for each.
1. No frontmatter
A skill file must start with a YAML block:
---
name: pdf
description: Read, split, merge and fill PDF files. Use when a task involves PDF documents.
---
If the file starts with a heading or a paragraph, the agent has no name and no trigger description to work with. Fix: put the block first, with nothing above it — not even a blank line.
2. The name is not a valid identifier
Use lowercase letters, numbers and single hyphens: pdf, frontend-design, seo-audit. Spaces, capitals, underscores and dots break routing in several agents.
3. The description does not say when to use it
The description is the trigger. “A helpful skill for documents” matches almost nothing and everything. Write the job and the cue:
Read, split, merge and fill PDF files. Use when a task involves PDF documents, forms, or extracting text from a PDF.
Keep it under 1,024 characters and front-load the verbs.
4. The file is in the wrong place
Skills are discovered by path, not by search. For Claude Code:
- personal:
~/.claude/skills/<name>/SKILL.md - project:
<project>/.claude/skills/<name>/SKILL.md
A file at ~/skills/pdf.md or ~/.claude/skills/pdf.md (file, not folder) will not load. The folder name and the name: field should match.
5. The body is a placeholder
A skill with a good description and an empty body triggers and then does nothing. The body is the procedure: steps, order, checks, examples. If it is under a hundred characters, it is not a skill yet.
Two more that bite later
Duplicate names. Two skills with the same name shadow each other. Check your skills folder before installing a new one.
Scripts without paths. If the body says “run the script” without the path relative to the skill folder, the agent will guess. Use paths relative to the skill directory and say so explicitly.
Check it in ten seconds
Paste the file into our SKILL.md validator — it checks the frontmatter, the name format, the description length and placeholder text in the browser, without uploading anything.
Community notes
Found a broken install? Know a skill we missed?
One line is enough: the skill name, what happened, and the command you ran. We read every note and fix the index.