📋 Estrutura Geral do SKILL.md
Todo arquivo SKILL.md tem duas partes obrigatórias: o frontmatter YAML (entre delimitadores ---) e o corpo em Markdown (as instruções propriamente ditas). Juntas, essas partes definem o que a skill é e como o agente deve se comportar.
Estrutura anotada de um SKILL.md completo:
--- # Início do frontmatter name: minha-skill # OBRIGATÓRIO: identificador description: O que faz e # OBRIGATÓRIO: gatilho de ativação quando usar metadata: # OPCIONAL internal: true # ocultar da descoberta --- # Fim do frontmatter # Minha Skill # Título (Markdown) Instruções para o agente. # Corpo livre em Markdown ## When to Use - Cenário 1 - Cenário 2 ## Steps 1. Faça isso 2. Depois isso
Por que essa estrutura?
O frontmatter permite que o CLI processe os metadados sem depender de parsing de Markdown. O corpo em Markdown é lido pelo agente diretamente. Essa separação garante compatibilidade: o CLI usa o YAML, o agente usa o Markdown.
🏷️ Campo name: Nomenclatura e Regras
O campo name é o identificador único da skill. É usado pelo CLI nos comandos remove, update e list. Seguir as regras de nomenclatura é essencial para que o CLI funcione corretamente.
✓ Names corretos
- ✓react-best-practices
- ✓git-commit-style
- ✓find-skills
- ✓nextjs-routing
- ✓deploy-checklist
✗ Names incorretos
- ✗React Best Practices(maiúsculas)
- ✗git_commit_style(underscore)
- ✗minha skill(espaço)
- ✗skill@v2(caractere especial)
- ✗MinhaSkill(camelCase)
💡 Dica de Nomenclatura
Use o padrão [tecnologia]-[o-que-faz]. Exemplos: react-hooks, typescript-strict, docker-security. Isso facilita encontrar a skill com npx skills list e comunicar seu propósito a outros membros do time.
📝 Campo description: O Gatilho de Ativação
A description é o campo mais crítico do SKILL.md. É ela que o agente lê para decidir se deve ou não ativar a skill no contexto atual. Uma description bem escrita resulta em ativação precisa; uma vaga resulta em skill ignorada ou ativada incorretamente.
Anatomia de uma description eficaz
✗ Description vaga
"Boas práticas de React"
O agente não sabe quando ativar isso — é sempre? Só para componentes? Só para novos arquivos?
✓ Description precisa
"Aplica boas práticas de React ao criar ou modificar componentes, garantindo uso de hooks, TypeScript e acessibilidade"
Claro: ação (aplica), quando (criar/modificar componentes), o que (hooks, TS, acessibilidade).
🎯 Teste da description
Após escrever a description, pergunte: "Se eu for um agente e ler apenas essa linha, saberei exatamente quando devo usar essa skill?" Se a resposta for não, reescreva.
📖 Corpo Markdown: When to Use e Steps
O corpo do SKILL.md é Markdown livre, mas duas seções padronizadas maximizam a eficácia: When to Use (cenários de ativação) e Steps (instruções sequenciais para o agente seguir).
Exemplo completo de corpo bem estruturado:
# React Best Practices Ao criar ou modificar componentes React neste projeto, siga rigorosamente estas diretrizes de qualidade. ## When to Use - Criando novos componentes React (*.tsx, *.jsx) - Refatorando componentes existentes - Revisando código de colegas via PR - Quando o usuário pedir ajuda com React ## Steps 1. Use componentes funcionais (nunca classes) 2. Adicione tipos TypeScript explícitos a todas as props 3. Prefira hooks nativos antes de libs externas 4. Verifique acessibilidade: aria-labels, focus management 5. Escreva testes com Testing Library 6. Documente props complexas com JSDoc
Seções opcionais úteis
- •## Examples — Exemplos de código de entrada e saída
- •## Avoid — Padrões a evitar (antipatterns)
- •## References — Links para documentação relevante
- •## Context — Contexto adicional sobre o projeto ou time
🔒 metadata.internal: Skills Ocultas
O campo metadata.internal: true marca uma skill como interna, ocultando-a da descoberta pública pelo npx skills find e do diretório skills.sh. Ideal para skills com informações sensíveis de processos internos.
--- name: deploy-processo-interno description: Guia o processo de deploy seguindo nossa política de segurança e aprovações obrigatórias metadata: internal: true # oculta do skills.sh --- # Deploy — Processo Interno [Instruções confidenciais do processo de deploy...]
Quando usar internal: true
- •Políticas de segurança da empresa
- •Processos com dados sensíveis
- •Skills em desenvolvimento/teste
- •Convenções proprietárias do time
Como instalar skills internas
- •Defina
INSTALL_INTERNAL_SKILLS=1 - •Execute
npx skills add owner/repo - •Skills internas serão incluídas
- •Sem a var, são silenciosamente ignoradas
🔍 A Skill find-skills como Modelo
A skill find-skills é a única skill inclusa no repositório vercel-labs/agent-skills e serve como modelo de referência. Ela demonstra como escrever uma skill com gatilhos naturais (linguagem do usuário), instruções claras e integração com o CLI.
Por que a find-skills é um modelo
npx skills find [query] e apresentar os resultados de forma útil🎓 Exercício prático
1. Execute: npx skills init minha-primeira-skill
2. Abra o arquivo gerado e estude a estrutura do template
3. Compare com a find-skills em github.com/vercel-labs/agent-skills
4. Adapte para um caso de uso do seu projeto
✅ Resumo do Módulo
Próximo Módulo:
1.3 — 🤖 Agentes Suportados — Os 50+ agentes, caminhos de instalação e diferenças de compatibilidade