Qué es un agente está en Conceptos básicos; cómo se lanza un subagente y dónde se guarda, en OpenCode y Claude Code. Aquí, cómo se escribe uno propio.

En este curso los agentes aparecen de dos formas:

• El agente principal: el que habla contigo. En OpenCode, Plan y Build; en Claude Code, la propia sesión.
• Los subagentes: agentes especializados que el principal lanza para un trozo del trabajo, cada uno con su propia ventana de contexto, sus herramientas y sus instrucciones. Esa ventana propia es la razón de fondo para usarlos, más que el paralelismo: es lo que permite abarcar un problema que no cabría en una sola conversación (patrón orquestador).

El agente organiza el trabajo: quién lo hace, con qué herramientas, en qué orden y cuándo para. El conocimiento no va en el agente: va en las skills. Así que un agente no lleva ejemplos ni convenciones del proyecto; dice qué skill cargar. La tabla completa de qué va en cada uno está en Skills.

✅ Antes de revisar, carga la skill servicios.
❌ Los servicios lanzan ErrorDeNegocio, nunca IllegalStateException... (conocimiento: va en la skill)

Un agente es un solo fichero .md: frontmatter con la configuración y, debajo, sus instrucciones.

---
name: verificador-tests
description: Comprueba que cada requisito de una spec tiene un test que lo cita y
  que pasa. Usar después de implementar una funcionalidad, antes del commit.
tools: Read, Grep, Bash
model: haiku
skills:
  - requisitos
---

# Verificador de tests

Comprueba que cada requisito de la spec está cubierto por un test que pasa.

## Rol
Eres un verificador. No arreglas nada: solo dices qué falta.
No te fíes del resumen de quien implementó: comprueba en el código.

## Entradas
Te llegan en el prompt:
- `spec`: ruta del fichero de requisitos.
- `modulo`: módulo Maven donde están los tests.

## Proceso
1. Saca los identificadores de la spec (`R-1`, `R-2`...).
2. Busca en `src/test` el test que cita cada uno.
3. Ejecuta `./mvnw -pl <modulo> test`.

## Criterios
- OK: todos los requisitos tienen un test que lo cita y todos pasan.
- Fallo: un requisito sin test o un test que falla.
- En la duda: fallo.

## Salida
Primera línea, exactamente `DONE` o `BLOCKED`.
Si es `BLOCKED`, una línea por problema: `R-12: sin test`.

• name y description: igual que en una skill, la descripción dice qué hace y cuándo usarlo: es lo que lee el principal para decidir si lo lanza (cómo se escribe).
• tools: las herramientas que puede usar. Si no se pone, las tiene todas: un revisor que puede editar acaba arreglando en vez de revisar.
• model: haiku, sonnet, opus o inherit. Si no se pone, el del principal. Lo mecánico (verificar, contar, comprobar un formato) con haiku: el principal no lo baja solo y gasta el caro. Lo que juzga, diseña o corrige, con el del principal.
• skills: las skills que se cargan enteras al arrancar. Es como el agente recibe el conocimiento sin llevarlo dentro.

Siempre las mismas secciones, en este orden:

• Rol: quién es y qué sesgo evita. Un revisor que no se fía del resumen de quien implementó.
• Entradas: lo que le llega en el prompt, con nombre.
• Proceso: pasos numerados, un verbo cada uno.
• Criterios: cuándo está bien, cuándo mal y qué hace en la duda: fallar.
• Salida: formato cerrado, con las palabras exactas (DONE / BLOCKED). El principal compara por texto: «indícalo de alguna forma» no se puede comparar.

Un agente que reparte el trabajo entre subagentes lo dice con números y con el orden:

• En paralelo: cuántos exactamente y que se lancen en una sola respuesta. «Lanza 3 subagentes en paralelo, uno por módulo».
• En serie si alguno puede necesitar preguntarte algo: dos preguntas a la vez no se pueden contestar.
• Los que van en paralelo no preguntan: devuelven sus dudas en la respuesta y el principal te las hace.
• Vuelven con poco: el estado y un resumen corto, o la ruta del fichero que han escrito. El contenido entero llenaría la ventana del principal, que es justo lo que se quería evitar.

En Claude Code un subagente puede lanzar a su vez otros subagentes, hasta tres niveles por debajo del principal.

Un agente sin límite da vueltas hasta gastar el plan. Siempre:

• Un criterio de terminado comprobable: los tests pasan, no «cuando esté bien» (ingeniería de bucles).
• Un límite de vueltas: «máximo 3 intentos de corrección; después, para y di qué falta».
• Cuándo parar y preguntar: «si la spec no dice qué hacer con un pedido ya enviado, para y pregunta».

Un agente también ejecuta scripts para lo determinista. Como no tiene carpeta, los scripts viven en el scripts/ de una skill y el agente los ejecuta con el comando exacto. Cómo se escriben y se citan: scripts.

Como subagente se lanza igual que los que trae la herramienta: Claude Code, OpenCode. Un agente que coordina a otros también se puede usar como agente principal, para que toda la sesión siga su rol:

• En Claude Code:

claude --agent orquestador

• En OpenCode, con mode: primary en el frontmatter: aparece junto a Plan y Build y se cambia a él con Tab.

• Claude Code: subagents: todos los campos del frontmatter, skills y los subagentes anidados.
• OpenCode: agents: agentes principales y subagentes, mode y permission.
• MCP vs Skills vs Agents With Scripts: Which One Should You Pick?