📋 O frontmatter completo

Imagine o frontmatter como a ficha técnica de um colaborador: nome, ferramentas disponíveis, modelo cognitivo, memória, e o padrão de comportamento geral. O Claude Code lê apenas o frontmatter para decidir se deve chamar este agente — o corpo inteiro só é carregado quando o agente é de fato invocado. Cada campo que você omite vira um valor default; cada campo que você preenche vira uma decisão deliberada.

↑ Anatomia de um arquivo .md: frontmatter (YAML) + corpo (Markdown). O Claude Code lê o frontmatter para decidir; o corpo é o comportamento.

O campo name define o identificador único do seu subagente. É por esse nome que o maestro o chama — e é o nome que aparece na status line quando o agente está rodando. Pense nele como o apelido profissional do colaborador.

# BOM — papel claro, minúsculas, hífens
name: code-reviewer
name: doc-writer
name: sql-optimizer
name: security-auditor

# RUIM — espaço, maiúscula, underscore
name: Code Reviewer     # espaço + maiúscula
name: code_reviewer     # underscore
name: TypescriptChecker # camelCase

A description é o campo mais estratégico do frontmatter. É o texto que o maestro lê para decidir se deve ou não chamar este agente. Pense nela como a placa de entrada do consultório: "cardiologista — dores no peito, check-up cardíaco". Sem a placa certa, o maestro passa pela porta e não sabe o que tem ali dentro.

O campo tools é a lista branca de ferramentas que o subagente pode usar. Se você não declarar nada, ele herda todas as ferramentas do maestro — o que pode ser demais. Restringir ferramentas é uma decisão de segurança e foco: um revisor que só lê não pode acidentalmente escrever arquivos.

O campo model define qual modelo de linguagem executará o agente. Esta é a decisão de custo e qualidade: tarefas simples e repetitivas vão para modelos rápidos e baratos; análises profundas vão para Opus. O tema de modelos por tarefa é a Trilha 3 inteira — aqui aprendemos a sintaxe do campo.

model: haiku          # rápido, barato — triagem, classificação
model: sonnet          # equilibrado — maioria dos casos
model: opus            # profundo e caro — análises complexas

# IDs completos (mais estáveis em produção)
model: claude-haiku-4-5
model: claude-sonnet-4-5
model: claude-opus-4-5

# omitido: herda o modelo do maestro (padrão seguro)

Dois campos que completam a configuração básica: color define a cor de destaque visual do agente na UI, e memory define quais arquivos de memória ele acessa — controlando o que ele "sabe" antes mesmo de a tarefa começar.

color: "#34d399"   # verde
color: "#60a5fa"   # azul
color: "red"       # nome CSS

Enquanto tools é uma lista branca (só o que está lá pode ser usado), disallowed-tools é uma lista negra explícita: "o agente pode usar tudo, exceto estes". Use quando você quer herdar a maioria das ferramentas do maestro mas bloquear especificamente uma ou duas perigosas.

---
name: code-analyzer
description: Analisa a base de código. Nunca modifica arquivos.
model: sonnet
disallowed-tools:
  - Write    # não pode criar / sobrescrever
  - Edit     # não pode editar trechos
  - Bash     # não pode rodar comandos
---

Além dos campos básicos, o frontmatter suporta configurações avançadas para integrar servidores MCP (Model Context Protocol) — que expandem as ferramentas disponíveis com APIs externas, bancos de dados, serviços e muito mais. Estes campos são opcionais e geralmente aparecem em agentes de produção.

---
name: db-analyst
description: Analisa dados no PostgreSQL. Use quando pedir
  insights de banco ou queries de análise.
model: sonnet
tools: mcp__postgres  # ferramenta via MCP
mcp_servers:         # servidores MCP disponíveis
  - postgres         # nome definido em .claude/mcp.json
---

// .claude/mcp.json
{
  "postgres": {
    "command": "mcp-postgres",
    "args": ["postgresql://…"]
  }
}

Um security-auditor.md de produção usando todos os campos que vimos — com comentários explicando cada decisão de design. Este é o ponto de referência que você pode copiar e adaptar.

---
name: security-auditor        # kebab-case, papel claro

description: |               # bloco multiline para descrições longas
  Audita o código em busca de vulnerabilidades de segurança:
  SQL injection, XSS, dependências desatualizadas, segredos
  expostos e falhas de autenticação.
  Use quando o usuário pedir revisão de segurança, antes
  de qualquer PR para produção, ou após mudanças em auth.
                               # ↑ "quando usar" explícito = gatilho preciso

tools: Read, Grep, Glob      # só leitura — auditor nunca modifica

model: claude-opus-4-5       # análise crítica → modelo mais capaz

color: "#f87171"              # vermelho = segurança (visual na UI)

memory: project             # carrega CLAUDE.md do projeto
                               # → conhece as convenções de segurança do repo

disallowed-tools:           # bloqueio explícito de ferramentas destrutivas
  - Write                      # não pode alterar arquivos
  - Edit                       # não pode editar trechos
  - Bash                       # não pode executar scripts
---

# Corpo do agente (cérebro) — carregado só quando invocado

You are a senior application security engineer.
Your role is to audit code for vulnerabilities — never to fix them.

When invoked:
1. Run Grep to find patterns: SQL queries, eval(), innerHTML, passwords, tokens.
2. Read each flagged file in full context.
3. Classify each finding by severity: CRITICAL / HIGH / MEDIUM / LOW.

Output format:
- One table: Severity | File | Line | Issue | Recommendation
- Summary paragraph with the 3 most critical risks
- Do NOT rewrite code — only report.

Três prompts para usar no Claude Code agora: criar um agente via /agents, inspecionar um agente existente, e gerar um frontmatter sob medida para um papel específico.

Crie um subagente chamado "doc-writer" que escreve
documentação técnica em Markdown. Ele deve usar apenas
Read e Write, rodar em sonnet, e ter memória do projeto.
Escreva o frontmatter completo e um corpo de 5 linhas.

Leia o frontmatter de todos os arquivos .md em
.claude/agents/ e me diga: quais modelos estão sendo
usados, quais ferramentas cada agente tem, e se algum
agente tem description vaga que pode atrapalhar o match.

Quero um agente que otimize queries SQL pesadas.
Escreva o frontmatter completo incluindo: name kebab-case,
description com o gatilho "quando usar", tools mínimas,
model adequado ao tipo de análise, e color de destaque.
Depois explique cada campo escolhido e por quê.

É assim que o Claude Code exibe seus agentes após carregar os arquivos .md. A UI mostra o nome, a description resumida, as ferramentas e o modelo de cada agente. O campo color aparece como a bolinha colorida ao lado do nome.

↑ Recriação ilustrativa do painel /agents. O color aparece como bolinha; a description é truncada mas suficiente para o match semântico.