Skills That Actually Fire (Free Edition)
Skills that get used, not just written
Most broken skills are not broken. They load, they validate, and they are
never invoked — because the description does not match how anyone actually
asks for the thing.
That is the problem worth solving. The file format is the easy part.
The format, briefly
A skill is a folder containing SKILL.md. The file begins with frontmatter:
---
name: my-skill
description: ...
---
(body)
The folder name must equal name.
The silent killer: a quote at the start of description
If description begins with a double quote, YAML parses it as a quoted
scalar and breaks on the first quote inside. The frontmatter loads empty.
No error. No warning. The skill exists, validates as a file, and is never
invoked. You will look everywhere except here.
Two fixes, either works:
description: Use when "the user says this" — plain start, quotes inside are fine
description: 'Use when "X" happens — single-quoted wrapper'
Just never let the very first character be ".
Catch it with the validator instead of by hand:
claude plugin validate <skills-directory>
Run this every time you touch frontmatter. It takes a second and it finds
exactly this class of bug.
Writing a description that fires
The description is not a summary of the skill. It is a match target for
how a person phrases a request. Those are different jobs.
Bad — describes the content:
description: Documentation about our deployment process.
Good — describes the moment of need, in the user's words:
description: Use when someone says "ship it", "push to prod", "release this",
or asks whether a change is live yet. Covers the deploy steps, the checks
that must pass first, and how to roll back.
Three things make the difference:
- Start with "Use when". It forces you to describe a situation, not a topic.
- Include the actual phrases people use — including the sloppy ones.
- Say what is inside, so the model knows whether opening it will help.
Proving it fires
Validation passing is not invocation. Test it in two steps:
By name — confirms the file loads and the body is readable:
ask for the skill by name, then ask a question only answerable from inside it.
If you get the right answer, the content is fine.
By phrasing — the real test:
ask for the thing the way a user would, without naming the skill. Use their
words, not yours. If it does not fire, the description is wrong — not the body.
Iterate on the description, not the content. This is where the time goes and
it is time well spent.
Converting notes into a skill
Notes get read when someone remembers to open them. A skill gets opened on
its own. That is the whole reason to convert.
When you convert, two things change:
- Strip anything account-specific or private. Credentials, personal
addresses, internal identifiers. A skill is more likely than a note to get
shared, copied, or published. - Cut to what is decided. Notes accumulate history and dead ends. A skill
should say what to do now. Keep a trap only when it is still a live trap.
Keep the body short
A skill that gets opened often is read often. Length is not thoroughness; it
is cost, paid every time it fires.
If the body is getting long, split it. One skill per situation beats one skill
that covers five situations badly and fires for none of them cleanly.
