Gerador de subagentes do Claude Code
Descreva uma tarefa única e bem definida que você queira delegar - revisar PRs em busca de falhas de segurança, escrever testes unitários, pesquisar como algo funciona em uma base de código - e receba um arquivo .claude/agents/<nome>.md completo para colocar direto no Claude Code. A IA escreve o conteúdo; o nome, o cabeçalho YAML e a lista de ferramentas permitidas são todos verificados em relação às regras reais de subagentes enquanto você edita, e uma descrição somente leitura contendo ferramentas com capacidade de escrita é sinalizada automaticamente.
1. Descreva a tarefa que você quer delegar
Linguagem simples já basta. Pense em uma fatia de trabalho bem definida que você entregaria de bom grado a um especialista, do qual só leria o resumo - é exatamente para isso que um subagente serve.
Ou comece a partir de um destes
O seu .claude/agents/<name>.md vai aparecer aqui, totalmente editável, com o nome e a descrição verificados contra as restrições reais dos subagentes enquanto você digita.
O que um arquivo de subagente realmente contém
Um subagente é um único arquivo markdown: frontmatter YAML no topo, um corpo markdown abaixo. O corpo não é uma dica ou um complemento - é todo o system prompt do subagente, substituindo o padrão do Claude Code durante todo o tempo em que esse subagente roda. Ele também começa na sua própria janela de contexto, sem nada da sua conversa atual carregado junto, então tudo o que ele precisa saber tem que estar escrito nesse corpo.
Apenas dois campos do frontmatter são obrigatórios. name usa só letras minúsculas e hífens, não contém dois-pontos, e precisa ser único entre seus subagentes - é o nome do arquivo e como você chama o subagente manualmente. description é o campo que vale a pena pensar bastante, porque é o único texto que o Claude lê para decidir qual subagente deve receber uma tarefa. Dois subagentes com descrições vagas vão roubar o trabalho um do outro.
Todo o resto é opcional, e este construtor conecta cada um deles de verdade ao arquivo: tools (uma lista de permissões separada por vírgulas - omita para herdar todas as ferramentas), disallowedTools (a lista de bloqueio), model (sonnet, opus, haiku, fable, um ID de modelo completo, ou inherit), permissionMode, maxTurns (um limite de turnos agênticos antes de parar e retornar uma saída parcial), skills (nomes de skills pré-carregados no contexto dele) e color, que é só visual.
A coisa mais valiosa que você pode fazer com essa lista é manter tools restrito. Um revisor de código que só tem Read, Glob, Grep não pode reescrever sua branch enquanto está "ajudando", não importa como a conversa evolua. Esta ferramenta cruza a lista de permissões com o que sua descrição diz ser a função do subagente, e sinaliza uma tarefa de somente leitura que, de alguma forma, recebeu Write, Edit ou Bash.
Perguntas frequentes
O que é exatamente um subagente do Claude Code?
Um subagente é uma instância especializada do Claude que roda em sua própria janela de contexto separada com um system prompt diferente, permitindo delegar a ele uma subtarefa bem definida e receber de volta apenas o resumo. Ele é definido por um único arquivo markdown em .claude/agents/<nome>.md: um cabeçalho YAML com um nome e uma descrição no topo, e um corpo que se torna o system prompt completo daquele subagente. Como ele trabalha em um contexto isolado, a longa e confusa exploração que faz - ler cinquenta arquivos, rodar greps, seguir becos sem saída - nunca chega à sua conversa principal. Só o relatório final chega. Esse isolamento é o objetivo principal: mantém seu contexto principal limpo, e permite dar a uma tarefa restrita, perigosa se usada incorretamente, um conjunto igualmente restrito de ferramentas.
Agentes vs skills do Claude Code - qual é a diferença?
Uma skill carrega instruções na conversa que você já está tendo; um subagente inicia uma conversa totalmente nova própria. Quando uma skill é ativada, o corpo do seu SKILL.md é adicionado ao contexto atual do Claude, e o Claude continua trabalhando como ele mesmo, com tudo que já sabia. Quando um subagente é ativado, o Claude gera uma instância separada com um contexto em branco e um system prompt diferente, essa instância trabalha sozinha, e só a mensagem final dela volta. Então recorra a uma skill quando quiser ensinar ao Claude como fazer algo que ele fará aqui mesmo depois - um estilo próprio, um checklist, um procedimento de lançamento. Recorra a um subagente quando quiser que o trabalho seja feito em outro lugar e só quiser a conclusão: uma busca grande que você não quer poluindo seu contexto, ou uma revisão que você quer que seja feita por algo que literalmente não pode editar seus arquivos. Um comando slash é uma terceira coisa, ainda mais simples: um prompt salvo que você aciona digitando /nome, executado inline, sem isolamento e sem identidade própria.
Como eu crio um subagente no Claude Code?
Crie a pasta com mkdir -p .claude/agents, salve nela um arquivo markdown nomeado como o subagente, e recarregue o Claude Code. O arquivo precisa de um cabeçalho YAML com pelo menos name (apenas letras minúsculas e hífens, sem dois-pontos, único) e description (quando o Claude deve delegar a ele), seguido do corpo que funciona como seu system prompt. Coloque-o em .claude/agents/ dentro do repositório para commitá-lo no git e compartilhar com sua equipe, ou em ~/.claude/agents/ na sua pasta pessoal para mantê-lo pessoal em todos os seus projetos. Se ambos existirem com o mesmo nome, o do projeto vence dentro daquele repositório. Este gerador escreve o arquivo inteiro para você e mostra o caminho exato e o comando mkdir para o escopo que você escolher.
Por que a lista de ferramentas permitidas importa tanto?
Porque é o único limite rígido sobre o que um subagente pode fazer. Se você omitir tools, o subagente herda tudo o que a conversa principal tem, incluindo ferramentas MCP - ótimo para um ajudante confiável, desnecessariamente arriscado para um cujo único trabalho é olhar e relatar. Um revisor de segurança com Read, Glob, Grep fisicamente não consegue modificar sua árvore de trabalho; o mesmo revisor com Bash e Write consegue. A regra prática é o menor privilégio: conceda o mínimo necessário para o trabalho, adicione Write e Edit apenas para um subagente que deva alterar arquivos, e adicione Bash apenas quando ele genuinamente precisar rodar algo como uma suíte de testes. Este construtor sinaliza a incompatibilidade nos dois sentidos - uma descrição de revisão com ferramentas de escrita, e uma descrição de correção sem nenhuma forma de escrever algo.
Como o Claude decide qual subagente usar?
Ele compara a tarefa com a descrição de cada subagente, então essa string é sua tabela de roteamento. Uma descrição como 'Revisa código' não dá ao Claude nada para discriminar e será escolhida para tudo ou para nada. Em vez disso, nomeie os gatilhos concretos: 'Revisa código alterado em busca de vulnerabilidades de segurança - injeção, falta de autorização, desserialização insegura, segredos vazados. Use proativamente após qualquer mudança em autenticação ou tratamento de entrada, e sempre que o usuário pedir uma revisão de segurança.' Dizer 'usar proativamente' incentiva a delegação automática; você sempre pode sobrepor isso pedindo um por nome - 'use o subagente security-code-reviewer para checar este diff'. Em uma configuração multiagente onde vários subagentes se sobrepõem, as descrições precisam traçar fronteiras claras entre eles, por isso este gerador avisa ao vivo quando a sua soa genérica ou omite a parte do 'quando'.
Dois companheiros deste aqui: o Claude Skill Generator escreve um SKILL.md que carrega instruções na conversa em que você já está, e o AI Slash Command Generator escreve a versão de arquivo único em /command.