Mapa da trilha
📋 O frontmatter completo
Config que determina quem você é
🎯 A descrição é o gatilho
Uma frase que dispara o agente certo
🧠 O corpo é o cérebro
Papel + passos + saída + não-fazer
🔐 Ferramentas e permissões
tools: — só o que precisa
📁 Projeto × Global
Onde mora define quem vê
🚀 Criando com /agents
Como o Claude escolhe e lança
Conteúdo detalhado
📋 O frontmatter completo
O YAML entre os --- que configura tudo antes de o Claude ler uma linha do corpo. Cada campo, por que existe e o que muda se você omitir.
O bloco YAML delimitado por --- no topo do arquivo. É a zona de config: o Claude lê antes de processar o conteúdo.
Sem entender o frontmatter, todos os campos parecem mágica. Entender a estrutura separa o que configura do que instrui.
Frontmatter = config; corpo = instrução. São zonas distintas com propósitos distintos.
O identificador único do agente. Aparece no /agents, no log do FleetView e permite invocar pelo nome ("use o security-reviewer").
Um nome ruim impede invocação direta e polui o catálogo. Kebab-case descritivo é a convenção.
Kebab-case; sem espaços; nome = handle de invocação direta.
Lista YAML das ferramentas que o agente pode chamar: Bash, Read, Write, WebFetch, etc. Omitir dá acesso total — o que raramente é o ideal.
Limitar ferramentas é a primeira camada de segurança. Um agente que só lê não pode apagar nada.
Princípio do menor privilégio; lista explícita > acesso total omitido.
Seleciona qual modelo Claude roda o agente: sonnet (padrão), haiku (rápido/barato), opus (profundo). Omitir herda o modelo do processo pai.
É a alavanca de custo. Tarefas mecânicas em haiku; análise profunda em opus. Escolha consciente poupa créditos.
Herda se omitido; sonnet = default seguro; haiku = baterias de tarefas.
color define a cor no FleetView; memory habilita notas persistentes; isolation: worktree roda em git branch isolado.
Campos opcionais destravem casos de uso avançados sem poluir o config básico. Você escolhe quando crescer.
Optional = progressivo; adicione quando o caso pedir.
Sem name o arquivo é ignorado. Sem tools vem acesso total. Sem model herda do pai. Sem description nunca é escolhido automaticamente.
Defaults invisíveis causam bugs silenciosos. Saber o que cada omissão ativa evita surpresas na produção.
name obrigatório; description = roteamento automático; tools = segurança.
🎯 A descrição é o gatilho
O campo mais influente do agente. Uma description bem escrita faz o Claude escolher o agente certo — automaticamente, sem você nomear.
Quando você pede algo, o Claude lê apenas o name + description de todos os agentes disponíveis e decide qual usar sem ver o corpo.
É o mecanismo central de roteamento. Entender como o Claude decide qual agente chamar muda como você escreve a description.
Roteamento por description; corpo só entra quando o agente é ativado.
Uma boa description tem: (1) o que o agente faz, (2) quando usar e (3) exemplos de acionamento — como um verbete de dicionário de especialista.
É o texto mais lido do seu agente — lido toda vez que o Claude decide. Uma frase ruim = agente nunca chamado ou sempre chamado errado.
O que faz + quando usar + exemplos de acionamento.
Três erros clássicos: (1) vaga demais — o Claude nunca escolhe; (2) longa demais — desperdiça tokens de catálogo; (3) igual ao general-purpose — o agente nunca ganha da seleção padrão.
Reconhecer o erro evita revisão. Uma description ruim é invisível até você perceber que o agente nunca dispara.
Específico > genérico; conciso > longo; diferenciado > cópia do default.
Adicionar na description seções explícitas "TRIGGER (quando acionar)" e "SKIP (quando não acionar)" — o padrão usado nos agents de produção.
Elimina falsos positivos. O Claude entende literalmente "não acionar para X" e respeita — reduz invocações desnecessárias.
TRIGGER = sinal verde; SKIP = sinal vermelho explícito na description.
O método: invocar o agente com cenários reais, observar quando não dispara ou dispara errado, refinar a description e retestar — ciclo curto.
Ninguém acerta na primeira tentativa. O ciclo rápido de edição-teste é a habilidade que separa agentes funcionais dos eternamente "quase prontos".
Ciclo editar → testar → ajustar; o feedback é o sinal, não a intuição.
Leitura e análise de descriptions reais de agents do ecossistema Claude Code (claude-code-guide, general-purpose, Explore) — o que funcionou e por quê.
Exemplos reais ensinam mais que teoria. Ver um padrão de produção calibra suas expectativas.
Pattern matching; ler agents existentes como exercício.
🧠 O corpo é o cérebro
O Markdown depois do frontmatter. Aqui mora o papel, os passos, o formato de saída e o que o agente nunca deve fazer — tudo que determina a qualidade do output.
A primeira linha do corpo define o papel do agente: "Você é um especialista em X que faz Y". Essa frase ancora todo o comportamento seguinte.
Agentes sem declaração de papel derivam — ficam genéricos. O papel é o norte que orienta cada decisão dentro da tarefa.
Papel = identidade; quanto mais específico, mais coerente o output.
Lista numerada que define o protocolo: 1. Leia X 2. Identifique Y 3. Produza Z. O agente segue a lista como um checklist interno.
Sem passos, o agente interpreta criativamente — às vezes bem, às vezes não. Passos numerados tornam o comportamento reproduzível.
Reproduzibilidade; cada passo = uma ação verificável.
Uma seção do corpo que diz exatamente o formato do relatório: bullet list, tabela, JSON, texto corrido — com exemplo mínimo se ajudar.
O maestro processa o output do agente. Um formato inesperado quebra a cadeia. Especificar o output é parte do contrato do agente.
Formato = contrato; o maestro é o consumidor do output.
Seção "NÃO FAÇA" com proibições explícitas: não deletar arquivos, não fazer commits, não perguntar ao usuário, não inventar dados.
Instruções negativas são mais fortes que positivas para guardrails. O agente lembra mais "nunca X" do que "às vezes não X".
Guardrail negativo = mais forte; lista de proibições previne acidentes.
Você pode embutir contexto permanente no corpo: caminhos fixos de pastas, convenções do projeto, listas de ferramentas MCP disponíveis.
Contexto no corpo evita repetir no prompt de invocação. O agente já sabe onde estão as coisas antes de receber a tarefa.
Contexto permanente vs contexto de invocação; o corpo é o briefing pré-carregado.
Corpo mínimo = papel + 3-5 passos + formato de saída. Corpo rico adiciona exemplos, contexto, edge cases. Quando cada um é suficiente.
Perfeccionismo paralisa. Saber quando o mínimo é suficiente e quando vale investir mais é uma habilidade prática.
MVP do agente; iterar depois que o mínimo funciona.
🔐 Ferramentas e permissões
O campo tools determina o que o agente pode e não pode fazer. Princípio do menor privilégio aplicado — e como usar disallowed-tools para blindar.
Bash, Read, Write, Edit, WebFetch, WebSearch, Agent, Grep, LS — cada ferramenta com seu propósito e o que ela permite fazer no sistema.
Você não pode dar permissão do que não conhece. Conhecer o catálogo é o pré-requisito para a configuração consciente.
Catálogo: Bash=executa, Read=lê, Write=cria, Edit=modifica, Agent=subagente filho.
Um agente de leitura precisa de Bash (grep), Read e Grep — nada de Write ou Edit. Define o scope pelo tipo de tarefa, não pelo "e se precisar".
Agentes com acesso excessivo causam estragos acidentais. O menor privilégio torna o agente previsível e auditável.
Read-only agents = mais seguros; Bash+Write = só quando necessário.
O campo disallowed-tools proíbe ferramentas específicas mesmo que o perfil pai as permita — uma camada adicional de bloqueio explícito.
Quando o agente herda permissões de um perfil amplo, a blocklist é a única forma de excluir o que não deve usar.
Blocklist complementa allowlist; explícito sobrescreve herdado.
Ferramentas MCP (Model Context Protocol) estendem o catálogo: acesso a banco de dados, APIs externas, sistemas de arquivos remotos — cada servidor MCP registrado vira uma ferramenta.
MCP multiplica as capacidades do agente. Saber dar (ou bloquear) acesso a um server MCP específico é uma habilidade-chave.
MCP server = conjunto de ferramentas externas; nome no tools: = registro.
Como usar o /agents para inspecionar o perfil de ferramentas de cada agente antes de rodá-lo — identificar permissões excessivas.
Auditoria pré-execução é o hábito que previne acidentes. "Deixa rodar e vê o que acontece" é a receita para perda de dados.
Revisar antes de executar; /agents como ferramenta de inspeção.
Perfis típicos: (1) Leitor [Read, Bash(grep)] (2) Analista [Read, WebFetch, Bash] (3) Construtor [+Write, Edit] (4) Orquestrador [+Agent]. Cada perfil com uso-alvo.
Templates aceleram a criação. Em vez de inventar do zero, você escolhe o perfil mais próximo e ajusta.
4 perfis base; ajuste fino por caso de uso.
📁 Projeto × Global
Onde o arquivo .md mora determina quem o vê — só este repositório ou toda a sua máquina. A regra é simples, a implicação é grande.
Projeto: .claude/agents/ na raiz do repositório. Global: ~/.claude/agents/ no home. Um é local ao repo, o outro é disponível em todo projeto da máquina.
Colocar no lugar errado faz o agente desaparecer (projeto) ou vazar pra contextos onde não deveria existir (global).
.claude/agents/ = projeto; ~/.claude/agents/ = global; escopo determina visibilidade.
Global é ideal para agentes de uso universal: revisores de código que independem do projeto, pesquisadores, agentes de documentação pessoal.
Criar tudo como global polui o catálogo de todos os projetos. Saber distinguir economiza confusão na hora da seleção automática.
Global = agnóstico de projeto; projeto = especializado no domínio do repo.
Projeto é ideal para agentes que conhecem o domínio específico do repositório: estrutura de pastas, convenções de nomenclatura, scripts locais.
Um agente de projeto pode embutir no corpo os caminhos exatos do repo — context que um agente global nunca teria.
Context específico do repo = vantagem do agente de projeto.
Quando existem dois agentes com o mesmo nome (um de projeto, um global), o de projeto prevalece — permite override local de comportamento global.
O override é uma feature, não um bug. Você pode adaptar um agente global para um projeto específico sem alterar o global.
Projeto sobrescreve global; override intencional é uma técnica válida.
Agentes de projeto ficam no git junto com o código — diff, blame, rollback. Agentes globais ficam fora do repo e precisam de estratégia própria (dotfiles, symlinks).
Versionar o agente junto com o código garante que o time use a mesma versão — sem drift silencioso entre ambientes.
Agente = código; versionar = rastreabilidade; dotfiles para o global.
Convenções para manter o catálogo legível: prefixos por domínio (sec-, doc-, infra-), README.md na pasta agents, deprecação explícita.
Com 20+ agentes, sem organização o catálogo vira um problema. Estrutura desde o início poupa refatoração futura.
Prefixos + README + deprecação = catálogo sustentável.
🚀 Criando com /agents + como o Claude escolhe
O comando /agents como interface de criação e gestão. E o algoritmo de seleção — por que o Claude chama um agente e não outro para a mesma tarefa.
O comando /agents é o painel de gestão: lista todos os agentes disponíveis (built-in + custom), abre assistente de criação e permite inspecionar qualquer agente.
É o ponto de entrada prático para tudo que a Trilha 2 ensina. Dominar o comando é dominar a interface de trabalho.
/agents = painel; lista + inspeciona + cria tudo num lugar.
Ao criar via /agents, o Claude conduz um diálogo: pergunta o propósito, sugere name/description/tools e gera o arquivo — você revisa e ajusta.
A criação guiada é mais rápida que escrever do zero. Mas entender o resultado permite corrigir o que o assistente errou.
Geração assistida + revisão humana = fluxo ideal de criação.
O Claude faz matching semântico entre o pedido e os descriptions disponíveis. Ordem de preferência: (1) invocação direta por nome, (2) match forte de description, (3) general-purpose como fallback.
Entender o algoritmo permite influenciar a seleção: escrever descriptions que ganham do general-purpose nos casos que importam.
Direto > semântico > fallback; description forte vence general-purpose.
Técnicas para diagnosticar seleção incorreta: inspecionar descriptions dos agentes concorrentes, identificar overlap semântico, fazer o Claude explicar a escolha.
"O agente errado foi chamado" é o bug mais comum de catálogos crescidos. Diagnosticar é mais rápido que adivinhar.
Overlap semântico = conflito; distinção clara = seleção precisa.
Exercício completo: criar um agente de revisão de código (code-reviewer) do zero — frontmatter, description com TRIGGER/SKIP, corpo com papel+passos+formato+não-fazer.
É a síntese de toda a Trilha 2. Depois desse exercício você sai com um agente real rodando no seu ambiente.
Do zero ao funcional; todos os campos em harmonia; teste final.
T3 aprofunda modelo e custo (haiku vs opus para cada tipo de agente). T4 expande para Codex e múltiplos ambientes. A Trilha 2 é o núcleo que ambas amplificam.
Contexto sobre o que vem a seguir ajuda a priorizar: se custo importa agora, pule para T3. Se o ambiente é diferente, T4 espera.
T2 = criar; T3 = otimizar; T4 = expandir para outros ambientes.