📋 The complete frontmatter

Imagine the frontmatter as the spec sheet of a collaborator: name, available tools, cognitive model, memory, and general behavior pattern. Claude Code reads frontmatter only to decide whether to call this agent — the full body is loaded only when the agent is actually invoked. Every field you omit becomes a default value; every field you fill in becomes a deliberate decision.

↑ Anatomy of a file .md: frontmatter (YAML) + body (Markdown). Claude Code reads the frontmatter to decide; the body defines the behavior.

The field name defines the unique identifier of your subagent. This is the name the conductor uses to call it — and the name that appears in the status line while the agent is running. Think of it as the professional nickname from the collaborator.

# 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 is the field more strategic from the frontmatter. It's the text the conductor reads to decide whether to call this agent. Think of it as the consulting room entrance sign: "cardiologist — chest pain, cardiac checkup". Without the right sign, the orchestrator walks through the door and doesn't know what's inside.

The field tools é a tool allowlist that the subagent can use. If you don't declare anything, it inherits all the orchestrator's tools — which may be too many. Restricting tools is a security and focus: a reviewer who only reads cannot accidentally write files.

The field model defines which language model will run the agent. This is the cost and quality decision: simple, repetitive tasks go to fast, inexpensive models; deep analysis goes to Opus. The topic of models by task is the Track 3 entire — here we learn the field syntax.

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)

Two fields that complete the basic configuration: color defines the visual highlight color from the agent in the UI, and memory defines which memory files it accesses—controlling what it "knows" before the task even begins.

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

While tools is an allowlist (only what's on it can be used), disallowed-tools is a explicit blocklist: "the agent can use everything except these". Use when you want to inherit most of the orchestrator's tools but specifically block one or two dangerous ones.

---
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
---

Beyond the basic fields, the frontmatter supports advanced settings for integrating MCP servers (Model Context Protocol) — which expand the available tools with external APIs, databases, services, and much more. These fields are optional and generally appear in production agents.

---
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://…"]
  }
}

One security-auditor.md of production using all the fields we've covered — with comments explaining each design decision. This is the reference point you can copy and adapt.

---
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.

Three prompts to use in Claude Code now: create an agent via /agents, inspect an existing agent and generate a custom frontmatter for a specific role.

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ê.

This is how Claude Code displays your agents after loading the files .md. The UI shows the name, a brief description, the tools e o model of each agent. The field color appears as the colored dot next to the name.

↑ Illustrative recreation of the panel /agents. O color appears as a dot; the description is truncated but sufficient for the semantic match.