Quando você digita um pedido, o maestro lê a sua mensagem e, em seguida, lê as descriptions
de todos os agentes que existem. Ele faz uma pergunta implícita: "algum desses textos combina com o que o usuário pediu?"
Se combinar, o agente dispara. Se não combinar — mesmo que o agente seja perfeito para a tarefa — ele fica quieto.
A description é o único elo entre o seu pedido e o especialista certo.
↑ Mesma mensagem do usuário, dois agentes com descriptions diferentes — resultados opostos.
Conteúdo detalhado
🔍 Por que a description dispara
O maestro não tem um catálogo de agentes memorizados. A cada turno, ele lê o seu prompt e os campos
description de todos os agentes disponíveis. A decisão de acionar ou não é uma
correspondência semântica entre o que você pediu e o que a description descreve —
não é um nome, não é um emoji, não é um título.
⚙️ Como o maestro processa
Você envia: "revisa o código de pagamento antes do deploy".
O maestro varre as descriptions de todos os agentes ativos.
Se uma description diz "após mudanças em pagamentos, use proactively" — combina. Dispara.
Se a description diz apenas "agente de revisão" — vaga demais para combinar. Silêncio.
A description é lida pelo maestro a cada turno para decidir qual agente usar. É o único texto que guia a seleção automática.
Agentes com descriptions vagas são invisíveis ao maestro. Sem entender o mecanismo, você cria agentes que nunca aparecem e não sabe por quê.
Correspondência semântica · leitura por turno · description como algoritmo de roteamento.
⚖️ Fraca × forte: o que separa as duas
Uma description fraca diz o que o agente é. Uma description forte diz quando usar e para quê. A diferença parece sutil, mas é a distância entre um agente que nunca dispara e um que dispara na hora exata.
❌ Descriptions fracas
- ▸
"Agente para revisão de código."
— vago, sem gatilho, dispara para tudo ou nada - ▸
"Helper de programação."
— tão amplo que concorre com qualquer agente - ▸
"Especialista em segurança."
— título sem condição: o maestro não sabe quando - ▸
"Faz análises."
— uma palavra que cobre tudo, logo cobre nada
✅ Descriptions fortes
- ▸
"Revisa diffs em auth/pagamentos. Use proactively após mudanças nessas áreas."
— domínio + condição + instrução de quando - ▸
"Pesquisa na web e indexa fontes. Acione quando o usuário precisar de dados externos ou quiser verificar fatos."
— caso de uso claro, não competitivo - ▸
"Gera e revisa planos de implementação. Use proactively antes de qualquer tarefa de desenvolvimento grande."
— "antes de" define o momento exato
A diferença estrutural: fraca descreve identidade; forte descreve situação de uso.
Descriptions fracas criam agentes que nunca disparam (sub-uso) ou disparam em tudo (over-disparo). Forte é cirúrgica.
Identidade vs. situação · gatilho condicional · "Use proactively" como instrução de timing.
⏱️ "Use proactively" — o timing explícito
A frase Use proactively na description é uma instrução direta ao maestro:
"não espere o usuário pedir explicitamente — dispare quando o contexto combinar". Sem ela, o maestro pode
hesitar e não acionar o agente mesmo quando o contexto é perfeito.
💡 Anatomy de uma description com timing
Use proactively após qualquer mudança em auth, pagamentos ou sessões.
"Revisa o diff…" — a tarefa em si.
"Use proactively após…" — o timing explícito.
"auth, pagamentos, sessões" — restringe o escopo.
⚡ Dica prática
Use "Use proactively" apenas quando você quer disparo automático.
Para agentes que só devem ser chamados por nome (@nome), omita a frase —
o maestro então esperará ser invocado explicitamente, sem se meter onde não foi chamado.
A instrução "Use proactively" na description autoriza o maestro a disparar o agente sem pedido explícito do usuário.
Sem esse padrão, agentes valiosos ficam ociosos. Com ele aplicado em excesso, tudo dispara — indesejável.
Proativo vs. reativo · "@nome" para invocação manual · timing como dimensão da description.
🔥 Misfires: quando o agente dispara errado
Há dois tipos de misfire: a mais (dispara quando não devia) e a menos (não dispara quando devia). Ambos têm a mesma causa — a description não descreve o caso de uso com precisão suficiente.
🔊 Misfire A mais — over-disparo
- Causa: description muito ampla ou "Use proactively" sem restrição de domínio.
- Sintoma: o agente aparece em pedidos que não têm nada a ver.
- Exemplo: "Revisa código. Use proactively." → dispara para qualquer menção a código.
- Fix: adicionar restrição de domínio — "Revisa diffs em auth/pagamentos. Use proactively após mudanças nessas áreas."
🔇 Misfire A menos — sub-disparo
- Causa: description muito específica, sem sinônimos, ou sem "Use proactively".
- Sintoma: o agente nunca aparece, mesmo sendo o ideal para a tarefa.
- Exemplo: "Agente de revisão." → o maestro não conecta a descrição com o pedido.
- Fix: ampliar o vocabulário e adicionar trigger — "Revisa diffs. Use proactively após mudanças."
Como diagnosticar um misfire
Observe o comportamento
O agente disparou quando não devia, ou deveria ter disparado e não apareceu?
Leia a description atual
Pergunte: se eu fosse o maestro, esse texto me diria quando usar esse agente?
Ajuste o gatilho ou o domínio
A mais: adicione restrição. A menos: adicione "Use proactively" e expanda o vocabulário.
Dois padrões de falha — o agente dispara demais (description ampla) ou de menos (description vaga/sem trigger).
Misfires são a principal causa de desconfiança no sistema. Reconhecer o tipo acelera o conserto em segundos.
Over-disparo vs. sub-disparo · domínio como filtro · diagnóstico iterativo.
💥 Colisão skill × agent: o caso plan-roaster
Skills (arquivos em .claude/commands/) e agents (arquivos em
.claude/agents/) podem colidir quando ambos têm descriptions semânticas parecidas.
O maestro às vezes seleciona um quando o usuário queria o outro. O caso
plan-roaster ilustra esse problema e como resolvê-lo.
📌 O caso plan-roaster
❌ Antes: descrição que colidia
description: Analisa e critica
planos de implementação.
tools: Read
Problema: "analisa planos" também combina com a skill /plan → colisão.
✅ Depois: description cirúrgica
description: Critica planos
de implementação prontos,
buscando furos e riscos.
Use após um plano ser
gerado, não durante.
tools: Read
Fix: "após um plano ser gerado" diferencia do /plan (que cria, não critica).
🧪 Como detectar colisões
- →Peça ao maestro: "liste os agentes e skills que combinam com 'criar um plano'".
- →Se dois aparecem com semântica semelhante, um dos dois precisa de uma description mais específica.
- →O que diferencia: skills são ações disparadas pelo usuário; agents são trabalhadores automáticos.
Colisão acontece quando a description de um agent e a de uma skill se sobrepõem semanticamente — o maestro escolhe um e você queria o outro.
À medida que o repertório de agentes cresce, colisões são inevitáveis sem disciplina na description.
Overlap semântico · skill vs. agent · "após" como separador temporal de escopo.
🔄 Iterar: perguntar por que não disparou
O maestro é seu aliado no diagnóstico. Quando um agente não dispara como esperado, a estratégia mais rápida é perguntar diretamente ao maestro por que não usou aquele agente — e pedir que proponha uma description corrigida.
Por que o agente [nome] não disparou no meu último pedido?
Leia a description dele e explique o mismatch.
Depois proponha uma description corrigida.O agente [nome] disparou quando eu pedi "[pedido X]",
mas não queria isso. Leia a description e diga por que
combinou. Reescreva para evitar esse over-disparo.🔍 O loop de iteração
O fluxo de diagnóstico: perguntar ao maestro sobre o mismatch, receber sugestão, editar, testar.
Tentar adivinhar o problema sem perguntar ao maestro é lento. Ele tem acesso à description e ao contexto — use isso.
Diagnóstico assistido · loop curto · o maestro como detetive da própria seleção.
🐛 Fechar aspas no YAML — o bug real
O frontmatter dos agentes é YAML. YAML tem regras silenciosas sobre aspas e quebras de linha. O bug mais comum (e invisível) é uma aspas não fechada ou indentação incorreta que faz o parser cortar a description no meio — o agente carrega, mas o gatilho fica truncado.
---
name: code-reviewer
description: "Revisa o diff após mudanças
em auth e pagamentos. Use proactively
após qualquer alteração nessas áreas.
tools: Read, Grep
---
# Code Reviewer
Revisa o diff do repositório atual...Bug: aspas abertas em " nunca fechadas. O parser YAML lê tudo até a próxima aspas (inexistente) — a description vai truncada ou quebra o frontmatter inteiro.
---
name: code-reviewer
description: Revisa o diff após mudanças
em auth e pagamentos. Use proactively
após qualquer alteração nessas áreas.
tools: Read, Grep
---
# Code Reviewer
Revisa o diff do repositório atual...Fix: usar block scalar YAML (sem aspas, indentação consistente). A description é lida completa.
❌ Evitar
- • Aspas sem fechar
- • Dois pontos sem aspas no meio da frase
- • Indentação mista (tab + espaço)
- • Linhas de continuação sem espaço inicial
✅ Fazer
- • Block scalar: sem aspas, 2 espaços de indent
- • Testar com
python -c "import yaml; yaml.safe_load(open('agent.md').read())" - • Uma frase por linha nas continuações
🔍 Diagnóstico
- • Agente carrega mas nunca dispara? Verifique o YAML.
- • Peça ao maestro: "leia o frontmatter de [agent.md] e valide o YAML".
Bug silencioso de YAML que trunca a description — o agente existe mas o gatilho está partido.
É o bug mais difícil de perceber: o arquivo é válido, o agente carrega, mas o comportamento muda sem aviso.
Block scalar YAML · frontmatter parsing · validação antes de confiar no disparo.
Prompts prontos para usar agora
Cole estes prompts diretamente no maestro para diagnosticar e consertar descriptions.
Por que o subagente [nome] não disparou nesse prompt?
Leia o arquivo .claude/agents/[nome].md, analise a
description e diga onde está o mismatch.
Depois reescreva a description para consertar.Liste todos os agentes e skills cujas descriptions
combinam com "[pedido X]". Se mais de um combinar,
aponte a colisão e sugira como diferenciar cada um.Leia o arquivo .claude/agents/[nome].md e valide o
frontmatter YAML. Há aspas não fechadas, dois pontos
no meio de strings sem aspas, ou indentação mista?
Se sim, corrija e mostre o frontmatter válido.Tela simulada: diagnosticando uma description
Veja como o loop de diagnóstico aparece na prática — o usuário pede ao maestro para explicar por que o agente não disparou e recebe a description corrigida.
Use proactively após mudanças em auth, pagamentos ou sessões.
↑ Recriação ilustrativa do terminal. O maestro tem acesso ao arquivo do agente e pode propor a correção diretamente.
Exercício: reescrever uma description fraca
Dada a description abaixo, reescreva-a para que o agente dispare no momento certo, sem over-disparo. Use as três dimensões que você aprendeu: o quê, quando e domínio.
Description original (fraca)
description: Agente que ajuda com deploys.
tools: Bash, Read
Como fazer
- Imagine o que esse agente faria de útil num deploy (ex.: checar variáveis de ambiente, validar Docker, verificar migrations pendentes).
- Defina quando você quer que ele apareça automaticamente — antes, durante ou após o deploy?
- Restrinja o domínio — ele deve disparar para qualquer menção a código ou só para pedidos explícitos de deploy?
- Escreva a description em 2–3 linhas, incluindo "Use proactively" com a condição específica.
✅ Critério de verificação
Sua description está boa quando:
- →Um colega consegue dizer em 5 segundos quando esse agente dispara.
- →Ela não combina com pedidos genéricos como "ajuda com código" ou "olha esse arquivo".
- →Ela sim combina com "faz o deploy da feature X" ou "vou subir pra produção".
- →O YAML está válido: sem aspas soltas, indentação com 2 espaços.
Exemplo de resposta possível
description: Verifica pré-requisitos de deploy:
variáveis de ambiente, migrations pendentes
e configuração de Docker. Use proactively
quando o usuário mencionar deploy, subida
para produção ou push de feature.
tools: Bash, Read
Observe: o quê ("verifica pré-requisitos"), quando ("mencionar deploy/subida/push"), domínio específico.
✅ Resumo do módulo
Próximo módulo:
2.3 — O corpo é o cérebro. O que vai no corpo do arquivo .md e como ele define o comportamento real do agente.