Como escrever uma descrição que ative a sua skill
Se uma skill não se ativa quando devia, o problema está quase sempre na descrição. É a linha que o Claude lê para decidir se a sua skill encaixa no que é pedido. Domine-a e as suas skills funcionarão à primeira.
Porque é que a descrição é (quase) tudo
O Claude não lê o conteúdo completo de todas as suas skills em cada mensagem — seria demasiado. O que faz é ler o nome e a descrição de cada uma e, com isso, decidir qual usar. Por isso a descrição não é um resumo bonito: é o gatilho. Se for vaga, a sua skill fica adormecida mesmo que seja perfeita por dentro.
A fórmula de uma boa descrição
Uma descrição que funciona costuma ter três ingredientes:
- O momento de ativação: comece por «Use esta skill quando…». Deixe claro em que situações deve entrar.
- A tarefa concreta: inclua o verbo de ação (redigir, analisar, rever, resumir, traduzir…).
- O detalhe que a distingue: o tema, o idioma, o formato ou o tipo de documento. Isto evita que ative quando não deve.
Exemplos: de fraca a excelente
❌ Fraca
description: Ajuda com e-mails.
Demasiado curta e ambígua. Ajuda a lê-los, a escrevê-los, a traduzi-los? O Claude não saberá quando a usar.
⚠️ A melhorar
description: Redige e-mails profissionais.
Já menciona a tarefa, mas falta-lhe o momento de ativação e o contexto.
✅ Excelente
description: Use esta skill quando o utilizador pedir para redigir, rever ou melhorar e-mails profissionais em português: pedidos, reclamações, seguimentos ou respostas formais.
Tem o momento («quando o utilizador pedir»), a tarefa («redigir, rever, melhorar»), o contexto («e-mails profissionais em português») e exemplos de casos. Ativa exatamente quando deve.
Erros habituais a evitar
- Ser demasiado genérico: «ajuda com textos» sobrepõe-se a quase tudo.
- Ser demasiado estreito: se só menciona «faturas», não ativa com «recibos» ou «orçamentos».
- Descrever o como em vez do quando: a descrição é para o gatilho; o «como» vai nas instruções.
- Repetir o nome: se a skill se chama
tradutor, «traduz coisas» não chega; acrescente idiomas e contexto.
Verifique em tempo real
O criador do SkillCreator inclui um medidor de qualidade exclusivo: enquanto escreve a sua descrição, pontua-a de 0 a 100 e diz-lhe exatamente o que falta (o momento, a tarefa ou o detalhe). É a forma mais rápida de acertar sem ser especialista. Veja também o nosso guia de boas práticas.