📋 El frontmatter completo

Imagina el frontmatter como la ficha técnica de un colaborador: nombre, herramientas disponibles, modelo cognitivo, memoria y patrón general de comportamiento. Claude Code lee solo el frontmatter para decidir si debe llamar a este agente; el cuerpo completo solo se carga cuando el agente se invoca de verdad. Cada campo que omites se convierte en un valor predeterminado; cada campo que completas se convierte en una decisión deliberada.

↑ Anatomía de un archivo .md: frontmatter (YAML) + cuerpo (Markdown). Claude Code lee el frontmatter para decidir; el cuerpo define el comportamiento.

El campo name define el identificador único de tu subagente. Así lo llama el director, y es el nombre que aparece en la línea de estado mientras el agente está en ejecución. Piénsalo como el seudónimo profesional del 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 es el campo más estratégico del frontmatter. Es el texto que el director lee para decidir si debe llamar a este agente o no. Piénsalo como la placa de entrada del consultorio: "cardiólogo — dolores en el pecho, chequeo cardíaco". Sin la señal correcta, el maestro cruza la puerta y no sabe qué hay adentro.

El campo tools é a lista blanca de herramientas que puede usar el subagente. Si no declaras nada, hereda todas las herramientas del maestro — lo que puede ser demasiado. Restringir herramientas es una decisión de seguridad y enfoque: un revisor que solo lee no puede escribir archivos accidentalmente.

El campo model define qué modelo de lenguaje ejecutará el agente. Esta es la decisión de costo y calidad: las tareas simples y repetitivas van a modelos rápidos y baratos; los análisis profundos van a Opus. El tema de los modelos por tarea es la Ruta 3 completa — aquí aprendemos la sintaxis del 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)

Dos campos que completan la configuración básica: color define la color de realce visual del agente en la UI, y memory define a qué archivos de memoria accede — controlando lo que «sabe» incluso antes de que empiece la tarea.

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

Mientras tools es una lista blanca (solo se puede usar lo que aparece en ella), disallowed-tools es una lista negra explícita: "el agente puede usar todo, excepto esto". Úsalo cuando quieras heredar la mayoría de las herramientas del maestro, pero bloquear específicamente una o dos que sean peligrosas.

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

Además de los campos básicos, el frontmatter admite configuraciones avanzadas para integrar servidores MCP (Model Context Protocol), que amplían las herramientas disponibles con APIs externas, bases de datos, servicios y mucho más. Estos campos son opcionales y generalmente aparecen en agentes de producción.

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

Uno security-auditor.md de producción usando todos los campos que vimos — con comentarios que explican cada decisión de diseño. Este es el punto de referencia que puedes copiar y 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.

Tres prompts para usar ahora en Claude Code: crear un agente mediante /agents, inspeccionar un agente existente y generar un frontmatter a medida para un rol 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ê.

Así es como Claude Code muestra sus agentes después de cargar los archivos .md. La UI muestra el nombre, a description resumida, las herramientas e o modelo de cada agente. El campo color aparece como el punto de color junto al nombre.

↑ Recreación ilustrativa del panel /agents. O color aparece como un punto; la descripción se trunca, pero basta para la coincidencia semántica.