🧭 The path from zero to SKILL.md
Creating a skill is a journey with six stops: capture intent → frontmatter → body → folders → package → iterate. In this module, you go from an empty folder to a ready file. Iteration (testing and optimizing the description) is the focus of Track 4 — here, the focus is assembly.
Start tiny
A valid SKILL.md has only two parts: frontmatter with name + description, and a Markdown body. Folders are optional—create them only when the content calls for it. Don’t set up scripts/ on day one.
🏷️ Step 1 — frontmatter: kebab-case name
O name is the identifier. One rule, non-negotiable: lowercase kebab-case, matching the folder name. No spaces, uppercase letters, or underscores.
✗ Broken names
- ✗ PDF Extractor
- ✗ pdf_extractor
- ✗ PdfExtractor
- ✗ minha-skill-v2-final
✓ Correct names
- ✓ pdf-extractor
- ✓ frontend-design
- ✓ skill-creator
- ✓ supabase
💡 Tip
The folder name MUST match the name. If the folder is pdf-extractor/, the frontmatter is name: pdf-extractor. A mismatch breaks loading.
🎣 Step 2 — description: the trigger
A description is the only text always loaded and what makes the skill trigger. Follow the formula: [WHAT it does] + [WHEN to use it] + [concrete TRIGGERS]. Be pushy — Claude under-triggers by default.
the formula in practice (example of a new skill):
description: Extract structured data from PDF invoices and receipts into JSON. Use this skill whenever the user uploads a PDF invoice/receipt, asks to "parse", "extract fields", or "read" a financial document, or mentions OCR on a scanned bill.
WHAT it does
"Extract structured data from PDF invoices..." — starts with a verb and states the result.
WHEN to use
"Use this skill whenever the user uploads a PDF invoice..." — the trigger condition.
Concrete triggers
"parse", "extract fields", "read", "OCR" — keywords users actually type.
~100 words is the limit
The metadata (name + description) is Level 1 of progressive disclosure and is ALWAYS in context. Keep it around 100 words: assertive enough to trigger, concise enough not to weigh down every conversation.
📝 Step 3 — the body: imperative, When to Use, Steps
The body is Markdown in imperative ("Read the file," "Run the script"), explaining the why instead of shouting MUSTs in uppercase. A structure that works: title, one line describing what the skill does, When to Use, Steps numbered and with output examples.
body skeleton:
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean JSON.
## When to Use
Use when the user provides a PDF invoice and asks
to extract fields, parse, or read it.
## Steps
1. Run `python scripts/extract.py <file.pdf>`.
2. Validate the JSON against the schema below.
3. Return the JSON; flag any missing field.
## Output Format
{ "vendor": str, "total": number, "date": str }
✗ Bad body
- ✗"YOU MUST ALWAYS..." shouted in caps
- ✗Long paragraphs without steps
- ✗No guidance on when to use it
✓ Good body
- ✓Clear imperative + why
- ✓Numbered, actionable steps
- ✓When to Use + explicit Output Format
📁 Step 4 — when to create each folder
Folders are optional and should come from need, not aesthetics. Create only when the trigger below appears:
scripts/ — deterministic code
Create when a task has the same input → same output (convert a file, validate a schema). More reliable than instructions and runs without loading the code into context.
references/ — docs on demand
Create when the body would grow beyond 500 lines with details that matter only in specific cases. The agent reads only the relevant file.
assets/ — output files
Create when the skill generates something from a template (HTML, source code, icon, boilerplate). These are files used no output, not read as instructions.
the final tree for the example skill:
pdf-extractor/
├── SKILL.md # frontmatter + corpo
├── scripts/
│ └── extract.py # roda sem ir pro contexto
├── references/
│ └── field-map.md # lido só em casos raros
└── assets/
└── report.html # template de saída
💡 Tip
Don’t create empty folders "for the future." Every file should have a corresponding pointer in the body of SKILL.md explaining when to read or run it.
📄 Step 5 — complete template to copy
Bring it all together. This is a complete SKILL.md, ready to paste into a file, change the names, and get started. It covers frontmatter, When to Use, Steps, Output Format, and pointers to the folders.
SKILL.md — complete template:
---
name: pdf-extractor
description: Extract structured data from PDF
invoices and receipts into JSON. Use this skill
whenever the user uploads a PDF invoice/receipt,
asks to "parse", "extract fields", or "read" a
financial document, or mentions OCR on a bill.
metadata:
author: seu-usuario
version: "0.1.0"
---
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean,
validated JSON. Built for accounts-payable flows.
## When to Use
Use when the user provides a PDF invoice or
receipt and asks to extract, parse, or read its
fields. Do NOT use for plain-text data or images
without a document layout.
## Steps
1. Run `python scripts/extract.py <file.pdf>` to
pull raw fields. The script handles OCR.
2. Validate the result against the schema in
`references/field-map.md` — read it only if a
field is missing or ambiguous.
3. If the user wants a report, fill the template
`assets/report.html` with the JSON.
4. Return the JSON and flag any field you could
not extract. Never invent values.
## Output Format
```json
{ "vendor": "string", "total": 0.00,
"date": "YYYY-MM-DD", "line_items": [] }
```
## Notes
Explain to the user which fields were uncertain so
they can verify — accuracy matters more here than
speed.
Ready—now test
Save as pdf-extractor/SKILL.md, create the referenced folders and you have an installable skill. Step 6 — test, evaluate, and optimize the description in a loop — is exactly the topic of Track 4. Section 3.5, next, shows how to make the multi-file structure truly sharp.
✅ Module Summary
Next:
Module 3.5 — 🚀 Advanced Tips: real progressive disclosure, domain-based routing, scripts that run without context, and how to keep SKILL.md under 500 lines.