Quando você instala o Claude Code, um conjunto de agentes já está lá — invisíveis, prontos, sem que você precise criar nada.
São os built-ins. Mas o sistema também permite que qualquer arquivo
.md com o frontmatter certo
vire um agente novo — um custom. O diagrama abaixo mostra a bifurcação: o maestro
lê name e description, decide qual dos dois ramos seguir, e despacha o trabalho.
↑ O maestro não precisa saber se o agente é built-in ou custom — ele lê name e description e decide. A bifurcação é interna ao sistema.
💡 Conceito central
Para o maestro, built-in e custom são idênticos: ambos têm nome, descrição e ferramentas.
A diferença é de origem — os built-ins vêm com o Claude Code; os customs você cria com um arquivo
.md dentro de
.claude/agents/.
Conteúdo detalhado
O que são os built-ins
O Claude Code registra quatro agentes na instalação. Eles não aparecem como arquivos no seu projeto — estão embutidos no binário. Você os invoca pelo nome exato ou deixa o Claude escolher automaticamente.
Por que conhecer cada built-in
Quando você deixa o Claude escolher, ele usa a description para decidir. Sem conhecer os built-ins, você não percebe quando o escolhido é inadequado — e cria um custom redundante desnecessário.
Dica: verifique /agents antes de criar qualquer custom.
Conceitos-chave
- →Embutidos no binário — não são arquivos, não aparecem no projeto, não precisam de manutenção sua.
- →Explore é read-only — por design, não tem ferramentas de escrita; ideal para pesquisa segura.
- →general-purpose ≠ custom — mesmo que você passe um "system prompt" ao invocar o general-purpose, ele não vira um custom; é uma persona temporária.
O que é a confusão
Muita gente descobre que pode invocar o general-purpose com uma instrução adicional
— "aja como um revisor de código crítico" — e acha que criou um agente novo. Não criou. Criou uma persona efêmera:
ela existe apenas naquela conversa, não tem nome próprio no sistema, não pode ser invocada depois e não aparece no /agents.
Por que a distinção importa
✅ Use persona efêmera quando
- ✓É uma tarefa única, não repetitiva
- ✓Você não precisa do agente amanhã
- ✓O comportamento varia a cada invocação
❌ Não substitui custom quando
- ✗Você usa o mesmo padrão toda semana
- ✗Outros no time precisam invocar o mesmo agente
- ✗Precisa de ferramentas restritas ou específicas
Conceitos-chave
- →Persona efêmera — existe só na conversa atual; morre quando você fecha a sessão.
- →Custom é persistente — vive no arquivo
.md, pode ser versionado no Git, e qualquer membro do time o usa. - →Regra prática — se você vai repetir mais de 3 vezes, crie um custom.
O que é um agente custom
Um agente custom é um arquivo Markdown com frontmatter YAML na primeira linha. Salvo em
.claude/agents/
(projeto) ou ~/.claude/agents/ (global),
ele é registrado automaticamente — sem instalar nada, sem reiniciar.
Por que esse formato funciona
O Claude registra o agente lendo apenas o frontmatter. O corpo do .md é o
system prompt do agente — só é lido quando ele é invocado. Isso permite um catálogo enorme de agentes
sem custo de tokens no maestro: progressive disclosure em ação.
Conceitos-chave
- →Frontmatter obrigatório:
nameedescription. O resto é opcional. - →Escopo: agentes em
.claude/agents/do projeto ficam disponíveis apenas nele; globais em~/.claude/agents/. - →Versionável: o arquivo
.mdvai para o Git junto com o projeto — toda a equipe usa a mesma definição.
O que é progressive disclosure aqui
O maestro não carrega o corpo inteiro de cada agente no contexto para decidir qual usar.
Ele lê apenas name e
description de todos os agentes disponíveis —
um catálogo enxuto. O system prompt completo (o corpo do .md) só é
carregado quando o agente é de fato invocado.
Por que isso importa
name + description de todos os agentes. Custo: mínimo..md é carregado — na janela do agente, não no maestro.Conceitos-chave
- →Description como contrato: é a única coisa que determina quando o agente é escolhido. Uma description vaga = invocação errada.
- →Você pode ter 50 agentes sem pagar tokens de seleção: o catálogo de names+descriptions é enxuto.
- →Cuidado com descriptions longas: a Trilha 2 ensinará a "trimar" para deixar apenas o gatilho essencial.
O modelo de custo
Cada token no contexto do maestro custa — em dinheiro e em atenção. O modelo built-in/custom evita custo desnecessário: o maestro carrega metadados (name + description), não o system prompt completo.
✅ Com progressive disclosure
- ✓Maestro carrega ~5 tokens por agente (name)
- ✓System prompt só entra na janela do agente
- ✓Contexto do maestro permanece limpo
- ✓Escala para dezenas de agentes sem custo
❌ Sem separação (inline)
- ✗System prompt de cada agente no contexto
- ✗Contexto do maestro cresce a cada turno
- ✗Custo multiplica com o número de agentes
- ✗Menos espaço para o trabalho real
Por que isso escala
20 agentes × 300 palavras cada = 6.000 palavras só de "configuração" sem progressive disclosure. Com a separação: ~100 palavras de metadados; os 300 de cada agente ficam na gaveta até serem chamados.
Regra de ouro: a description tem menos de 2 linhas. O detalhamento vai no corpo do .md.
Conceitos-chave
- →Metadados ≠ comportamento — description determina seleção; o corpo do .md determina execução.
- →Separar responsabilidades — maestro decide, agente executa, cada um com seu contexto próprio.
- →O custo real é de atenção, não só de dinheiro — um contexto lotado produz respostas piores.
O que é o /agents
Digite /agents no Claude Code para abrir o painel
de agentes. Ele lista tudo: built-ins registrados pelo sistema e customs encontrados nas pastas
.claude/agents/ do projeto e
~/.claude/agents/ global.
É também daqui que você cria novos agentes com o assistente interativo.
↑ Saída ilustrativa do /agents. Os built-ins aparecem primeiro; os customs mostram de qual pasta vieram.
Por que verificar antes de criar
Antes de escrever um custom, abra o /agents
e leia as descriptions dos built-ins. Em muitos casos — especialmente busca de código, planejamento e tarefas genéricas —
um built-in já faz o que você precisa, com configuração zero.
Fluxo recomendado: /agents
→ leia as descriptions → se nenhum serve, crie um custom. Nunca o contrário.
Conceitos-chave
- →/agents é o inventário: sempre a fonte de verdade sobre o que está disponível no contexto atual.
- →Escopo visível: o /agents mostra agentes do projeto atual + globais. Em outro projeto, a lista muda.
- →Criar pelo wizard: ao pressionar n no /agents, o Claude te guia para preencher frontmatter — boa porta de entrada para o primeiro custom.
Prompts prontos para usar agora
Copie qualquer um destes prompts e cole no Claude Code para explorar os conceitos deste módulo na prática.
Resultado esperado: o Claude usa o /agents internamente e te devolve a lista com descriptions resumidas.
O Claude vai comparar os built-ins disponíveis com a tarefa e recomendar a abordagem certa.
Bom para experimentar progressive disclosure: veja como o frontmatter sozinho já define o contrato.
Exercício
Acesse o /agents na sua máquina e
catalogue os built-ins disponíveis.
Para cada um, escreva: nome, uma linha de description e um exemplo de tarefa onde ele seria a escolha certa.
Como fazer
- Abra o Claude Code e digite
/agents. - Leia as descriptions de cada built-in (não os custom ainda).
- Para cada built-in, escreva: nome | description resumida | exemplo de tarefa concreta.
- Identifique qual built-in você usaria com mais frequência no seu contexto de trabalho.
✅ Critério de verificação
Você completou o exercício se conseguir responder:
- →Qual built-in é read-only? (resposta: Explore)
- →Qual usar para criar um plano de refatoração? (resposta: Plan)
- →Qual usar quando nenhum outro se encaixa? (resposta: general-purpose ou claude)
Bônus
Depois de catalogar os built-ins, identifique uma tarefa do seu dia que nenhum built-in cobre bem. Anote o nome que você daria ao agente custom e uma description de duas linhas. Você vai criar esse agente na Trilha 2.
✅ Resumo do módulo
Próximo módulo:
1.5 — A pergunta que decide. Como saber quando um subagente resolve — e quando ele complica.