\
CONTEXT/academy
Lección 03 · ≈ 14 min

Crea un subagente custom

El fichero, el frontmatter (name, description, tools, model) y el system prompt.

Crea un subagente custom

Defines un subagente custom cuando te descubres lanzando una y otra vez el mismo tipo de trabajador con las mismas instrucciones. Vamos a crear un revisor de código — el artefacto del curso.

Un subagente es un fichero markdown

Vive en .claude/agents/<nombre>.md (proyecto, versionado) o ~/.claude/agents/<nombre>.md (personal). El frontmatter lo configura; el cuerpo es su system prompt.

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Revisa código por calidad, seguridad y mantenibilidad. Úsalo justo
  después de escribir o modificar código.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Eres un revisor de código senior. Cuando te deleguen una revisión:

1. Mira el diff (`git diff`) y los ficheros tocados.
2. Señala, por orden de gravedad: bugs, agujeros de seguridad, casos límite sin
   cubrir, y luego estilo.
3. Sé concreto: cita fichero y línea, propón el cambio.
4. No edites nada: solo revisas y reportas.

Los campos que importan

Solo name y description son obligatorios:

CampoPara qué
nameidentifica al subagente (también para invocarlo)
descriptionel disparador: cuándo Claude delega en él
toolsallowlist de tools que puede usar (aquí, solo lectura + Bash)
modelsonnet, haiku, opus o inherit (heredar el de la sesión)

Igual que en las skills, la description es lo que dispara la delegación. "Úsalo justo después de escribir o modificar código" le dice a Claude exactamente cuándo recurrir a él. Vaga = no se usa cuando esperas.

El cuerpo es clave: un subagente recibe solo ese system prompt (más detalles básicos del entorno), no el system prompt completo de Claude Code. Escríbelo como las instrucciones de un especialista.

La forma cómoda: /agents

No tienes que escribir el fichero a mano. El comando:

/agents

abre un gestor donde creas un subagente paso a paso (personal o de proyecto), eliges sus tools y su modelo, y lo guarda en la ruta correcta.

Pruébalo

Haz un cambio en tu repo y pídele a Claude algo que encaje con la description:

"Acabo de tocar el login, ¿me lo revisas?"

Claude debería delegar en code-reviewer, que revisa en su propia ventana y te devuelve el informe. Cuando te guste:

git add .claude/agents/code-reviewer.md && git commit -m "feat: add code-reviewer subagent"

Versionado, todo el equipo tiene el revisor. Ese es el artefacto.

Qué llevas hasta aquí

  • Un subagente es un .md en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal).
  • Frontmatter clave: name, description (disparador), tools, model; el cuerpo es su system prompt.
  • /agents te lo crea sin tocar el fichero.

En la siguiente lección, cómo se delega (automático vs explícito) y cómo acotar lo que puede hacer.

Fuente oficial: Subagents

¿Quieres llevar la cuenta de las lecciones que has terminado?

Entrar para guardar progreso