🧱 Estrutura geral
Um SKILL.md tem exatamente duas partes. No topo, um bloco de frontmatter YAML entre dois delimitadores ---. Logo abaixo, o corpo em Markdown com as instruções de comportamento. Essa separação é o que todo agente compatível espera encontrar.
Esqueleto de um SKILL.md:
--- name: nome-da-skill description: O que ela faz e quando usar. --- # Título da Skill Instruções em Markdown que o agente segue quando a skill dispara.
💡 Dica
O frontmatter tem só dois campos obrigatórios: name e description. Tudo além disso (license, allowed-tools etc.) é opcional. Comece sempre por esses dois.
🏷️ Campo name
O name é o identificador único da skill. Convenção fixa: kebab-case (palavras separadas por hífen), tudo em minúsculas, e normalmente igual ao nome da pasta que contém o SKILL.md.
✗ name mal formado
- ✗Frontend_Design
- ✗minha skill
- ✗ReactBestPractices
- ✗skill (genérico demais)
✓ name correto
- ✓frontend-design
- ✓react-best-practices
- ✓skill-creator
- ✓supabase-postgres-best-practices
Por que kebab-case importa
O name é usado em comandos, em logs e como chave única no agente. Espaços e maiúsculas quebram a referência, e nomes genéricos como skill colidem com outras instalações. As skills mais instaladas do skills.sh — find-skills (1,8M), frontend-design (488k) — seguem todas o padrão.
🎣 Campo description — o gatilho
A description é o campo mais importante do arquivo. É a frase que o agente lê para decidir se ativa a skill. Uma boa description diz duas coisas: O QUE a skill faz e QUANDO usá-la — de preferência com exemplos concretos de situações.
✗ Description vaga
"Ajuda com frontend."
Não diz quando disparar. O agente quase nunca vai ativá-la.
✓ Description com gatilho
"Cria interfaces frontend. Use quando o usuário pedir para construir componentes web, páginas, landing pages..."
Diz o que faz E lista situações de uso.
Padrão recomendado:
description: <O QUE faz>. Use this skill when <QUANDO usar> (examples include <gatilhos concretos>).
💡 Dica
A description fica sempre carregada no contexto (Nível 1 do progressive disclosure — veja o módulo 3.2). Por isso vale ser específico e até um pouco "pushy": Claude tende a subdisparar skills.
📝 O corpo em Markdown
Abaixo do frontmatter vem o corpo: as instruções de verdade. Escreva em modo imperativo ("Crie", "Use", "Prefira"), explique o PORQUÊ em vez de gritar MUSTs em maiúscula, e mostre padrões de output e exemplos de como o resultado deve parecer.
✗ Corpo fraco
- ✗Lista de MUSTs em CAIXA ALTA sem contexto
- ✗Regras sem explicar o porquê
- ✗Nenhum exemplo de output esperado
- ✗Parágrafos longos e genéricos
✓ Corpo eficaz
- ✓Instruções imperativas e diretas
- ✓Explica o motivo de cada escolha
- ✓Mostra exemplos de bom e mau output
- ✓Seções curtas com headings claros
Trecho real do corpo do frontend-design:
## 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...
Imperativo + porquê
Repare no exemplo acima: cada diretriz é um comando ("Focus on", "Choose", "Commit to") seguido do raciocínio. Isso é muito mais eficaz do que "VOCÊ DEVE SEMPRE..." — o agente absorve melhor quando entende a intenção.
📁 Estrutura de pastas
Uma skill profissional não é só o SKILL.md. Ao redor dele, três pastas convencionais organizam os recursos — e cada uma tem um propósito claro.
scripts/ — código determinístico
Scripts que executam tarefas repetíveis sem depender do julgamento do agente. Rodam sem carregar o código no contexto — o agente só chama e recebe o resultado.
references/ — docs sob demanda
Documentação extensa que o agente lê só quando precisa. Mantém o SKILL.md curto enquanto oferece profundidade quando necessário.
assets/ — templates
Arquivos de apoio: templates, boilerplates, imagens, configs que a skill usa ou copia para o projeto do usuário.
Layout típico de uma skill:
minha-skill/
├── SKILL.md
├── scripts/
│ └── gerar.py
├── references/
│ └── guia-completo.md
└── assets/
└── template.html
💡 Dica
Não crie pastas vazias por antecipação. Comece só com o SKILL.md e adicione scripts/ ou references/ quando o conteúdo realmente justificar — cada pasta é o Nível 3 do progressive disclosure.
🔬 Exemplo mínimo vs real
Para fechar, compare os extremos. Um SKILL.md mínimo cabe em 5 linhas. Já uma skill de produção — como a frontend-design da Anthropic (488.299 instalações) — carrega no frontmatter uma description rica em gatilhos.
Mínimo:
--- name: git-commit-style description: Formata mensagens de commit no padrão Conventional Commits. --- Sempre escreva commits no formato tipo(escopo): descrição.
Real — frontmatter do anthropics/skills/frontend-design:
--- 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 ---
O que o exemplo real ensina
- •Abre com O QUE faz: "Create distinctive, production-grade frontend interfaces".
- •Segue com QUANDO: "Use this skill when the user asks to build...".
- •Lista gatilhos concretos entre parênteses: websites, landing pages, dashboards, React.
- •Fecha com o diferencial: "avoids generic AI aesthetics".
✅ Resumo do Módulo
Próximo:
3.2 — 🎚️ Progressive disclosure & a description que dispara: os 3 níveis de carregamento e como escrever o gatilho perfeito.