Anatomía de un subagente

Cada vez que el maestro activa un subagente, está leyendo un archivo .md. Este archivo tiene dos zonas obligatorias: o frontmatter (entre los tres rasgos ---) e o cuerpo (todo lo demás). La primera zona configura al agente — indica el nombre, el disparador, las herramientas y el modelo. La segunda zona es el cerebro — indica quién es y qué hace. Juntas, estas dos partes forman el subagente completo.

↑ La ecuación del subagente: frontmatter (configuración) + cuerpo (cerebro) = agente completo.

Contenido detallado

📄 El archivo .md es el subagente

Si ya trabajaste con skills en Claude Code, ya viste la estructura: un archivo Markdown con frontmatter al principio. Un subagente es exactamente eso: un .md con un frontmatter de configuración y un cuerpo de instrucciones. No es binario, no es código compilado, no es un plugin. Es un archivo de texto que cualquier editor puede abrir.

🔑 Por qué esto importa

Cuando el archivo es texto simple, obtienes tres cosas gratis:

•Legibilidad — lees, entiendes y editas sin una herramienta especial.
•Control de versiones — va a git junto con el proyecto. El diff funciona.
•Portabilidad — copia la carpeta .claude/agents/ a otro proyecto y el agente irá contigo.

📋 Skill (.claude/skills/)

Invocada con /skill-name · mismo modelo y herramientas del chat · misma ventana de contexto.

🤖 Subagente (.claude/agents/)

Se activa mediante la description · ventana propia · modelo y tools distintos · devuelve solo el informe.

Qué es:

Un archivo Markdown con frontmatter + cuerpo. La analogía con skill.md es intencional — misma estructura, propósito diferente.

Por qué aprender:

Desmitifica el subagente. No hay nada oculto: todo lo que el maestro sabe sobre el agente está en este archivo.

Conceptos clave:

Archivo .md · frontmatter YAML · cuerpo Markdown · versionable en git · portable entre proyectos.

⚙️ Frontmatter (configuración) × cuerpo (cerebro)

Las dos zonas tienen responsabilidades completamente diferentes. El frontmatter lo lee Claude Code para decidir si activa el agente y como va a ejecutarse. El cuerpo es el prompt que se envía al modelo cuando se lo activa: literalmente es el «sistema» de ese agente. Confundir las dos zonas es el error más común al crear el primer subagente.

.claude/agents/code-reviewer.md Markdown

⚙️ FRONTMATTER — configuración

---

name: code-reviewer

description: Revisa el diff actual en busca de errores y

fallas de seguridad. Úsalo después de cualquier cambio de código.

tools: Read, Grep, Glob

model: claude-sonnet-4-5

---

🧠 CUERPO — cerebro (prompt)

You are a senior code reviewer.

When invoked:

1. Ejecuta git diff to see what changed.

2. Lee los archivos modificados y entiende la intención.

3. Revisa la corrección, la seguridad y las pruebas faltantes.

Flag: errores, vulnerabilidades de seguridad y pruebas faltantes.

Be concise. Do not rewrite the code — only report.

↑ Recreación ilustrativa: las dos zonas del archivo .md de un subagente

⚙️ Frontmatter — qué hace

✓Define el identificador del agente (name)
✓Describe cuándo debe usarlo el maestro (description)
✓Enumera las herramientas permitidas (tools)
✓Elige el modelo que se ejecutará (model)

🧠 Cuerpo — qué hace

✓Define el rol del agente ("You are a...")
✓Describe los pasos de ejecución
✓Especifica el formato de salida
✓Enumera lo que el agente NO debe hacer

Qué es: la división en dos responsabilidades: configuración del runtime (frontmatter) y prompt del modelo (cuerpo).

Por qué aprender: sin esta distinción, colocas las instrucciones en el lugar equivocado: intentas configurar tools en el cuerpo o describes el rol en el frontmatter.

Conceptos clave: frontmatter YAML entre --- · cuerpo Markdown libre · se leen en momentos distintos · propósitos no intercambiables.

🔑 Los 4 campos clave del frontmatter

El frontmatter admite muchos campos, pero hay cuatro que vas a escribir en cada subagente. Los demás — color, memory, disallowed-tools — son opcionales y se cubren en la Trilha 2. Por ahora, domina estos cuatro.

`name` — identificador

Minúsculas + guiones, sin espacios. Aparece en los logs y en FleetView. Usa nombres descriptivos: code-reviewer > cr.

`description` — activador

El maestro lee este campo para decidir cuándo activar el agente. Description vaga = el agente nunca se activa. Toda la Trilha 2 está dedicada a escribir buenas descriptions.

`tools` — permisos

Principio del mínimo privilegio: agente lector → Read, Grep, Glob. Agente editor → agrega Edit, Write. No lo omitas: si no lo declaras, hereda todo del director de orquesta.

`model` — quién ejecuta

Mecánico → haiku. Análisis → sonnet. Razonamiento estratégico → opus. Elegir con intención aquí ahorra costo y tiempo. La Trilha 3 profundiza en el tema.

💡 Todos los campos disponibles

