🧱 General structure
A SKILL.md has exactly two parts. At the top, a block of YAML frontmatter between two delimiters ---. Just below, the Markdown body with the behavior instructions. This separation is what every compatible agent expects to find.
Skeleton of a SKILL.md:
--- name: nome-da-skill description: What it does and when to use it. --- # Skill Title Markdown instructions the agent follows when the skill is triggered.
💡 Tip
The frontmatter has only two required fields: name e description. Everything beyond that (license, allowed-tools, etc.) is optional. Always start with those two.
🏷️ name field
O name is the skill’s unique identifier. Fixed convention: kebab-case (hyphen-separated words), all in lowercase, and usually the same as the name of the folder containing the SKILL.md.
✗ Poorly formed name
- ✗Frontend_Design
- ✗my skill
- ✗ReactBestPractices
- ✗skill (too generic)
✓ Correct name
- ✓frontend-design
- ✓react-best-practices
- ✓skill-creator
- ✓supabase-postgres-best-practices
Why kebab-case matters
The name is used in commands, logs, and as a unique key in the agent. Spaces and uppercase letters break the reference, and generic names like skill collide with other installations. The most installed skills on skills.sh— find-skills (1,8M), frontend-design (488k) — they all follow the same pattern.
🎣 Description field — the trigger
A description is the most important field in the file. It’s the sentence the agent reads to decide whether to activate the skill. A good description says two things: WHAT the skill does and WHEN use it — preferably with concrete examples of situations.
✗ Vague description
"Helps with frontend."
Doesn’t say when to trigger. The agent will almost never activate it.
✓ Description with a trigger
"Builds frontend interfaces. Use when the user asks you to build web components, pages, landing pages..."
Says what it does AND lists use cases.
Recommended pattern:
description: <O QUE faz>. Use this skill when <QUANDO usar> (examples include <gatilhos concretos>).
💡 Tip
The description always stays loaded in context (Level 1 of progressive disclosure — see module 3.2). So it's worth being specific and even a little "pushy": Claude tends to under-trigger skills.
📝 The body in Markdown
Below the frontmatter comes the body: the actual instructions. Write in imperative mood ("Create," "Use," "Prefer"), explain the WHY instead of shouting MUSTs in uppercase, and show output patterns and examples what the result should look like.
✗ Weak body
- ✗List of MUSTs in ALL CAPS without context
- ✗Rules without explaining why
- ✗No examples of expected output
- ✗Long, generic paragraphs
✓ Effective body
- ✓Imperative, direct instructions
- ✓Explain the reason for each choice
- ✓Show examples of good and bad output
- ✓Short sections with clear headings
Real excerpt from the frontend-design body:
## Frontend Aesthetics Guidelines Focus on: - **Typography**: Choose fonts that are beautiful, unique... Avoid generic fonts like Arial and Inter. - **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables...
Imperative + why
Notice the example above: each guideline is a command ("Focus on", "Choose", "Commit to") followed by the reasoning. This is much more effective than "YOU MUST ALWAYS..."—the agent absorbs it better when it understands the intent.
📁 Folder structure
A professional skill is more than just the SKILL.md. Three conventional folders organize the resources around it, each with a clear purpose.
scripts/ — deterministic code
Scripts that perform repeatable tasks without relying on the agent’s judgment. They run without loading the code into context — the agent just calls them and gets the result.
references/ — docs on demand
Extensive documentation the agent reads only when needed. Keeps SKILL.md short while providing depth when necessary.
assets/ — templates
Supporting files: templates, boilerplates, images, configs that the skill uses or copies into the user’s project.
Typical skill layout:
minha-skill/
├── SKILL.md
├── scripts/
│ └── gerar.py
├── references/
│ └── guia-completo.md
└── assets/
└── template.html
💡 Tip
Don’t create empty folders in advance. Start with just SKILL.md and add scripts/ or references/ when the content truly warrants it—each folder is Level 3 of progressive disclosure.
🔬 Minimal vs. Real Example
To wrap up, compare the extremes. A minimal SKILL.md fits in 5 lines. A production skill—like frontend-design from Anthropic (488.299 installs) — its frontmatter includes a description rich in trigger terms.
Minimum:
--- name: git-commit-style description: Formata mensagens de commit no padrão Conventional Commits. --- Sempre escreva commits no formato tipo(escopo): descrição.
Real — anthropics/skills/frontend-design frontmatter:
--- name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. license: Complete terms in LICENSE.txt ---
What the real example teaches
- •Starts with WHAT does: “Create distinctive, production-grade frontend interfaces”.
- •Continue with WHEN: “Use this skill when the user asks to build...” .
- •List concrete triggers in parentheses: websites, landing pages, dashboards, React.
- •Ends with the differentiator: “avoids generic AI aesthetics”.
✅ Module Summary
Next:
3.2 — 🎚️ Progressive disclosure & the description that triggers: the 3 loading levels and how to write the perfect trigger.