How-to · 7 min · 5 steps
How to create an AI skill
Write a skill file that actually gets selected: frontmatter, a description that states a condition, trigger phrases, and the right body size.
A skill packages a reusable capability: a name, a description that decides when it loads, and a body of instructions loaded only once it does.
The economics are the whole design. The description is always in context and must be short. The body loads on demand and can afford to be thorough. Get that split backwards and the skill is either useless or expensive.
Name it as a slug
Lowercase, hyphen-separated, under about sixty characters. It is an identifier used in paths and references, so spaces and capitals cause the same problems they cause anywhere else in a toolchain.
Write the description as a condition, not a title
This is the step that decides whether the skill ever fires. "A tool for reviewing prompts" matches almost nothing. "Use when the user asks to reduce token usage, understand why a prompt is expensive, or estimate monthly API cost" matches the way people actually ask.
AI Skill File BuilderFrontmatter validation, trigger-quality checks, and the token cost of what loads into context.List trigger phrases in the user’s words
Three or more, written as the literal words someone would type. Include the phrasings you personally would not use — your own vocabulary is the one case already covered.
Write an operational body
Numbered steps, grouped rules, and one worked example. No preamble: the model has already decided to load the file, so it does not need selling. Keep it under about three thousand tokens — past that it is usually two skills.
Validate before shipping
Broken skills fail silently: they simply never trigger, and you conclude the mechanism does not work. Check the frontmatter parses, the name is a slug, and the description states a condition.
Skill File Frontmatter ValidatorThe checks that decide whether a skill ever gets loaded.
What goes wrong
Putting rare instructions in the system prompt instead
It is the obvious place and the most expensive one. Anything conditional and large belongs in a skill, where it is paid for only when it fires rather than on every request forever.
One large skill instead of two small ones
A big skill needs a description broad enough to cover everything inside it — which makes it vague, which makes it match badly. Splitting gives each half a precise description and halves the load cost.
Frequently asked questions
- Why does my skill never trigger?
- Almost always the description. If it describes what the skill is rather than when to use it, there is nothing for the model to match a user request against.
- How large should a skill be?
- Small enough that loading it is cheap, large enough that it is worth loading. Past roughly three thousand tokens in the body, look for the natural split.
Tools for this
- AI Skill File BuilderFrontmatter validation, trigger-quality checks, and the token cost of what loads into context.
- Skill File Frontmatter ValidatorThe checks that decide whether a skill ever gets loaded.
- System Prompt to Skills SplitterSplits a system prompt into what belongs there and what belongs in a skill.
Read next
- How to build an AI agent — Eight steps from empty file to a config you can ship, priced as you go.
- How to write a system prompt — Seven steps, in the order that matters, with the cost of each decision.