A skill is a folder with a SKILL.md inside it: a short YAML head and some Markdown instructions. The instructions are the part people spend their time on, and the description is the part that decides whether those instructions are ever read. It is matched against the task at hand, so one that says what the skill is about but never says when to reach for it will sit unused indefinitely — with no error to tell you why. This builder writes the file and checks that field hardest: whether it names a trigger, whether it is long enough to match on, and whether it wastes its opening words. The name is checked against the folder-naming rules, and the instructions against the length below which they rarely change anything.
Features
Name checked against the folder-naming rules, with a corrected version offered
Description checked for a trigger clause — the thing that actually causes a match
Warns when a description is too short to carry any signal
Optional tool allow-list, picked rather than typed
A readiness score that separates blocking errors from suggestions
The exact path the file belongs at
Frontmatter quoted correctly, so a colon in the description does not split the value
Downloads as SKILL.md, ready to drop into place
How to use the Skill Builder
Name the skill in lowercase with hyphens
Write a description that says both what it does and when to use it
Write the instructions as Markdown
Read the findings, then download SKILL.md
Example
Input
name: release-notes
Output
description: Writes release notes from a range of git commits. Use when the user asks for a changelog.
The “Use when…” clause is what turns a subject into a trigger.
Common errors & troubleshooting
The skill never seems to be used. — Almost always the description. It has to say when the skill applies, in the words someone would actually use — file types, task names, phrases they would type.
The name is rejected. — It doubles as the folder name, so it must be lowercase letters, digits and single hyphens. A corrected version is suggested when yours does not fit.
My description contains a colon and the file breaks. — It should not — values are quoted when they need it. If you hand-edit the file afterwards, quote anything containing a colon followed by a space.
The skill loads but changes nothing. — Very short instructions rarely shift behaviour. Say what to produce, how to work, and what not to do.
Frequently asked questions
What makes a skill description good?
It answers two questions in one or two sentences: what the skill does, and when it should be used. The second half is what gets matched, so name the file types, the task, and the phrasing a person would use. “Helps with documents” matches nothing in particular.
Where does the file go?
In a folder named after the skill, inside a skills directory — the path is shown under the editor and updates as you type the name. The folder name and the name field should agree.
Should I set an allowed-tools list?
Only when the skill genuinely needs fewer tools than the session has. Leaving it empty means the skill inherits whatever is available, which is usually what you want; narrowing it is a way of keeping a focused skill focused.
How long should the instructions be?
Long enough to be specific and no longer. A few sentences rarely changes behaviour; several pages tends to get skimmed. Sections with headings survive editing better than one long block.
Does the file get validated anywhere else?
The loader will accept a file with a weak description perfectly happily — that is the problem. Nothing downstream tells you the skill is unmatchable, which is why the check belongs before you ship it.
Related tools
Skill Linter — Paste a SKILL.md and see what stops it being matched to a task.
Subagent Builder — Build a subagent definition file with its tools and model set.
Slash Command Builder — Build a custom slash command, with arguments and a tool allow-list.