Además de los cuatro anteriores, el frontmatter admite: color (color en FleetView), memory (project/user/local/none), disallowed-tools (bloqueo explícito) y campos avanzados de MCP. La documentación oficial los enumera todos: enlace en el tema 6 de este módulo.

Qué es: los cuatro campos que todo subagente necesita: name, description, tools, model.

Por qué aprender: sin los cuatro, el agente no se activa, usa demasiadas herramientas o se ejecuta con el modelo equivocado.

Conceptos clave: name (id) · description (activador) · tools (mínimo privilegio) · model (costo × calidad).

🧠 El cuerpo: las cuatro secciones del cerebro

El cuerpo es Markdown libre: puedes escribir lo que quieras. Pero hay cuatro elementos que casi siempre tiene un cuerpo bien estructurado. Piensa en ellos como las secciones de un briefing para un empleado nuevo: quién eres, qué hacer, qué entregar e qué nunca hacer.

👤

Papel (Rol)

La primera línea del cuerpo. Define la identidad del agente.

You are a senior code reviewer
focused on security.

📋

Pasos (Steps)

Qué hacer cuando se active, paso a paso.

When invoked:
1. Ejecuta git diff.
2. Lee los archivos modificados.
3. Busca errores.

📤

Salida (Output)

Formato y contenido de lo que vuelve al maestro.

Report: a bullet list of
issues. Include file path
and line number.

🚫

Acciones prohibidas (Limits)

Límites explícitos: lo que el agente no hace.

De not rewrite code.
De not open new files
beyond the diff.

✓ Cuerpo bien estructurado

✓Empieza con «You are a...» — función clara
✓Pasos numerados, sin ambigüedad
✓Instrucción explícita de formato de salida (viñetas, JSON, prosa)
✓Al menos un «Do not...» para limitar el alcance

✗ Cuerpo débil

✗Sin un rol, el modelo improvisa su identidad
✗Pasos vagos: "analiza el código"
✗Sin instrucciones de salida, el maestro no sabe qué esperar
✗Sin límites: el agente edita cuando solo debería leer

Qué es: el cuerpo como una descripción de cuatro secciones: rol, pasos, salida y límites.

Por qué aprender: un cuerpo incompleto produce agentes impredecibles — que hacen más (o menos) de lo que esperabas.

Conceptos clave: role · steps · output format · limits · Markdown libre.

📁 Dónde vive: .claude/agents — el puente a la Ruta 2

Claude Code busca subagentes en .claude/agents/ en la raíz del proyecto. Es una carpeta oculta, igual que .claude/skills/ que ya conoces. Cualquier .md guardado allí, se carga automáticamente como subagente disponible — sin reiniciar, sin comando de registro.

estructura de carpetas proyecto

seu-projeto/
├── .claude/
│   ├── agents/               # subagentes do projeto
│   │   ├── code-reviewer.md   # ← aqui!
│   │   ├── test-writer.md
│   │   └── doc-writer.md
│   ├── skills/               # skills (diferente!)
│   └── CLAUDE.md             # instruções do projeto
└── src/
    └── …

🗂️ Proyecto — `.claude/agents/`

Solo en este proyecto · va en git · compartido con el equipo.

🌐 Global — `~/.claude/agents/`

Todos los proyectos · directorio principal del usuario · agentes personales.

🔭 Puente a la Trilha 2: En la Ruta 2 tú crea estos archivos — frontmatter completo, cuerpo real y el comando /agents para gestionar el catálogo.

Qué es: la carpeta .claude/agents/ como punto de montaje de los subagentes de un proyecto.

Por qué aprender: saber dónde guardar es el primer paso para crear. Sin la ruta correcta, el agente no aparece.

Conceptos clave: .claude/agents/ · alcance de proyecto frente a global · carga automática · versionable.

📚 Documentación oficial — todos los campos

El frontmatter admite más campos además de los cuatro esenciales. La referencia de abajo cubre los más usados.

📖 Campos del frontmatter — referencia rápida

Campo	¿Obligatorio?	Para qué sirve
name	✓ sí	Identificador único: minúsculas y guiones
description	✓ sí	Disparador: cuándo el maestro activa este agente
tools	recomendado	Herramientas permitidas (lista separada por comas)
model	recomendado	Modelo de Claude que ejecuta (haiku / sonnet / opus)
color	opcional	Color de la insignia en FleetView
memory	opcional	Acceso a la memoria: project / user / local / none
disallowed-tools	opcional	Bloquea herramientas específicas de forma explícita

Documentación completa: use /help agents en Claude Code (sin conexión) o docs.anthropic.com/claude/code/agents. Campos avanzados como memory e disallowed-tools desbloquean comportamientos adicionales cubiertos en la Ruta 3+.

Qué es: referencia de todos los campos — obligatorios y opcionales.

Por qué aprender: saber dónde encontrar campos avanzados ahorra ensayo y error al crear agentes más sofisticados.

Conceptos clave: campos obligatorios × opcionales · /help agents · docs.anthropic.com/claude/code/agents.

📄

Ejemplo .md totalmente anotado

