Etapa 1: defina o que esta Skill deve ensinar
Uma boa Skill faz exatamente uma coisa, e a «forma correta» de fazer essa coisa pode ser resumida.
- ✅ Bons exemplos: «escrever um artigo para a conta oficial seguindo as nossas diretrizes de marca», «revisar código front-end em busca de problemas de acessibilidade»
- ❌ Mau exemplo: «me ajuda com tudo» (amplo demais: a IA não saberá quando usá-la)
Etapa 2: escreva o SKILL.md
A estrutura padrão é assim (fique à vontade para copiá-la):
---
name: weekly-report-writer
description: Converte notas de trabalho dispersas em um relatório semanal bem estruturado. Use quando o usuário disser «escreve meu relatório semanal» ou colar um amontoado de registros de trabalho.
---
# Geração de relatório semanal
1. Leia as notas brutas do usuário e organize-as primeiro por «resultados / problemas / planos da próxima semana»
2. Ordene os resultados por importância; formate cada item como: resultado em uma frase + dado de apoio
3. Marque os dados que faltarem com [TBD]; nunca invente dados
4. Termine com 2 títulos sugeridos para o relatório semanal
## Exemplo
Entrada do usuário: «Na segunda tive uma reunião, na terça corrigi um bug, na quarta lancei um recurso.»
Saída:
### Resultados desta semana
1. Conduzi o lançamento do recurso XX (impacto de dados [TBD])
........
name
Em minúsculas com kebab-case, identificador único
description
A mais crítica: diga claramente o que ela faz + quando usá-la; a IA se baseia nisso para decidir ativá-la
corpo
Etapas concretas + exemplos + regras — quanto mais específico, melhor
Etapa 3: pastas opcionais de melhoria
scripts/— scripts executáveis (Python, Bash etc.) que a IA chama quando precisareferences/— material de referência/docs, carregado quando necessárioassets/— recursos estáticos como modelos e exemplos
Etapa 4: teste e aperfeiçoe
- Teste 3 entradas diferentes e verifique se a saída corresponde ao esperado
- Acrescente ao corpo os «pontos em que a IA entendeu errado» — as Skills se afinam de forma iterativa
- Faça com que a description cubra todos os cenários de ativação esperados (os usuários formulam as coisas de mil maneiras)
- Estude como são escritas as Skills mais bem avaliadas da comunidade: veja a lista selecionada (o repositório oficial anthropics/skills é um excelente modelo)
Erros comuns
- description muito vaga → a IA nunca sabe quando ativá-la, então a Skill é desperdiçada
- Etapas vagas (como «analise com cuidado») → substitua-as por ações verificáveis e concretas
- Empilhar um monte de trechos fora do tema → viola o carregamento progressivo e deixa o agente mais lento
- Esquecer de definir «quando NÃO usá-la» → ela acaba se aplicando à força a cenários inadequados