SKILL.md Format
A SKILL.md is Markdown with a YAML frontmatter block. The frontmatter tells the agent when to use the skill; the body tells it how. Get the frontmatter wrong and the best instructions in the world never load.
Minimal valid file
---
name: og-image
description: Create 1200x630 social preview images from a title and optional screenshot. Use when the user asks for an OG image, social card, or link preview.
---
# OG Image
1. Read the title and the page URL.
2. Pick a layout from `references/layouts.md`.
3. Render at 1200x630 with 80px safe margins.
4. Export PNG under 300 KB.Two fields are required. That's a valid skill.
Field reference
| Field | Required | Rules |
|---|---|---|
name | Yes | Max 64 chars; lowercase letters, numbers, hyphens; no leading/trailing hyphen |
description | Yes | Max 1024 chars; non-empty; says what it does and when to use it |
license | No | License name or a reference to a bundled file |
compatibility | No | Max 500 chars; environment requirements |
metadata | No | Arbitrary key-value pairs (version, author) |
allowed-tools | No | Restrict which tools the skill may use |
The description is the product
Everything else can be mediocre and the skill still works; a bad description makes it invisible. Write it as: capability + trigger phrases.
Weak:
Helps with images.
Strong:
Create 1200×630 social preview images from a title and optional screenshot. Use when the user asks for an OG image, social card, or link preview.
Body structure that works
- One sentence: what this produces
- Inputs required
- Numbered steps
- Output format and constraints
- Failure cases ("if no screenshot, use the type-only layout")
Keep it under ~500 lines. If it's longer, move reference material into references/ and load it only when needed.
Optional directories
| Folder | Holds | Loaded |
|---|---|---|
scripts/ | Executable helpers | On demand |
references/ | Long docs, checklists | On demand |
assets/ | Fonts, templates, images | On demand |
This is progressive disclosure: the agent reads the map first, then opens the drawer it needs.
Validation checklist
- [ ] Frontmatter parses as YAML
- [ ]
namematches the folder name - [ ]
descriptionincludes at least three phrases a user would actually type - [ ] Steps are imperative and ordered
- [ ] Every referenced file exists
- [ ] Output format is explicit (size, file type, naming)
FAQ
Can I add custom fields? Yes, under metadata. Unknown top-level fields may be ignored.
Does the filename have to be SKILL.md? Yes, in every implementation I've checked.
Can one skill call another? It can instruct the agent to use another skill, but don't build deep chains — behaviour becomes hard to predict.