Todo subagente bien construido sube la misma escalera: empieza con un rol claro, avanza por los pasos numerados y llega hasta un formato de salida que cualquier orquestador puede leer. Lo que distingue a un agente débil de un especialista confiable está en esta progresión.
🎭 Función: "you are a senior…"
La primera línea del cuerpo define el identidad del agente. No es vanidad: es una señal de especialización. El modelo ajusta el vocabulario, la profundidad y el tono según esa declaración. Una frase de rol bien escrita vale más que diez párrafos de instrucciones vagas.
Anatomía de una función efectiva
Un rol completo tiene tres partes: nivel (senior / staff / principal), dominio (ingeniero de seguridad / revisor de código / redactor técnico) y contexto operativo (trabajar en una base de código de producción / revisar PRs / escribir para desarrolladores).
✓ Papel efectivo
- ✓ "You are a senior security engineer reviewing production Python code for OWASP vulnerabilities."
- ✓ "You are a staff technical writer creating developer documentation for a REST API."
- ✓ Incluye un dominio específico + contexto de uso
✗ Papel débil
- ✗ "You are a helpful assistant." — demasiado genérico, sin ninguna señal del dominio
- ✗ "You are an expert." — sin especificar en qué
- ✗ Omitir el rol por completo
Consejo: prueba su función preguntando "¿qué vocabulario usaría un [tu rol]?" — si la respuesta cambia entre "asistente útil" e "ingeniero sénior de seguridad", el rol está haciendo un trabajo real.
🔢 Pasos numerados: "when invoked: 1…"
Después del rol vienen las pasos de ejecución — la secuencia exacta que el agente debe seguir cada vez que se lo activa. Los pasos numerados transforman el comportamiento emergente (impredecible) en un comportamiento reproducible.
¿Por qué numerar?
El modelo tiende a seguir listas numeradas con más fidelidad que párrafos de instrucciones. La numeración crea un contrato explícito de ejecución — saltarse un paso se vuelve visible para quien revisa el resultado.
📄 Formato de salida
El orquestador leerá lo que devuelva el subagente. Si el formato varía, el orquestador necesita lógica adicional para analizarlo. Un formato de salida declarado en el cuerpo del agente elimina esa variación y hace que la integración sea trivial.
Sección ## Output Format en el cuerpo
Declara el formato explícitamente en una sección separada del cuerpo. Usa Markdown para la estructura
y code fences para mostrar el esquema exacto esperado.
Respond with a Markdown document containing:
- **Resumen**: 1-2 oraciones
- **Findings**: lista numerada, cada uno con su nivel de gravedad (HIGH/MED/LOW)
- **Recomendación**: una solución práctica por hallazgo
No incluyas ninguna otra sección.
✓ Formato estructurado
- ✓ Sección dedicada
## Output Format - ✓ Campos con nombre y tipo (string, número, lista)
- ✓ Esquema JSON cuando el orquestador va a analizarlo automáticamente
✗ Formato libre
- ✗ Sin declaración de formato: la salida varía en cada invocación
- ✗ "Responda en prosa" para integraciones automatizadas
- ✗ Campos opcionales sin valor predeterminado declarado
Consejo: cuando el subagente vaya a devolver datos para que otro agente los procese, prefiere JSON a Markdown: es más fácil de analizar mediante programación. Usa Markdown cuando la salida sea para lectura humana directa.
🚫 Qué NO hacer
Declarar restricciones explícitas es tan importante como decir qué hacer. El modelo sabe más de lo que quieres que use; la sección de no hacer delimita el alcance y evita que el agente «ayude demasiado» fuera de su función.
Sección ## Constraints
Usa una sección ## Constraints o
## Do not para enumerar
comportamientos prohibidos. Cada restricción debe poder ponerse en práctica; no debe ser vaga.
- Do not fix code — only report findings
- Do not comment on style — enfócate solo en seguridad
- Do not escalate to the user — devolver los resultados al orquestador
- Do not hallucinate CVE numbers — di "sin verificar" si no estás seguro
⚠️ Las restricciones vacías no funcionan
"No hagas nada dañino" no es una restricción accionable: el modelo ya tiene guardrails para eso. Las restricciones útiles son específicas del dominio del agente: "no sugieras cambios arquitectónicos" (para un revisor de código), "no traduzcas el contenido" (para un verificador de calidad).
⚡ Un agente, una tarea
El mayor error en el cuerpo de un agente no es lo que está ahí, sino lo que está más. Los agentes que hacen varias cosas no hacen bien ninguna. La prueba es sencilla: si puedes poner un "y también" en el rol del agente, debe dividirse.
La prueba del "y también"
Review the code for bugs,
and also suggest improvements,
and also update the docs,
and also check security.
security-reviewer: comprobaciones de OWASP
doc-writer: actualizar la documentación
refactor-advisor: sugerir mejoras
Consejo práctico: cuando un agente tarda mucho, produce resultados grandes y difíciles de analizar, o se queda "confundido" entre modos de operación, es señal de que está intentando hacer demasiadas cosas. Divide en el punto del "y también".
🔧 El cuerpo invoca skills
Un subagente puede usar skills registradas en el sistema: las invoca por nombre, con un comando en el cuerpo. Esto permite que el agente delegue partes del trabajo en skills especializadas sin tener que volver a implementar comportamientos que ya existen.
Cómo declararlo en el cuerpo
1. Lee por completo los archivos de destino.
2. Use the `impeccable` skill to check prose quality.
3. Aplica los hallazgos al resultado.
4. Devuelve un resumen al estilo diff.
La instrucción de uso de la skill va en los pasos numerados, no en el rol. El rol define quién es el agente; los pasos definen qué usa.
✓ Delegación correcta
- ✓ Skill invocada en un paso específico y numerado
- ✓ Resultado de la skill integrado en el resultado final
- ✓ La skill hace una cosa; el agente orquesta el flujo
✗ Problemas comunes
- ✗ Invocar una skill sin usar el resultado (desperdicio de tokens)
- ✗ Llamar a una skill que hace exactamente lo mismo que el agente
- ✗ Invocar múltiples skills sin un criterio de orden
🔁 Iterar con feedback
El cuerpo de un agente no nace listo. La primera versión funciona el 70% del tiempo — el otro 30% revela lo que falta o lo que está mal. Iterar con comentarios reales es lo que separa un agente que «funciona a veces» de uno «confiable en producción».
Regla práctica: si tuviste que explicárselo al orquestador "el agente devolvió X, pero debes ignorar la parte Y", esto es una señal de que la corrección debería estar en el cuerpo del agente, no en la lógica del orquestador.
Ejemplo real: security-reviewer.md
Abajo tienes un subagente completo de revisión de seguridad. Cada sección muestra uno de los conceptos de este módulo aplicados en conjunto.
Por qué funciona este cuerpo
- → Papel específico: seniority + dominio + alcance (Python/TS, producción)
- → Pasos del checklist: 5 pasos que cubren todo el flujo sin ambigüedad
- → Formato declarado: 3 secciones con nombre y estructura exacta
- → Restricciones accionables: 5 prohibiciones específicas del dominio de seguridad
Contenido detallado
Úsalo cuando ya tienes un proceso documentado y quieres transformarlo en un agente.
Úsalo para revisar agentes que «casi funcionan» e identificar qué les falta.
Úsalo cuando un agente hace de todo, pero no hace nada bien.
Pantalla simulada: invocando al security-reviewer
El orquestador invocó al security-reviewer
en un archivo de autenticación. Mira cómo el cuerpo estructurado produce una salida consistente y parseable.
Ejercicio: dividir un agente que lo hace todo
Aplica lo que aprendiste en este módulo.
El agente problemático
Tu tarea
- 1 Lista todas las responsabilidades separadas de este agente (aplica la prueba del «y también»)
- 2 Propón 3 agentes especializados (nombre + una línea sobre el rol de cada uno)
- 3 Escribe el cuerpo completo de uno de los agentes: rol + pasos numerados + formato de salida + constraints
Criterio de finalización
- ✓ Identificaste ≥4 responsabilidades separadas en el agente original
- ✓ Cada agente propuesto pasa la prueba de «y también» — cero superposición de responsabilidades
- ✓ El cuerpo que escribiste tiene un rol específico (nivel + dominio + contexto)
- ✓ Los pasos numerados cubren el flujo completo sin «y también»
- ✓ El formato de salida está declarado y otro agente podría procesarlo
- ✓ Las restricciones son específicas del dominio — no genéricas