🗺️ Por que estudar anatomias reais
A melhor forma de aprender a escrever um SKILL.md é dissecar os que já venceram. As skills mais instaladas do ecossistema (frontend-design com 488.299 installs, skill-creator com 246k, azure-ai com 358.744) não são acidentes: cada uma resolve o problema de uma forma diferente, e juntas formam um catálogo de padrões prontos para imitar.
A regra do roubo honesto
Não copie o conteúdo — copie a forma. Cada anatomia abaixo resolve um trade-off diferente (concisão vs. cobertura, simplicidade vs. roteamento). Identifique qual delas se parece com a sua skill e use o esqueleto correspondente.
🎨 frontend-design — description curta e cirúrgica
A skill mais instalada da Anthropic (488.299 installs) é também uma das mais enxutas no frontmatter. A description faz três coisas em uma frase só: diz o que faz, lista quando usar com exemplos concretos, e fecha com o diferencial ("avoids generic AI aesthetics").
frontmatter real de 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 copiar
- ✓Verbo de ação no começo ("Create...")
- ✓Lista de exemplos entre parênteses como gatilhos
- ✓Frase final que diferencia o resultado
- ✓Zero pastas: corpo único resolve tudo
✗ Quando NÃO imitar
- ✗Se sua skill cobre vários domínios distintos
- ✗Se ela precisa rodar scripts determinísticos
- ✗Se o corpo passaria de 500 linhas sem pastas
💡 Dica
Use o molde frontend-design quando sua skill é "uma só competência" — sem variantes, sem scripts. É o arquétipo mais comum e o mais fácil de manter.
🧰 skill-creator — a anatomia multi-arquivo
A skill-creator da Anthropic (246k installs, ~33KB) é o exemplo canônico de skill grande organizada por pastas. O corpo do SKILL.md fica no essencial; o resto vive em scripts/, references/ e assets/ — exatamente os três diretórios canônicos.
A anatomia que o próprio skill-creator documenta:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - código determinístico
├── references/ - docs sob demanda
└── assets/ - templates, ícones, fontes
Veja como o corpo aponta para os recursos em vez de colar o conteúdo — o padrão de ponteiro que mantém o SKILL.md curto:
ponteiros reais no corpo do skill-creator:
See `references/schemas.md` for the full schema. python -m scripts.package_skill <path/to/skill> Read the template from `assets/eval_review.html`
O que copiar
Os três diretórios com os papéis exatos, e a disciplina de citar cada arquivo no corpo com uma frase de "quando ler". É o esqueleto a imitar quando sua skill tem código reutilizável, docs longos e templates de saída.
🗂️ supabase — roteamento por domínio na description
A skill supabase (99k installs) tem uma das descriptions mais agressivas do ecossistema: ela começa com "Use when doing ANY task involving Supabase" e despeja uma lista enorme de Triggers: — produtos, bibliotecas, problemas de auth. É roteamento puro: a description sozinha já sabe encaminhar o agente.
frontmatter real de supabase (trecho):
--- name: supabase description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit; auth issues (login, sessions, JWT, RLS); Supabase CLI or MCP server; migrations, security audits, Postgres extensions." metadata: author: supabase version: "0.1.2" ---
✓ O que copiar
- ✓O rótulo
Triggers:seguido de lista por categoria - ✓O "ANY" assertivo para forçar o disparo
- ✓Bloco
metadata:com author e version
✓ E no corpo
- ✓"Core Principles" numerados no topo
- ✓Checklists de segurança com armadilhas reais
- ✓Links para docs oficiais em vez de colar tudo
💡 Dica
Quando sua skill é o "porteiro" de uma plataforma inteira, copie o padrão de Triggers: categorizados — é o que garante que o agente ative em qualquer ponta do domínio.
☁️ microsoft-foundry & azure-ai — skills operacionais grandes
As skills da Microsoft (foundry e azure-ai, ~358–360k installs, 19KB+) mostram como escalar uma skill operacional e enorme sem perder controle: a description usa USE FOR e DO NOT USE FOR para delimitar o escopo, e o corpo é uma tabela de sub-skills que roteia para arquivos por workflow.
description de microsoft-foundry (trecho com limites de escopo):
description: "Deploy, evaluate, fine-tune, and manage Foundry agents end-to-end... USE FOR: deploy agent, hosted agent, create agent, evaluate agent, optimize prompt, deploy model, RBAC, quota, troubleshoot agent... DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy)."
corpo: tabela de sub-skills que roteia por workflow:
| Sub-Skill | When to Use | Reference | |-----------|------------------|------------------| | deploy | Build, push, ACR | deploy/deploy.md | | invoke | Send messages | invoke/invoke.md | | observe | Run evals | observe.md | | quota | Capacity, quota | quota/quota.md |
O que copiar
- •USE FOR / DO NOT USE FOR — desambigua skills vizinhas e evita disparo errado.
- •Tabela de sub-skills — o SKILL.md vira um roteador, cada workflow num arquivo próprio.
- •Pre-Execution Requirements — pré-checagens explícitas antes de qualquer ação.
📋 Tabela comparativa — qual molde usar
Junte tudo: cada anatomia é uma resposta a uma pergunta diferente sobre a sua skill. Use a tabela como decisor rápido.
| Referência | Padrão-chave | Copie quando… |
|---|---|---|
| frontend-design | description cirúrgica, sem pastas | skill é uma competência só |
| skill-creator | scripts/ references/ assets/ | tem código, docs e templates |
| supabase | Triggers: categorizados | é porteiro de uma plataforma |
| azure-ai / foundry | USE FOR / DO NOT + sub-skills | é grande e operacional |
💡 Dica final
A maioria das skills começa no molde frontend-design e migra para o molde skill-creator quando o corpo passa de 500 linhas. Os moldes supabase e foundry são para quando o domínio explode em variantes. No próximo módulo você vai montar um SKILL.md do zero seguindo esses padrões.
✅ Resumo do Módulo
Próximo:
Módulo 3.4 — 🛠️ Como Criar: montar um SKILL.md do zero, frontmatter ao corpo, com template completo pronto para copiar.