Mapa de la ruta
🎯 Qué es un subagente
Delegas, él trabaja
🧹 El verdadero motivo
Contexto limpio, no velocidad
⚖️ Agente × Subagente × Skill
Las tres primitivas
🔀 Built-in × Custom
Listos vs. los que tú creas
🤔 La pregunta que decide
¿Nunca lo voy a volver a leer? Delégalo
🧬 Anatomía de un subagente
Config + cerebro en un .md
Contenido detallado
🎯 Qué es un subagente
Un especialista al que delegas. El chat es el director; el subagente trabaja en su propia ventana y devuelve un informe limpio.
Tu chat principal es el director: entiende la solicitud y decide delegar. El subagente es el músico especialista que ejecuta una parte.
Sin esta separación de funciones, intentas hacerlo todo en una sola conversación y pierdes el control de lo que está ocurriendo.
Maestro = orquesta y decide; subagente = ejecuta una tarea e informa.
El subagente recibe la tarea, abre su propia ventana de contexto, trabaja y devuelve solo el resultado al director.
Este ciclo es lo que mantiene tu conversación concisa: el trabajo pesado se queda en la ventana del subagente.
Ventana propia = aislamiento; informe = solo vuelve lo esencial.
Cinco subagentes distintos pueden ejecutarse en paralelo, cada uno con su función, y devolver cinco resúmenes al agente coordinador.
Visualizar la flota ayuda a entender el beneficio: varios frentes al mismo tiempo, sin mezclar contextos.
Paralelismo = N ventanas independientes; cada persona = un especialista.
El subagente no conversa contigo turno a turno. Recibe una tarea, la ejecuta y desaparece — no es un segundo chat.
Esperar un diálogo con el subagente es el error mental más común. Saber lo que NO es evita la frustración.
Sin ida y vuelta; sin memoria de tu conversación; tarea única.
Cada subagente habla solo con el maestro que lo llamó. Los subagentes no conversan entre sí.
Define qué se puede y qué no se puede orquestar, y por qué la coordinación siempre está a cargo del director de orquesta.
Topología en estrella; el maestro es el único punto de unión.
Claude Code ya viene con subagentes listos (como general-purpose). Puedes invocar uno sin crear nada.
Experimentar antes de teorizar fija el concepto: ves cómo el informe vuelve limpio en la práctica.
Built-in = listo para usar; delegar es pedir «abre un subagente para…».
🧹 El verdadero motivo: contexto limpio
La razón número 1 no es la velocidad, sino proteger la ventana de contexto. Todo lo que lees permanece durante toda la sesión; delegar la mantiene limpia.
La ventana de contexto es la memoria de trabajo de la sesión. La status line muestra cuántos tokens y qué porcentaje ya usaste.
Quien entiende la ventana entiende por qué delegar. Es un recurso finito que gastas con cada archivo que lees.
Contexto = recurso limitado; %/tokens = tu presupuesto.
Todo lo que lees en la conversación principal — logs, archivos enormes, salidas — queda ahí ocupando espacio hasta el final de la sesión.
El contexto contaminado degrada las respuestas siguientes. Reconocer la contaminación es el primer paso para evitarla.
La lectura = costo permanente; el ruido acumulado empeora el enfoque.
Leer 300 páginas en la conversación principal frente a pedirle a un subagente que las lea y te traiga solo los 3 datos que importan.
Es la decisión central del curso. Interiorizar este intercambio cambia tu forma de trabajar en el día a día.
Tú = contexto sucio; subagente = contexto preservado.
El subagente hace el trabajo pesado en su ventana y devuelve un resumen destilado — no la pila en bruto.
Es lo que entra en tu conversación. Un buen resumen es el producto del subagente; tú solo ves lo esencial.
Destilación; el informe es la interfaz entre las dos ventanas.
Mucha gente cree que los subagentes sirven para ir más rápido. El principal beneficio es preservar el contexto.
Apuntar al motivo correcto hace que uses subagentes en las situaciones adecuadas, no solo «para ir más rápido».
Contexto > velocidad; la velocidad es una ventaja, no el objetivo.
Una investigación de producto sobre documentación enorme: el subagente lo lee todo y vuelve con los 3 puntos decisivos.
Un número concreto fija mejor la idea que la teoría: cientos de páginas costarían la mitad de tu ventana.
Relación de compresión; el resumen cabe donde la fuente sin procesar no cabría.
⚖️ Agente × Subagente × Skill
La comparación central del curso. Contexto propio vs. compartido, paralelismo, modelo propio y quién llama a quién.
Agente = el asistente principal; subagente = especialista delegado en una ventana propia; skill = instrucción/capacidad cargada en el contexto actual.
Confundir las tres lleva a usar la herramienta equivocada. Una frase clara sobre cada una lo resuelve todo.
Tres primitivas, tres funciones; no son sinónimos.
El subagente tiene una ventana propia y aislada; la skill se ejecuta dentro del contexto compartido del agente actual.
Es el eje que más los diferencia: una skill ensucia tu contexto; un subagente lo protege.
Aislamiento (subagente) frente a ejecución local (skill).
Puedes ejecutar varios subagentes en paralelo; una skill se ejecuta dentro del flujo secuencial del agente.
Cuando necesitas N frentes al mismo tiempo, solo el subagente te lo permite.
En paralelo = subagente; en línea = skill.
Un subagente puede ejecutarse con un modelo distinto al del maestro; una skill usa el modelo del agente que la cargó.
Es la base del ahorro: un subagente en Haiku económico mientras el jefe se queda en Opus.
Modelo por agente; la skill hereda el modelo actual.
Las skills y los agentes se llaman entre sí, pero un agente no invoca a otro agente: la coordinación siempre vuelve al director de orquesta.
Define los límites de la orquestación. Intentar que un agente llame a otro rompe el modelo.
skill ↔ agent OK; agent → agent NO.
Una tabla dinámica que cruza contexto, paralelismo, modelo e invocación para señalar la primitiva adecuada para cada escenario.
Es el entregable que consultarás siempre. Memoriza los ejes, no las celdas.
Decisiones por ejes; la tabla es la columna vertebral de la Trilha 1.
🔀 Built-in × Custom
Los subagentes listos para usar (Explore, Plan, general-purpose) frente a los que creas. Y el truco de la divulgación progresiva.
Claude Code ya incluye subagentes de fábrica: Explore (búsqueda), Plan (arquitectura), general-purpose (multiuso) y el propio claude.
Antes de crear cualquier cosa, ya tienes herramientas poderosas. Saber cuáles existen evita reinventar.
Built-in = listo; cubre búsquedas, planificación y tareas generales.
Darle una persona a general-purpose en un prompt no crea un subagente personalizado: es solo una instrucción temporal.
Es una confusión común. Un custom de verdad es un archivo persistente, reutilizable y que se activa solo.
Persona ad hoc ≠ agente guardado; custom = archivo.
Un subagente personalizado es un archivo Markdown con frontmatter + cuerpo. Vive en el disco y siempre está disponible.
Es el puente a la Ruta 2. Entender que «es solo un .md» le quita el misterio a la creación.
.md = subagente; frontmatter (configuración) + cuerpo (cerebro).
Claude solo lee el name y la description de cada agente hasta decidir usar uno. El cuerpo completo se incluye solo cuando se invoca al agente.
Explica por qué la description es tan importante y por qué tener muchos agentes no ocupa mucho espacio en el contexto.
Revelación progresiva; solo carga el detalle cuando lo necesitas.
Como solo name+description permanecen cargados, puedes tener decenas de agentes sin inflar el contexto.
Quita el miedo a «tener demasiados agentes». El catálogo es ligero por diseño.
Costo del catálogo ≈ solo metadatos; contenido bajo demanda.
El comando /agents enumera los subagentes disponibles (built-in y custom) y abre el asistente de creación.
Es la puerta de entrada práctica. Antes de crear, mira qué hay ya con un comando.
/agents = listar + crear; punto de partida de la T2.
🤔 La pregunta que decide
"¿Esto va a volcar cosas que nunca voy a volver a leer?" Las señales para usarlo, las señales para evitarlo y la regla de los 10+ archivos.
Una sola pregunta resuelve la mayoría de los casos: «¿esto va a generar un montón de resultados que nunca volveré a leer?». Si es así, delega.
Es la heurística que te evita memorizar listas. Una frase a mano vale por diez reglas.
Criterio: reutilización futura del resultado; «basura de lectura» → subagente.
Muchos archivos, una pared de output, tareas repetidas, trabajos independientes en paralelo o la necesidad de un revisor imparcial.
Reconocer rápidamente la señal verde hace que delegues en el momento adecuado, sin dudar.
Volumen, ruido, repetición, paralelismo, imparcialidad.
Edición rápida, pasos dependientes, agentes que tendrían que hablar entre sí, cuando necesitas toda la conversación o que te hagan una pregunta.
Forzar un subagente donde no corresponde genera retrabajo. La señal de alerta ahorra tiempo.
Rapidez, dependencia, diálogo, contexto personal.
Regla práctica: 10+ archivos para revisar o un output que nunca vas a volver a leer = subagente.
Un número hace objetiva la decisión cuando la intuición vacila.
Umbral de 10 archivos; una pared de output es el detonante.
Cuando el trabajo exige decenas o cientos de subagentes, pasas a un flujo de trabajo dinámico que orquesta la flota.
Marca el límite entre «un subagente» y «una operación a escala»; el tema se profundiza en la Ruta 3.
La escala cambia la herramienta; ten cuidado con el costo.
Para algo rápido, es mejor hacerlo directamente en el chat. El subagente tiene un costo de inicio: no vale la pena para todo.
Equilibrio: la herramienta adecuada para cada tamaño de tarea, sin dogmas.
Overhead de inicio; la tarea pequeña se queda en el chat.
🧬 Anatomía de un subagente
El archivo .md por dentro: frontmatter (la configuración) + cuerpo (el cerebro). Panorama general aquí; se profundiza en la Trilha 2.
No hay nada mágico: el subagente es literalmente un archivo Markdown, con la misma estructura que un skill.md.
Desmitifícalo de una vez. Si sabes editar texto, sabes crear un subagente.
Archivo = agente; texto simple y versionable.
La cima entre --- es el frontmatter (configuración en YAML); el resto es el cuerpo, el cerebro con las instrucciones.
Ver las dos zonas es el mapa mental de toda la Ruta 2. Cada una tiene un papel distinto.
Frontmatter = cómo se selecciona el agente; cuerpo = cómo actúa.
Los campos esenciales del frontmatter: name, description, tools e model.
Con estos cuatro ya puedes crear un subagente funcional. El resto son ajustes.
name (id), description (activador), tools (permisos), model (costo).
Un buen cuerpo define el rol ("eres un…"), los pasos numerados, el formato de salida y lo que NO debe hacer.
Esta estructura es lo que distingue a un agente confiable de uno genérico. Es el esqueleto de la Trilha 2.
Rol → pasos → salida → restricciones.
El archivo está en .claude/agents/ (en el proyecto) o ~/.claude/agents/ (global), tema de la Trilha 2.
Saber dónde vive es lo que conecta "crear el .md" con "que Claude lo encuentre y lo use".
La carpeta determina el alcance; proyecto vs. global.
Además de los 4 campos clave, hay campos avanzados (color, memory, disallowed-tools, MCP) documentados oficialmente.
No necesitas memorizarlo todo: necesitas saber que existe la referencia completa y dónde encontrarla.
4 campos para empezar; documentación oficial para el resto.