Conteúdo detalhado
🧩 A fórmula "Faz + Quando"
Toda description forte tem duas metades inseparáveis: o que a skill faz e quando ela deve ser usada. Descrições que só descrevem a capacidade ("gera relatórios") deixam o Claude sem o sinal mais importante — o gatilho. É como ter um currículo brilhante mas nunca dizer para qual vaga você está se candidatando.
✓ Tem "Faz + Quando"
- ✓"Troubleshoots frontend layout issues by testing live in the browser. Use when the user wants to fix cut-off elements or adjust layouts visually."
- ✓O Claude sabe o que recebe E em qual pedido isso se encaixa.
✗ Só o "Faz"
- ✗"A frontend troubleshooting skill."
- ✗Descreve a capacidade, mas não diz quando aplicar — o disparo fica ao acaso.
💡 Dica prática
Escreva a description e sublinhe mentalmente as duas partes. Se você não consegue apontar onde está o "quando", ela ainda não está pronta. A palavra "use when" (ou "use quando") é quase obrigatória.
🔫 Gatilhos concretos
Um gatilho concreto é uma frase ou palavra real que o usuário diria quando precisa da skill. Quanto mais próximo da linguagem do usuário, melhor o matching. Skills bem feitas listam vários gatilhos — incluindo comandos de barra e sinônimos — para cobrir as várias formas de pedir a mesma coisa.
# Gerador de itinerários
"plan a trip", "create an itinerary", "travel planner", /travel
# Correção de frontend ao vivo
"fix CSS/HTML changes", "fix cut-off elements", "adjust layouts visually"
# Padrão: linguagem do usuário + sinônimos + comando de barra📊 Três fontes de gatilho
- Verbos de ação: "create", "fix", "review", "generate" — o que o usuário quer fazer.
- Objetos concretos: "itinerary", "invoice", "workflow", "report" — o que ele quer obter.
- Comandos de barra:
/travel,/review— o atalho explícito.
💡 Dica prática
Antes de escrever os gatilhos, imagine cinco pessoas diferentes pedindo a mesma coisa, cada uma com suas palavras. Os pontos em comum entre essas cinco frases são os seus melhores gatilhos.
💡 Exemplos dentro da description
Para skills com escopo amplo ou ambíguo, embutir exemplos curtos de uso na própria description dá ao Claude âncoras semânticas que a prosa abstrata não dá. "Mostre, não só conte" vale tanto para o usuário quanto para o modelo: um caso concreto carrega mais sinal que uma definição genérica.
🎯 Abstrato vs. ancorado
"Helps with data analysis tasks."
"Analyzes a CSV and returns top trends. Use when the user says 'what's in this data?', 'find outliers', or 'summarize this spreadsheet'."
📐 Quando vale a pena
- Escopo amplo: a skill faz muitas coisas — exemplos delimitam.
- Termo genérico: palavras como "helper" ou "analysis" precisam de âncora.
- Confusão com vizinhas: exemplos diferenciam de skills parecidas.
🚫 Anti-padrões que matam o disparo
A forma mais rápida de consertar uma skill que não ativa é reconhecer o anti-padrão na sua description. Quase toda description quebrada cai em um destes quatro buracos — e cada um tem uma correção direta.
Vaga demais
"Helps with various tasks."
Correção: nomeie a tarefa específica e os gatilhos. "Various" nunca casa com nada e com tudo ao mesmo tempo.
Só "o que faz", sem "quando"
"Generates HTML pages."
Correção: adicione a metade do "quando". Sem gatilho, o Claude não tem como saber que o pedido atual se aplica.
Jargão sem contexto
"Runs the v2 pipeline orchestrator."
Correção: traduza para a linguagem do usuário. Ninguém pede "rode o orquestrador v2" — pede o resultado que ele entrega.
Sobreposta com outra skill
Duas skills com descriptions quase idênticas.
Correção: diferencie pelo escopo e adicione "não use para X" (próximo tópico). Descriptions colidentes geram disparos aleatórios.
🛑 Quando NÃO disparar
Esta é a parte que quase todo mundo esquece — e é o que separa uma description boa de uma excelente. Definir o escopo negativo ("não use para X") evita falsos positivos: a skill disparando em pedidos parecidos mas errados. Um falso positivo frustra tanto quanto um falso negativo, porque entrega o resultado errado com confiança.
🛑 O poder do limite explícito
Compare uma skill de "correção de frontend ao vivo". Ela trata layout e CSS — mas NÃO arquitetura. Deixar isso explícito impede que ela dispare em pedidos como "adicione um banco de dados".
"...Use for visual/layout bugs. Not for backend changes, new architecture, or database work — use a standard plan for those."
✓ Disparar quando
- ✓O pedido casa claramente com a capacidade central
- ✓Um gatilho concreto aparece no pedido
- ✓É exatamente o problema que a skill resolve
✗ NÃO disparar quando
- ✗O pedido só parece relacionado, mas é outra coisa
- ✗Cai num caso que a skill lista como fora de escopo
- ✗Outra skill é claramente mais adequada
💡 Dica prática
Para cada skill, escreva uma frase começando com "Não use esta skill para...". Se você não consegue completá-la, o escopo da skill provavelmente está vago demais — e ela vai disparar onde não deve.
🧪 Testando o disparo
Uma description é uma hipótese sobre quando a skill deve ativar. Só o teste confirma. O loop é simples: rode pedidos reais e variados, veja se a skill dispara quando deve e fica quieta quando não deve, e ajuste a description. É iteração, não um chute único.
Monte casos de teste
Liste pedidos que devem disparar (positivos) e pedidos parecidos que não devem (negativos). Bons negativos são pedidos vizinhos, não absurdos.
Rode em linguagem natural
Peça cada caso sem citar a skill pelo nome. Você está testando a description, não a invocação explícita.
Conte os erros e ajuste
Falso negativo (não disparou e devia)? Adicione gatilhos. Falso positivo (disparou e não devia)? Aperte o escopo negativo. Repita.
⚠️ Atenção
Não otimize a description só para os positivos. Uma description que dispara em tudo tem 100% de acerto nos positivos e é inútil — porque também dispara em todos os negativos. O equilíbrio entre os dois é o objetivo.
💡 Dica prática
Guarde seus casos de teste num arquivo. Toda vez que mexer na description, rode a bateria de novo. É a forma mais barata de não regredir — ajustar para um caso costuma quebrar outro.
🧰 Prompts copiáveis
Use estes prompts para escrever e testar descriptions afiadas com o Claude.
Minha skill faz: <descreva>. Escreva uma description no padrão
"Faz + Quando", com: (1) o que produz, (2) 3 a 5 gatilhos concretos
na linguagem do usuário, e (3) uma frase de escopo negativo
("não use para...").Avalie esta description: "<cole>". Ela cai em algum anti-padrão
(vaga, sem "quando", jargão, sobreposta)? Aponte qual e reescreva
corrigindo o problema.Para esta description: "<cole>", gere 5 pedidos de usuário que
DEVEM disparar a skill e 5 que NÃO devem (mas são parecidos).
Depois diga, para cada um, se a description atual acertaria.📤 Exemplo de saída
Uma description completa, com as quatro forças deste módulo: faz + quando, gatilhos concretos, exemplos e escopo negativo.
---
name: meeting-notes
description: Turns a raw meeting transcript into clean notes with
decisions and action items. Use when the user says "summarize
this meeting", "what did we decide?", "pull the action items",
or pastes a transcript and asks for notes. Not for live
transcription or scheduling — only for processing text that
already exists.
---✏️ Exercícios práticos
1. Diagnostique e corrija
Pegue cinco descriptions vagas (invente ou colete) e classifique cada uma pelo anti-padrão que ela comete. Depois reescreva todas no padrão "Faz + Quando".
2. Escreva o escopo negativo
Para três skills suas, escreva a frase "Não use esta skill para...". Se travar em alguma, anote — esse é um sinal de escopo mal definido.
3. Crie um SKILL.md rodável e teste o disparo ⭐
Escreva um SKILL.md completo cuja description tenha as quatro forças: faz + quando, ao menos 3 gatilhos concretos, um exemplo embutido e uma frase de escopo negativo. Em seguida, monte 5 pedidos positivos e 5 negativos e peça ao Claude para julgar — só lendo a description — em quais ele dispararia. Ajuste a description até acertar todos.
🎯 Resumo do módulo
Fim da Trilha 1:
Você já entende a anatomia, a estrutura e o gatilho. Na Trilha 2 você dissecará uma skill real do começo ao fim e construirá a sua.