✍️ Escrever uma description que dispara certo
A description é o gatilho — o agente lê os ~100 palavras de metadata para decidir se dispara. Uma boa tem três partes: o que faz, quando usar e ser um pouco "pushy", porque o agente tende a subdisparar.
O QUE faz (resultado, não atividade)
Abra com o resultado. frontend-design: "Create production-grade frontend interfaces". Não "ajuda com" — entrega algo.
QUANDO usar (gatilhos concretos)
"Use this skill when..." + exemplos de tarefa. supabase vai além: "Triggers:..." lista os sinais textuais que devem acionar.
Seja "pushy" (contra o subdisparo)
"Use when doing ANY task involving X." Claude erra por não acionar; uma description firme corrige isso — sem virar um aspirador que dispara em tudo.
anatomia de uma description forte (padrão supabase):
[O QUE] Use when doing ANY task involving Supabase.
[QUANDO] Triggers: criar tabela, RLS policy, query Postgres,
migrations, auth, edge functions, storage.
[PUSHY] "ANY task" + lista de triggers = dispara sempre que
o assunto aparece, raramente fora dele.
💡 Regra dos 100 palavras
A description fica sempre no contexto (nível 1 do progressive disclosure). Cada palavra é cara — corte adjetivo de marketing, mantenha gatilho. "O quê + quando" densos batem qualquer texto bonito.
🎯 Escopo atômico: uma responsabilidade
Uma skill deve fazer uma coisa. É o que faz vercel-react-best-practices (443k) e test-driven-development (107k) dispararem com precisão. Se a sua tenta abraçar tudo, ela absorve mal no contexto, dispara errado e não compõe.
✗ Escopo inchado
- ✗"web-helper": React + CSS + deploy + testes + SEO
- ✗Dispara em qualquer tarefa web — ruído constante
- ✗Corpo de 1.500 linhas que estoura o contexto
- ✗Impossível testar: o que exatamente ela garante?
✓ Escopo atômico
- ✓Quebre em 4: react-patterns, css-layout, deploy, testes
- ✓Cada uma dispara só no seu gatilho
- ✓Corpo <500 linhas (nível 2 do disclosure)
- ✓Testável e composível, como a suíte azure-skills
Teste da frase única
Descreva a skill em uma frase sem usar "e" nem "também". Conseguiu? Atômica. A frase tem três cláusulas ligadas por "e"? São três skills. A Microsoft não fez "azure-everything" — fez foundry, ai, deploy, diagnostics e prepare.
✅ O checklist de polimento
Antes de publicar, passe a skill por este roteiro. Cada item separa uma skill que parece de qualidade de uma que é. Inspirado no fluxo canônico do skill-creator (anthropics).
| # | Checagem | Por quê |
|---|---|---|
| 1 | description tem O QUE + QUANDO + gatilhos | é o roteamento |
| 2 | cabe em uma frase sem "e" | escopo atômico |
| 3 | corpo <500 linhas, imperativo | absorve no contexto |
| 4 | explica o PORQUÊ, não só MUSTs | o agente generaliza melhor |
| 5 | rodou 2–3 test prompts realistas | prova que dispara e ajuda |
| 6 | scripts repetidos extraídos p/ bundled | nível 3 sob demanda |
| 7 | nome autoexplicativo | descoberta clara |
o loop, em comandos:
npx skills add anthropics/skill-creator # use a meta-skill # escreva draft → rode test prompts (com-skill vs baseline) # avalie → generalize do feedback → enxugue → extraia scripts # otimize a description (should-trigger / should-not) → repita
💡 Polimento ≠ mais texto
Polir uma skill é quase sempre remover: cortar instrução redundante, mover detalhe para bundled resources, apertar a description. Skill enxuta dispara melhor e custa menos contexto.
🔁 Antes / Depois: uma skill fraca → forte
O caso clássico. Mesma intenção ("ajudar com SQL"), duas execuções. À esquerda, o que ninguém instala. À direita, o padrão supabase-postgres-best-practices (203k).
✗ Antes — fraca
name: sql-helper description: Helps with SQL and databases and queries and more.
- ✗Sem o QUANDO — o agente não sabe disparar
- ✗"and more" = escopo infinito
- ✗Nome genérico, fonte desconhecida
✓ Depois — forte
name: postgres-best-practices description: Use when writing or reviewing Postgres SQL. Triggers: schema design, indexes, RLS, query perf, migrations. Enforces idiomatic, safe, performant Postgres.
- ✓"Use when..." + Triggers concretos
- ✓Escopo atômico: só Postgres
- ✓Resultado declarado, nome óbvio
O que mudou de verdade
Nada do conteúdo técnico — só o roteamento e o foco. A versão forte dispara nos casos certos, não dispara nos errados, e diz exatamente o que entrega. É a diferença entre parecer útil e ser usada.
📐 Template de description pronto
Copie, preencha os colchetes, corte o que sobrar. Este molde junta os padrões de frontend-design (o quê + exemplos) e supabase (gatilhos "pushy").
template (cole no frontmatter):
name: [nome-autoexplicativo-em-kebab] description: [VERBO de resultado] [o que entrega]. Use this skill when [situação principal] (examples include [ex1], [ex2], [ex3]). Triggers: [gatilho1], [gatilho2], [gatilho3]. [Diferencial: o que ela garante e outras não].
exemplo preenchido (skill de migrations):
name: db-migrations-safe description: Generate and review reversible database migrations. Use this skill when the user adds, alters, or drops schema (examples include new column, index, rename table, backfill). Triggers: ALTER TABLE, CREATE INDEX, migration file, schema change. Always produces an up + down pair and warns about locking on large tables.
💡 Calibre os triggers
Liste 3–5 gatilhos que devem acionar e pense em 2–3 near-misses parecidos que não devem. Se a description não distingue os dois grupos, ela vai disparar errado — tema do módulo 2.5.
🚦 O loop completo de criação
Juntando tudo: criar uma skill de qualidade é iterativo, não um chute. Capture a intenção, escreva, teste contra baseline, generalize do feedback e otimize a description. Repita até disparar certo.
Capturar intent + draft
Defina a única responsabilidade. Escreva o SKILL.md imperativo, <500 linhas.
2–3 test prompts realistas
Rode com-skill vs baseline. A skill mudou o resultado para melhor?
Generalizar + enxugar
Tire regras gerais do feedback, explique o porquê, extraia scripts repetidos para bundled.
Otimizar description + empacotar
Ajuste com queries should-trigger / should-not-trigger e near-misses. Aí publique.
💡 Onde aprofundar
A anatomia completa do SKILL.md está na Trilha 3, e o loop de criação detalhado na Trilha 4. Aqui você já tem o suficiente para uma primeira skill que parece e é de qualidade.
✅ Resumo do Módulo
Próximo:
Módulo 2.5 — 🚀 Dicas Avançadas: Sinais que Só os Experts Veem. Precisão de triggering, economia de tokens, ler transcripts, pass-rate de evals e por que uma skill popular ainda pode ser ruim.