🎯 A description como único gatilho
O campo description no frontmatter do SKILL.md é o único sinal que o agente usa para decidir se deve ativar uma skill. É o seu "anúncio" para o agente — escreva como se precisasse convencer alguém em 5 segundos.
O que torna uma description eficaz
⚡ Escrevendo frases-gatilho fortes
Frases-gatilho são as cláusulas TRIGGER when na description. Elas listam explicitamente os contextos de ativação, cobrindo múltiplas formas como o usuário pode expressar o mesmo pedido.
description: |-
Build, debug, and optimize Claude API / Anthropic SDK apps.
Apps built with this skill should include prompt caching.
Also handles migrating existing Claude API code between
Claude model versions.
TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`;
user asks for the Claude API, Anthropic SDK, or Managed
Agents; user adds/modifies/tunes a Claude feature (caching,
thinking, tool use, batch) or model (Opus/Sonnet/Haiku).
SKIP: file imports `openai`/other-provider SDK, filename
like `*-openai.py`, provider-neutral code, general
programming/ML.✓ Triggers fortes
- ✓Prefixo explícito "TRIGGER when:" ou "Use quando:"
- ✓Cobre múltiplas formulações do mesmo pedido
- ✓Inclui sinônimos e variações do domínio
- ✓Menciona artefatos concretos (imports, arquivos)
- ✓Testável: "se disser X, deve disparar?"
✗ Triggers fracos
- ✗Sem prefixo — não há separação clara do resumo
- ✗Cobre apenas 1 formulação ("crie um curso")
- ✗Palavras-chave genéricas ("código", "web")
- ✗Técnico demais para o usuário ("processa tokens")
- ✗Sem SKIP — dispara em contextos errados
💡 Técnica: 5 perguntas de teste
Antes de publicar a skill, teste a description com 5 perguntas reais que o usuário faria. Para cada uma, verifique:
- 1. A skill deveria disparar? (sim/não)
- 2. Apenas lendo a description, fica claro que sim/não?
- 3. Alguma outra skill concorreria por este trigger?
- 4. O SKIP elimina os falsos positivos?
- 5. Alguém sem contexto entenderia a description?
🚫 Cláusulas SKIP: evitar disparo errado
SKIP define os anti-casos: situações onde a skill NÃO deve disparar, mesmo que haja sobreposição temática com o trigger. É a fronteira que separa a skill de suas vizinhas.
📊 Por que SKIP importa
Imagine que você tem claude-api e uma skill genérica de "código Python". Sem SKIP, qualquer script Python que mencione uma API poderia acionar a skill errada. O SKIP cria fronteiras nítidas:
- • import anthropic
- • Claude API / SDK
- • Opus, Sonnet, Haiku
- • import openai
- • código provider-neutral
- • ML genérico sem SDK
Como refinar o SKIP na prática
Identify false positives
Use a skill por 1 semana. Anote toda vez que ela disparar quando não deveria — são os seus falsos positivos.
Encontre o padrão
O que os falsos positivos têm em comum? É uma biblioteca? Um tipo de arquivo? Um contexto específico?
Adicione ao SKIP
Adicione o padrão à cláusula SKIP da description. Re-teste com os falsos positivos originais.
✓ SKIP bem escrito
- ✓Prefixo "SKIP:" explícito e em maiúsculas
- ✓Lista os casos de não-uso com exemplos concretos
- ✓Complementa o TRIGGER sem contradizê-lo
- ✓Refinado com falsos positivos reais
✗ Armadilhas do SKIP
- ✗SKIP tão amplo que bloqueia casos válidos
- ✗Contradiz o TRIGGER ("Use quando X... SKIP: X")
- ✗Ausência de SKIP em skill de escopo amplo
- ✗SKIP genérico demais ("SKIP: código geral")
🔤 Nome em kebab-case
O nome da pasta e do campo name no frontmatter seguem uma convenção única: kebab-case.
💡 Por que kebab-case funciona
funciona como slug sem encoding
sem necessidade de aspas no shell
instantaneamente escaneável
✅ Exemplos reais de description eficaz
Análise de descriptions de skills reais em produção. O que as torna eficazes e por quê.
description: |-
Template e padrões de design para criar páginas HTML de cursos
no formato INEMA.CLUB.
Use esta skill SEMPRE que o usuário pedir para criar, editar ou
revisar páginas HTML de curso — incluindo index de trilhas,
páginas de módulos, componentes como navegação, cards, tópicos
expansíveis, modais e slides.
Acione também quando o usuário mencionar trilhas, módulos,
tópicos, INEMA.CLUB, ou quando pedir para seguir o
"formato de curso" ou "template de curso".
Nao deixe de usar esta skill se o usuário mencionar qualquer
coisa relacionada a páginas HTML de cursos ou ao projeto skillx.Por que essa description funciona
❌ Anti-patterns de description
Descriptions ruins são invisíveis (skill nunca dispara), promíscuas (dispara para tudo) ou confusas (dispara quando não deveria). Os 4 anti-patterns mais comuns:
✗ Anti-pattern 1: Vago demais
Problema: "código" é tudo. Toda skill de dev vai competir. Nenhuma vai ganhar de forma previsível.
✗ Anti-pattern 2: Circular
Problema: todas as skills "usam IA". A description precisa diferenciar, não generalizar.
✗ Anti-pattern 3: Técnico demais
Problema: o usuário não pensa em "tokens" e "context window" — pensa em "preciso de uma resposta".
✗ Anti-pattern 4: Sem âncoras
Problema: qual API? REST? GraphQL? Anthropic? OpenAI? Sem âncora específica, o match vai errar.
💡 O teste de 1 frase
Mostre a description para alguém que nunca viu a skill. Faça uma pergunta: "Em que situação você usaria isso?" Se a resposta for vaga ou errada, a description falhou. O teste leva 30 segundos e economiza horas de debug.
🎯 Resumo do Módulo
Próximo Módulo:
3.3 — Scripts e referências auxiliares: como estruturar scripts/, references/, .env.example e aplicar progressive disclosure