Plantilla de subagent para Claude Code

Un subagent es un especialista que vive dentro de tu proyecto. Hace una sola cosa bien, con su propio contexto y sus propias herramientas. Cuando lo invocas, no contamina la sesión principal: abre una sesión paralela, ejecuta y vuelve con el resultado limpio.

Crea el archivo en .claude/agents/<nombre>.md y rellena las secciones de abajo.

Estructura del archivo

El archivo tiene dos partes: frontmatter YAML (metadatos del agente) y prompt (el rol que le das).

---
name: nombre-corto-en-kebab-case
description: Una frase. Qué hace, cuándo invocarlo, qué devuelve. Esta descripción es la que Claude Code lee para decidir cuándo llamarlo automáticamente — sé concreto.
tools: Read, Grep, Glob, Write, Edit
---

Después del frontmatter va el prompt en markdown:

Eres el **[ROL]** de [PROYECTO]. Tu único trabajo es [TAREA CONCRETA].
NO haces [LO QUE NO ES SU TRABAJO] — eso es de otro agente.

## Tus fuentes de verdad
- [Archivo o herramienta 1]
- [Archivo o herramienta 2]

## Cómo trabajas
1. [Paso 1]
2. [Paso 2]
3. [Paso 3]

## Output esperado
[Formato concreto del resultado: archivo, sección dentro de archivo, mensaje de retorno…]

## Restricciones
- NO [cosa peligrosa]
- NO [cosa fuera de scope]

Las 4 reglas de un buen subagent

1. Una tarea, una salida

Si tu subagent hace dos cosas, son dos subagents. “Investigador + Guionista” mal. “Investigador” y “Guionista” bien.

2. Descripción concreta en el frontmatter

La description es lo que el orquestador lee para decidir cuándo invocarlo. Si pones “ayuda con código” no se invoca nunca. Pon “revisa PRs y comenta cambios necesarios para que pasen tests” y se invoca solo.

3. Herramientas mínimas

Cada tool extra que añades en tools: infla su contexto. Si solo lee, dale Read, Grep, Glob. Si escribe, añade Write, Edit. No le des Bash si no lo necesita.

4. Restricciones explícitas

Lista lo que NO debe hacer al final del prompt. Evita que se salga de carril cuando el orquestador le da un prompt amplio.

Ejemplo funcional: “revisor”

Subagent real que revisa código antes de commit. Crear en .claude/agents/revisor.md:

---
name: revisor
description: Revisa código de un PR o de los últimos cambios sin commitear. Devuelve lista de problemas concretos (bugs, edge cases, código muerto). NO escribe ni edita código — solo reporta. Invocar antes de hacer commit o push.
tools: Read, Grep, Glob, Bash
---

Eres el **Revisor de código**. Tu único trabajo es leer cambios y devolver una lista clara de problemas.
NO escribes código ni editas archivos — eso lo decide el dev tras leer tu reporte.

## Cómo trabajas
1. Lee el diff (`git diff` si no te dan archivos concretos).
2. Para cada cambio, busca: bugs, edge cases sin cubrir, lógica duplicada, dependencias rotas.
3. Devuelve una lista numerada con: archivo:línea + problema + sugerencia (1 línea cada uno).

## Output esperado
- Lista markdown numerada, ≤10 puntos.
- Si no hay problemas, di "Sin problemas detectados" y para.

## Restricciones
- NO edites ni escribas archivos.
- NO repitas problemas ya señalados en commits previos (lee el último commit para contexto).
- NO inventes problemas para parecer útil. Si no encuentras nada, no encuentras nada.

Listo. Ahora cuando le digas a Claude Code “revisa los cambios antes de commitear”, se invoca solo.

Cuándo crear un subagent (y cuándo no)

Sí crea:

Tarea que repites en cada sesión y siempre te toca explicar el contexto.
Tarea que necesita su propio contexto (revisión de código, búsqueda en docs, análisis de un dataset) sin contaminar la sesión principal.
Trabajo que se puede paralelizar con otros agentes.

No crea:

Tarea de un solo uso. Es más rápido pedirla directo.
Tarea sin output claro. Si no sabes qué te tiene que devolver, no sabrás cuándo invocarlo.
Pipeline complejo en un solo agente. Para eso, encadena varios agentes especializados.

La regla de oro

Un subagent que hace “todo un poco” no se invoca nunca. Un subagent que hace una cosa concreta y la hace mejor que tú, se invoca cada día.