Lee este doc-writer.md con atención a las anotaciones en comentarios. Cada línea está etiquetada con la sección a la que pertenece y la razón por la que está allí.

.claude/agents/doc-writer.md ejemplo anotado

--- ← delimitador de abertura do frontmatter

name: doc-writer
  ↑ identificador — minúsculas, hífens, sem acento

description: Escreve documentação técnica e READMEs
  a partir de código existente. Use quando o usuário
  pedir para documentar um módulo, função ou projeto.
  ↑ gatilho — 3 frases: o que faz, quando usar, sinal

tools: Read, Glob, Write
  ↑ menor privilégio — lê código, escreve .md, sem Bash

model: claude-sonnet-4-5
  ↑ sonnet: boa escrita, custo razoável. Haiku bastaria?
     Não — qualidade de prosa importa aqui.

--- ← delimitador de fechamento do frontmatter

# corpo (tudo aqui é o prompt enviado ao modelo)

You are a technical documentation writer.
  ↑ papel — identidade do agente (primeira coisa!)

When invoked:
1. Read the files listed in the task.
2. Identify the public interface (exports, classes, functions).
3. Write a clear README.md at the module root.
  ↑ passos — numerados, ação concreta em cada um

Output: a single README.md file with:
  - One-sentence summary
  - Installation (if applicable)
  - Usage examples in code blocks
  - API reference table
  ↑ saída — formato explícito; o maestro sabe o que esperar

Do not invent behavior that isn't in the source code.
Do not modify source files — only create/update .md files.
  ↑ limites — dois "do not" que previnem alucinação e dano

⌨️

Prompts listos (copia y pega)

Tres prompts para explorar la anatomía de un subagente que ya tienes, o para inspeccionar lo que sabe el maestro.

Prompt 1 — inspeccionar un agente existente entender cada campo

Abra o arquivo .claude/agents/code-reviewer.md e
me explique cada campo do frontmatter — o que faz,
por que está com esse valor e o que mudaria se eu
trocasse. Depois leia o corpo e identifique o papel,
os passos, a saída esperada e os limites.

Prompt 2 — listar todos los agentes disponibles ver el catálogo

Liste todos os subagentes disponíveis em
.claude/agents/ e para cada um me mostre:
- o campo name e description
- as tools permitidas
- o modelo configurado
Formato: tabela markdown.

Prompt 3 — diagnosticar un agente que nunca se activa depurar description

Leia o arquivo .claude/agents/meu-agente.md.
O maestro nunca aciona este agente. Analise a
description: ela é específica o suficiente?
Tem as palavras-gatilho certas? Sugira 3 versões
melhoradas da description, do mais genérico
ao mais específico.

🎯

Ejercicio — Etiqueta las partes

Abajo hay un archivo .md de subagente con 8 líneas numeradas. Para cada línea, identifica: (a) en qué zona está (frontmatter o cuerpo), (b) qué campo o sección del cuerpo representa.

L1---

L2name: escritor de pruebas

L3description: Escribe pruebas unitarias para funciones de Python.

L4tools: Read, Write, Bash

L5model: claude-haiku-4-5

L6---

L7You are a Python test engineer.

L8When invoked, read the target file and write pytest tests.

✅ Criterio — acertaste si, para cada línea, dijiste:

→Zona: frontmatter (L1–L6) o cuerpo (L7–L8).
→Campo/sección: delimitador, name, description, tools, model, rol o pasos.
→Impacto: qué se rompe si desaparece esta línea.

Bono: qué herramienta de L4 es la más riesgosa y por qué Bash requiere cuidado.

Respuestas

L1,L6 → delimitadores · sin ellos, el YAML no se puede parsear

L2 → frontmatter · name · sin él, el agente pierde su id

L3 → frontmatter · description (disparador de activación)

L4 → frontmatter · tools · Bash = ejecución libre = mayor riesgo

L5 → frontmatter · model · haiku = rápido y económico

L7 → cuerpo · rol · identidad del modelo (va primero)

L8 → cuerpo · pasos · instrucción de ejecución

✅ Resumen del módulo

✓

El .md es el subagente — archivo de texto, versionable y portable. La misma estructura de skill.md, pero con otro propósito.

✓

Dos zonas — frontmatter (configuración, leído por el runtime) y cuerpo (prompt, enviado al modelo).

✓

4 campos del frontmatter — name (id), description (activador), tools (menor privilegio), model (costo × calidad).

✓

4 secciones del cuerpo — rol, pasos, salida y límites. Un cuerpo sin límites produce agentes que hacen más de lo que deberían.

✓

Dónde vive — .claude/agents/ en el proyecto (o ~/.claude/agents/ a nivel global). Carga automática.

✓

Documentación oficial — /help agents para consultar la referencia local; docs.anthropic.com para ver la lista completa de campos.

Próximo — Ruta 2:

Ruta 1 completa. En la Ruta 2 crea en la práctica: frontmatter completo (todos los campos), la description como activador, herramientas y permisos, y el comando /agents para gestionar tu catálogo.

← Módulo anterior Ruta 2: En la práctica →