Subagentes de Claude Code: qué son y cómo usarlos

Por CodeAgentSwarm · Actualizado el 31 de octubre de 2026

Un subagente es un ayudante al que Claude Code le pasa una tarea secundaria. Trabaja con su propia ventana de contexto, se encarga de la parte ruidosa (buscar en el código, leer logs, revisar un diff) y devuelve solo el resultado, así que tu conversación principal sigue corta y centrada. En esta guía tienes lo que dice la documentación de Anthropic sobre los subagentes, cómo escribir los tuyos y cómo CodeAgentSwarm te enseña cada subagente mientras trabaja, con su modelo y su paso actual, y deja que los agentes abran subagentes con cualquier modelo en el que tengas sesión iniciada.

Qué son los subagentes

Según la documentación de subagentes de Anthropic, cada subagente se ejecuta en su propia ventana de contexto, con un prompt de sistema propio, acceso a herramientas concretas y permisos independientes. Cuando una tarea encaja con la descripción de un subagente, Claude se la delega y recibe el resultado.

  • Contexto limpio: el subagente no ve el historial de tu conversación. Lee lo que necesita y devuelve un resumen.
  • Herramientas limitadas: puedes darle a un revisor solo herramientas de lectura y dejar fuera Edit y Write.
  • Su propio modelo: una búsqueda rápida puede ir en un modelo más pequeño mientras la sesión principal sigue en uno más grande.
  • Mismos límites de uso: un subagente hace sus propias peticiones, y cuentan para los mismos límites que tu conversación principal.

Los subagentes que vienen de serie

  • Explore: un agente rápido y de solo lectura para buscar y analizar el código.
  • Plan: un agente de investigación de solo lectura que se usa en el modo plan para reunir contexto antes de proponer un plan.
  • general-purpose: para tareas complejas de varios pasos que piden explorar y también hacer cambios.

Claude los elige solo. También puedes pedir uno a propósito, por ejemplo: "usa el subagente Explore para encontrar todos los sitios donde leemos la cookie de sesión".

Cómo crear tu propio subagente

Un subagente es un archivo Markdown con frontmatter YAML. Ponlo en .claude/agents/ para compartirlo con un proyecto, o en ~/.claude/agents/ para usarlo en todos tus proyectos. Solo name y description son obligatorios.

markdown
---
name: revisor-de-codigo
description: Revisa el código buscando calidad y buenas prácticas
tools: Read, Glob, Grep
model: sonnet
---

Eres un revisor de código. Cuando te llamen, analiza el código y da
feedback concreto y accionable sobre calidad, seguridad y buenas prácticas.
  • description le dice a Claude cuándo delegar. Que sea corta y concreta.
  • tools limita lo que puede usar el subagente. Si lo quitas, hereda las herramientas disponibles.
  • model acepta sonnet, opus, haiku, fable, un ID de modelo completo o inherit.

No hace falta escribir el archivo a mano. Pídele a Claude Code que cree el subagente y revisa lo que escribe.

Los subagentes pueden ir en primer plano, bloqueando la conversación principal hasta que terminan, o en segundo plano mientras sigues trabajando.

Subagentes, Agent Teams y sesiones separadas

Los subagentes viven dentro de una sesión y le devuelven el resultado. Agent Teams coordina varias sesiones de Claude Code con una sesión líder (mira Agent Teams de Claude Code vs CodeAgentSwarm). Las sesiones separadas son totalmente independientes, y aun así puedes pedirle a un agente que planifique el trabajo y lo reparta con un coordinador.

Ve cada subagente en CodeAgentSwarm

En un terminal normal, un subagente es una línea que dice que se ha delegado trabajo, y lo que hace no se ve. El Chat de CodeAgentSwarm le da a cada turno un bloque de subagentes. Cada fila muestra:

  • El icono del agente y el nombre del subagente.
  • Lo que está haciendo en ese momento.
  • Su modelo y nivel de razonamiento, cuando el agente los informa (en Claude Code, cuando la llamada nombra un modelo como Haiku).
  • Su estado y cuánto tiempo lleva.

Pulsa una fila para abrir la conversación de ese subagente: sus instrucciones, sus respuestas y las herramientas que ha usado. Una ruta arriba te devuelve a la conversación principal. Junto a la caja de mensaje, un contador te dice cuántos subagentes están en marcha; muestra primero los que te esperan, luego los que siguen trabajando y después los terminados, para que puedas abrir cualquiera más tarde.

Subagentes con cualquier modelo en el que tengas sesión

CodeAgentSwarm también da a cada agente una forma de abrir sus propios subagentes, y pueden usar cualquier modelo en el que tengas sesión iniciada en CodeAgentSwarm, no solo el del agente principal. Las reglas son sencillas:

  • Si nombras un agente o un modelo ("pide a un subagente de Codex que revise esto"), usa ese.
  • Si no, el subagente usa el mismo agente, modelo y razonamiento que el principal.
  • El agente solo elige otro proveedor cuando una segunda opinión o un modelo más adecuado ayudan de verdad, y solo si a ese proveedor le queda cuota.
  • Te dice el motivo en una línea, y estos subagentes muestran cuándo están esperando una respuesta tuya.

Si eres tú quien pide pasar el trabajo a otro agente, CodeAgentSwarm lo abre como una sesión normal y visible, para que la sigas como cualquier otra. Para llevar muchas sesiones a la vez, mira enjambre de agentes de Claude Code.

Preguntas frecuentes

¿Qué es un subagente en Claude Code?

Un ayudante especializado con su propia ventana de contexto, prompt de sistema, herramientas y permisos. Claude le delega una tarea y recibe solo el resultado, lo que mantiene centrada la conversación principal.

¿Dónde pongo mis subagentes?

En .claude/agents/ para un proyecto o en ~/.claude/agents/ para todos tus proyectos. Cada subagente es un archivo Markdown con name y description en el frontmatter, y opcionalmente tools y model.

¿Los subagentes gastan más de mi plan?

Hacen sus propias peticiones, y esas peticiones cuentan para los mismos límites de uso que tu conversación principal.

¿Un subagente puede usar otro modelo?

Sí. Pon model en el frontmatter (sonnet, opus, haiku, fable, un ID de modelo completo o inherit). En CodeAgentSwarm, los agentes también pueden abrir subagentes con otro proveedor en el que tengas sesión, como Codex.

¿Cómo veo lo que está haciendo un subagente?

En el Chat de CodeAgentSwarm, cada subagente aparece como una fila con su paso actual, modelo, estado y tiempo. Púlsala para abrir su conversación completa.