🎯 Capturar o intent
O skill-creator começa entendendo a intenção antes de escrever qualquer linha. Se a conversa já contém o workflow que a pessoa quer capturar (ela diz "transforma isso numa skill"), extraia primeiro das mensagens anteriores — as ferramentas usadas, a sequência de passos, as correções que ela fez, os formatos de entrada e saída que apareceram. Só depois peça para preencher as lacunas, e confirme antes de prosseguir.
O que esta skill habilita o Claude a fazer?
A capacidade central. Não "ajudar com planilhas", mas "calcular margem de lucro e adicionar a coluna num xlsx".
Quando ela deve disparar?
Quais frases e contextos do usuário acionam a skill. Isso vira o coração da description.
Qual o formato de saída esperado?
Um arquivo? Um relatório com seções fixas? Código? Definir isso cedo evita retrabalho.
Vale montar test cases?
Skills com saída objetivamente verificável (transformar arquivo, extrair dados, gerar código) se beneficiam de testes. Saída subjetiva (estilo, arte) geralmente não precisa. Sugira o default, deixe o usuário decidir.
💡 Cuidado com o jargão
O skill-creator é usado por gente de níveis muito diferentes de familiaridade técnica. Termos como "JSON" e "assertion" só devem aparecer sem explicação se houver pistas claras de que a pessoa conhece. Na dúvida, defina o termo em uma frase curta.
🔎 Interview & research
Com o intent capturado, aprofunde. Pergunte proativamente sobre edge cases, formatos de entrada e saída, arquivos de exemplo, critérios de sucesso e dependências. Espere para escrever test prompts só depois de fechar essa parte — entrevista mal feita gera skill que cobre o caso feliz e quebra no resto.
✗ Entrevista rasa
- ✗Assume que só há um formato de entrada
- ✗Ignora o que acontece com input vazio ou malformado
- ✗Nunca pede arquivos de exemplo reais
- ✗Não define o que conta como "deu certo"
- ✗Joga o trabalho de pesquisa nas costas do usuário
✓ Entrevista que prepara o terreno
- ✓Mapeia todos os formatos in/out plausíveis
- ✓Explora edge cases antes de codar
- ✓Coleta exemplos concretos do domínio
- ✓Acorda critérios de sucesso explícitos
- ✓Pesquisa em paralelo via subagents/MCPs
Chegue com contexto pronto
Cheque os MCPs disponíveis. Se algum for útil para a pesquisa — buscar docs, achar skills parecidas, levantar boas práticas — pesquise em paralelo via subagents (quando houver) ou inline. A ideia é reduzir o atrito para o usuário: vir com o dever de casa feito em vez de perguntar tudo do zero.
📝 Escrever o SKILL.md
A partir da entrevista, preencha os componentes do arquivo. O SKILL.md é frontmatter YAML (com name e description obrigatórios) seguido do corpo em Markdown.
Os componentes
- •name: o identificador da skill
- •description: o quê faz E quando usar. É o mecanismo primário de disparo — todo "quando usar" mora aqui, não no corpo.
- •compatibility: ferramentas/dependências exigidas (opcional, raramente necessário)
- •o resto da skill :) — o corpo com as instruções
Description deve ser um pouco "pushy"
Hoje o Claude tende a subdisparar skills — não usá-las quando seriam úteis. Para combater isso, a description precisa listar contextos concretos de uso, mesmo que o usuário não peça explicitamente.
Fraca vs pushy:
# Fraca description: How to build a simple fast dashboard to display internal Anthropic data. # Pushy description: How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'
🎯 Lembrete da anatomia
Progressive disclosure em 3 níveis: (1) metadata name+description sempre no contexto (~100 palavras); (2) corpo do SKILL.md quando dispara, ideal <500 linhas; (3) recursos bundlados carregados sob demanda. A description é o gatilho.
✍️ Writing style
Como você escreve o corpo da skill importa tanto quanto o que escreve. Prefira o imperativo, use theory of mind e explique o porquê de cada instrução em vez de empilhar MUSTs em maiúscula. Mantenha a skill geral, não colada nos exemplos específicos.
✗ Estilo heavy-handed
- ✗"ALWAYS do X. NEVER do Y." em caixa-alta
- ✗Regras rígidas sem nenhuma razão
- ✗Instruções coladas a um exemplo único
- ✗Trata o modelo como executor cego
✓ Estilo que respeita o modelo
- ✓Imperativo claro: "Comece entendendo..."
- ✓Explica por que cada passo importa
- ✓Generaliza para muitos casos
- ✓Usa theory of mind: aposta na inteligência
Por que evitar MUSTs gritando
Os LLMs de hoje são espertos: têm boa theory of mind e, com um bom harness, vão além da instrução rote. Se você se pega escrevendo ALWAYS ou NEVER em caixa-alta, ou estruturas super rígidas, é um yellow flag — reformule explicando a razão para que o modelo entenda por que aquilo importa. É mais humano, mais poderoso e mais efetivo.
👀 Rascunhar e reler com olhos novos
Não trave buscando o draft perfeito. Escreva um primeiro rascunho, depois releia com olhos novos e melhore. O ciclo draft → revisar → melhorar acontece dentro da própria escrita, antes mesmo de qualquer teste.
Escreva o draft
Coloque tudo no papel sem editar. Velocidade primeiro, polimento depois.
Releia distanciado
Olhe como se fosse outra pessoa lendo. Onde está ambíguo? O que manda o modelo gastar tempo à toa?
Melhore
Corte redundância, reformule o que estava rígido, explique o porquê do que ficou vago.
💡 Dica
O skill-creator repete esse conselho em vários pontos: "escreva um draft e depois olhe com olhos novos para melhorar". Vale para o SKILL.md inteiro e para cada revisão futura no loop de iteração.
📦 Quando bundlar
Nem tudo vive dentro do SKILL.md. Recursos bundlados (scripts/, references/, assets/) carregam sob demanda. A regra prática: se 3 execuções repetem o mesmo script, extraia para scripts/; docs grandes vão para references/.
Anatomia de uma skill:
skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ # código p/ tarefas repetitivas ├── references/ # docs carregadas sob demanda └── assets/ # templates, ícones, fontes
Sinais de que é hora de bundlar
- •3 invocações independentes escreveram o mesmo
create_docx.py→ virescripts/e mande a skill usá-lo - •O corpo do SKILL.md está perto de 500 linhas → adicione uma camada de hierarquia com ponteiros claros
- •Doc de referência grande (>300 linhas) → inclua um índice/TOC
- •Skill suporta múltiplos domínios → organize por variante em
references/(aws.md, gcp.md, azure.md)
🎯 Por que bundlar script repetido
Escrever uma vez, colocar em scripts/ e apontar a skill para ele poupa toda invocação futura de reinventar a roda. Scripts executam sem precisar carregar todo o conteúdo no contexto — é mais rápido, mais confiável e reaproveitável entre iterações.
✅ Resumo do Módulo
Próximo:
4.2 — 🔁 Testar, avaliar e iterar — escreva test prompts realistas, rode com-skill vs baseline, avalie e itere até a skill funcionar para muito além dos exemplos.