Boas práticas para skills que funcionam
Uma skill pode estar perfeitamente escrita por dentro e mesmo assim nunca ativar, ou ativar quando não deve. Estes são os princípios que separam uma skill que funciona de uma que o Claude ignora. O SkillCreator aplica-os por si, mas conhecê-los vai ajudá-lo a escrever melhores skills.
1. A descrição manda
O Claude não lê o interior de todas as suas skills em cada mensagem: lê o nome e a descrição, e é com isso que decide qual usar. Por isso a descrição deve conter as duas coisas: o que a skill faz e quando usá-la. Escreva-a no imperativo («Use esta skill quando…») e seja um pouco insistente: enumere várias situações e inclua casos em que o utilizador não a nomeie explicitamente. É a melhor defesa contra a sub-ativação (a skill existe mas nunca dispara). Há um guia dedicado sobre como escrever boas descrições.
2. Instruções no imperativo — e explique o porquê
Dê as ordens de forma direta: «Verifique…», «Redija…», «Confirme…». E quando uma instrução for importante, explique porquê. Os modelos atuais seguem melhor uma regra quando entendem o motivo do que quando recebem um «SEMPRE» ou «NUNCA» em maiúsculas e sem contexto. «Não aplique alterações sem as rever antes, porque um erro em produção afeta utilizadores reais» funciona melhor do que «NUNCA aplique sem rever».
3. Os exemplos ensinam mais do que as regras
Um bom exemplo de entrada e saída ensina ao Claude o resultado esperado melhor do que um parágrafo de instruções. Use o padrão «Pedido → Resultado» com casos realistas. Dois ou três exemplos bem escolhidos valem mais do que dez regras abstratas.
4. Defina o formato de saída
Se a sua skill deve devolver sempre um resultado com a mesma estrutura (um relatório, um modelo, secções fixas), defina-o explicitamente com um modelo. Assim o resultado é consistente em cada uso. O SkillCreator tem um bloco específico para isto.
5. Divulgação progressiva: mantenha a skill leve
O corpo da skill deve ser conciso. O material pesado —documentação extensa, tabelas de referência, scripts— vai em pastas à parte (references/, scripts/) que o Claude consulta só quando precisa. Assim o contexto mantém-se leve e a skill é rápida. É o que a Anthropic chama «divulgação progressiva».
6. Uma skill, uma capacidade
Cada skill deve fazer uma coisa bem. Se tentar meter três tarefas diferentes numa só, a descrição fica difusa e o Claude não saberá quando a ativar. Se precisar de várias capacidades, crie várias skills.
7. Um nome correto
O nome vai em minúsculas, com hífens e sem acentos (por exemplo analista-de-csv), com um máximo de 64 caracteres. O SkillCreator formata-o por si automaticamente.
A boa notícia: não tem de decorar tudo isto
O criador do SkillCreator já aplica estes princípios: pontua a sua descrição em direto, estrutura o SKILL.md no formato correto, oferece um bloco de formato de saída e valida o nome. Você traz a ideia; nós as boas práticas.