Explicación de los subagentes de Claude Code: qué son y cuándo usarlos.
Cómo difieren los subagentes de Claude Code de las habilidades y los equipos de agentes: aislamiento del contexto, el primer subagente personalizado, buenas prácticas para la descripción y las herramientas, y cuándo omitirlos.
Los agentes no son más que habilidades disfrazadas
La reacción inicial común ante los agentes de Claude Code es pensar que se trata de habilidades con pasos adicionales, una “habilidad más inteligente” que actúa de forma más autónoma porque sus instrucciones están redactadas de manera diferente. Esa visión es errónea. Un agente es, en efecto, un prompt, al igual que una habilidad. La diferencia relevante radica en dónde se ejecuta. Un agente no se ejecuta dentro de la conversación principal; cuenta con su propia ventana de contexto, su propio prompt del sistema, su propio acceso a herramientas y sus propios permisos, trabaja en segundo plano y devuelve un resultado.
Lo que sigue parte de lo básico: qué son estos agentes, cómo crear uno y cuándo vale la pena el esfuerzo. Se da por sentado que ya utilizas Claude Code y deseas comprender bien esta función antes de cambiar cualquier configuración. El orden es primero el problema del vocabulario, luego las razones por las que existen los subagentes, a continuación un primer subagente personalizado, después cómo difieren de las habilidades, seguidas de las prácticas de trabajo, un vistazo a los equipos de agentes y, finalmente, los casos en los que un agente es la elección incorrecta.
Cuatro cosas que la gente entiende por “agente”
En Claude Code, la palabra “agente” abarca al menos cuatro conceptos distintos, y confundirlos hace que toda esta función sea más difícil de comprender. Un poco de pedantería aquí rinde frutos, ya que permite relacionar el vocabulario con recursos que realmente puedes utilizar.
- Claude Code es en sí mismo un entorno agente. Anthropic lo presenta como un asistente de programación con capacidad de acción: cuenta con herramientas y un bucle de ejecución, y puede planificar y actuar en varios pasos sin necesidad de ser instruido en cada uno. Ya es un entorno agente antes incluso de que se configure nada.
- Los subagentes son los primitivos de agente personalizados dentro del producto. Cuando un usuario dice que está creando un agente en Claude Code, casi siempre se refiere a un subagente. Según la documentación oficial, estos son subagentes que funcionan como asistentes especializados para tipos específicos de tareas, cada uno con su propia ventana de contexto, un prompt del sistema personalizado, acceso a herramientas definido y permisos independientes.
El resto se centra en el segundo punto: los subagentes. Más adelante merecen un tratamiento aparte; explicar detalladamente a uno de los subagentes es el punto adecuado para comenzar.
Por qué existen los subagentes
La causa raíz es que los modelos de lenguaje tienen un contexto finito, y tarde o temprano una sesión larga alcanza ese límite. Sin alguna medida contraria, esto ocurre una y otra vez.
El ensayo de Anthropic sobre la curaduría del contexto describe esta disciplina como la selección de lo que se incluye en una ventana limitada. Cada llamada a una herramienta, lectura de archivo y análisis inconcluso se agrega al contexto y permanece allí. Cuanto más tiempo dura una sesión, más espacio de esa ventana ocupa el material auxiliar que ayudó a encontrar una respuesta pero que resulta inútil posteriormente. Ese desorden afecta la calidad, un deterioro que a menudo se denomina “putrefacción” en la ventana. El modelo dispone de menos espacio para trabajar, y más material irrelevante compite por su atención.
Los subagentes son una solución. La sección de resumen de Claude Code lo indica claramente: un subagente puede leer docenas de archivos o realizar búsquedas extensivas, pero la conversación principal solo recibe un resumen, de modo que el trabajo intermedio nunca agota el contexto principal. Esto es útil cuando los pasos intermedios no necesitan permanecer visibles.
Un ejemplo concreto: pides a Claude que averigüe por qué una suite de pruebas está fallando. Al realizar la investigación en la sesión principal, es necesario leer veinte archivos, buscar patrones de errores, verificar la configuración de las pruebas y escanear los commits recientes. Todo esto termina formando parte de tu contexto. Al final, has gastado varios miles de tokens en el trabajo intermedio, y casi nada de ello afecta lo que hagas a continuación.
Un subagente reconfigura el problema. La investigación se lleva a cabo en su propia ventana de contexto y con su propio presupuesto de tokens, y lo que se obtiene es un veredicto breve, del tipo “la falla se debe a una variable de entorno ausente en la configuración CI; tres pruebas fallaron, y aquí está la solución”. El hilo principal nunca absorbe el ruido generado durante la búsqueda.
El aislamiento de contexto es la razón principal, y hay tres factores menores que lo respaldan:
- Especialización. Un subagente cuenta con su propio prompt del sistema. Un revisor enfocado, con instrucciones sobre los estándares de tu equipo, será más preciso que un asistente general que intenta aplicar esos mismos estándares junto con todo lo demás que sabe.
Creación del primer subagente personalizado
Técnicamente, un subagente no es más que un documento Markdown con una cabecera YAML. Hay dos ubicaciones válidas:
.claude/agents/dentro de un proyecto, para agentes vinculados a ese código. Guarde estos archivos en el repositorio para que el equipo pueda compartirlos y mejorarlos.
~/.claude/agents/ en el directorio principal, para los agentes personales disponibles en cada proyecto.El frontmatter merece atención
La gente tiende a leer rápidamente el frontmatter en formato YAML, pero Claude Code lo mantiene en la memoria de la sesión principal para saber para qué sirve cada agente. En efecto, funciona como un resumen del agente. Se requieren dos campos y varios más son opcionales. Un ejemplo sencillo muestra cómo se combinan:
---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.
Pasando por campo por campo:
namees el identificador único, en minúsculas y con solo guiones. Los registros lo muestran, y Claude lo utiliza para nombrar al agente internamente.descriptiones lo más importante. Claude la consulta para decidir si una tarea pertenece a este agente, por lo que debe describir su comportamiento: la tarea que realiza el agente y los momentos en los que se debe recurrir a él. Incluir “usar de forma proactiva” es una indicación documentada que le dice a Claude que active al agente sin esperar una solicitud explícita. Omita esta frase si el agente solo debe responder cuando se le pregunte directamente.
tools limita lo que puede acceder el agente. El revisor mencionado anteriormente puede leer archivos y realizar búsquedas, pero no puede editarlos, ejecutar comandos de shell ni realizar llamadas a red. Esto se hace intencionadamente: un revisor de solo lectura no puede cambiar accidentalmente lo que está revisando. La propia documentación recomienda otorgar únicamente las herramientas que necesite el agente, por motivos de seguridad y para mantener su comportamiento predecible.model dirige al agente a un modelo específico: sonnet, opus, haiku, o un ID completo como claude-opus-4-6. Sin él, el agente utiliza inherit, lo que significa que emplea el mismo modelo que la sesión principal.La referencia completa de los campos opcionales muestra cuánto más se puede ajustar: permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color y otros.
Al haber visto un agente, podrías pensar que está cerca de ser una habilidad. Tendrías razón en parte, pero también pasarías por alto el punto clave, que se explica en las secciones siguientes.
Dónde guardar el archivo
Guarda el ejemplo como .claude/agents/code-reviewer.md en el proyecto. El layout resultante se verá así:
your-project/
├── .claude/
│ ├── agents/
│ │ └── code-reviewer.md ← your new agent file
│ ├── skills/
│ └── rules/
├── src/
├── tests/
├── README.md
└── package.json
Después de guardar, Claude detecta al agente. Pídale que revise los cambios en el código y él mismo lo delegará a code-reviewer, según cuán bien coincida la solicitud con la descripción. Para un agente personal que funcione en todos los proyectos, mueva el archivo a ~/.claude/agents/code-reviewer.md. El formato y el contenido permanecen idénticos; solo cambia la ubicación.
Agentes versus habilidades
Por qué se confunden los dos
Tres similitudes explican la mayor parte de esta confusión:
- Ambos se configuran a través de una estructura de carpetas sencilla, dentro de
.claude/skillso.claude/agents. - Ambos utilizan frontmatter, y en ambos la descripción es el parámetro más importante.
- Ambos son conjuntos de instrucciones, en otras palabras, prompts. Una habilidad y un agente pueden contener exactamente las mismas palabras.
Vistos de esa manera, parecen similares en su estructura.
Dónde se realiza el trabajo
No obstante, existe una diferencia práctica y visible que los separa: el lugar donde se realiza el trabajo, es decir, dónde se gastan los tokens. Es la distinción más sencilla de comprender.
- Una habilidad se integra en la conversación en curso. Sus instrucciones, plantillas y archivos de soporte se unen al contexto activo; Claude los procesa en el mismo hilo de conversación, y cada paso se muestra en la ventana principal.
- Un subagente funciona de forma independiente en su propia ventana de contexto. Él realiza el trabajo, y la conversación principal recibe un resultado.
Superficie de ajuste
Anteriormente se presentó una larga lista de campos que un agente puede configurar en su frontmatter. En contraste, las habilidades aceptan una lista mucho más corta, que además es parcialmente diferente. Esto indica el mayor grado de control que brindan los agentes. No se trata de convertir todo en un agente; lo importante es que el modelo mental utilizado para diseñar una configuración fiable podría necesitar ser reconsiderado.
Una tarea, dos respuestas
Tomemos como ejemplo el deseo de que los estándares de revisión de código del equipo se apliquen de manera consistente.
Si Claude debe estar al tanto de esos estándares durante toda la sesión, utilizarlos mientras escribe código, citarlos en sus consejos y señalar las infracciones a medida que aparecen, entonces una habilidad es adecuada. Basta escribir los estándares una vez y Claude los incorporará al contexto cuando sean relevantes, de modo que todo lo realizado en la sesión pueda basarse en ellos.
Si en cambio desea que se revisen cuarenta archivos de una sola vez, sin que el contexto principal se llene de lecturas de archivos, comentarios intermedios y resultados de búsqueda, entonces se necesita un subagente. Configure un agente de revisión de código, déjelo funcionar en su propia ventana y reciba un resumen estructurado. Incluso podría iniciar cuarenta subagentes en paralelo, uno por archivo. La conversación principal recibe el resultado sin ver el trabajo que lo generó.
Una frase resume la diferencia: una habilidad cambia lo que sabe Claude o cómo aborda un flujo de trabajo, mientras que un subagente cambia quién realiza el trabajo, en qué contexto y con qué herramientas.
Prácticas de trabajo que funcionan
Trate la descripción como una interfaz de enrutamiento
Esto recibe menos énfasis del que debería. Claude lee las descripciones de los subagentes para decidir cuándo delegar, y no lee el cuerpo del mensaje antes de tomar esa decisión. Cualquier información específica que incluyas en el cuerpo del prompt permanece invisible hasta que se haya creado el subagente. Por lo tanto, la descripción debe contener suficiente información para que Claude sepa cuándo se necesita el agente.
- Utiliza una redacción específica y basada en el comportamiento.
- Indica qué hace el agente y en qué situaciones se debe elegirlo.
- Menciona los tipos de tareas que maneja bien y, si es útil, aquellas con las que no debería ocuparse.
- "Usar de forma proactiva después de cambios en el código" es un patrón probado, mencionado en la documentación como forma de fomentar la delegación sin una solicitud explícita. Omítelo para los agentes que solo deben ejecutarse cuando se les invoque directamente.
Para ver la diferencia, coloque una descripción vaga (“Ayuda con la calidad del código y las tareas de revisión”) junto a una redactada para el enrutamiento: “Revisa los cambios preparados en busca de defectos de seguridad, errores lógicos y problemas de estilo. Úselo proactivamente después de cada edición importante. Nunca escribe código ni edita archivos.”
Restrinja las herramientas a propósito
Un agente que hereda todas las herramientas de la sesión principal es difícil de manejar cuando surge un problema. Solo otorgue lo que necesite la tarea.
- Un revisor debería poder leer, y nada más: sin capacidad de escritura, sin shell, sin acceso a red.
- El trabajo de investigación requiere buscar y obtener información, sin posibilidad de editar archivos.
- Ejecutar pruebas implica acceso a Bash, pero no hay motivo para interactuar con la web.
Restringir las herramientas ayuda a la seguridad y a la claridad. Un conjunto limitado de herramientas hace que el comportamiento sea predecible, y cuando el agente falla o devuelve algo inusual, una lista corta de herramientas posibles acelera el diagnóstico. También hace que los modos de fallo sean finitos y conocibles. El campo disallowedTools permite que un agente herede las herramientas de la sesión principal y luego elimine algunas específicas, lo cual es útil en casos como “todo excepto Bash” o “todo excepto Write”.
Asigna una tarea a cada agente
La documentación sobre los subagentes indica claramente que cada uno debe destacar en una sola tarea. Una descripción como “revisa código, escribe pruebas, actualiza documentación y se encarga de las verificaciones de despliegue” incluye cuatro funciones en un mismo campo. Claude podría asignarles tareas de manera desigual, y el prompt del sistema tendría que manejar cuatro modos de operación al mismo tiempo.
Es mejor delimitar el alcance y crear tres archivos separados, cada uno con una descripción clara. En ciencia de datos podrían ser un agente para la validación de modelos, un verificador de calidad de datos y un revisor de cuadernos de notas. En software, podrían ser un revisor de código, un generador de pruebas y un actualizador de documentación. Este principio es aplicable en cualquier campo: cada agente tiene una única tarea, su propio archivo y una descripción que permite una asignación sin ambigüedades.
Utilice el campo del modelo para gestionar los costos
Las personas que aún no se han sorprendido por su factura de uso tienden a ignorar este campo en la mayoría de los casos. Establecer model: haiku en agentes ligeros reduce notablemente los costos cuando varios agentes se ejecutan en una misma sesión. Por su parte, establecer model: opus en un agente que debe razonar extensamente sobre un contexto amplio justifica su precio. Dejar el valor predeterminado, inherit, significa que cada agente utiliza lo mismo que la sesión principal, a menudo el modelo más potente, aplicado de manera igualitaria incluso a tareas que no lo necesitan.
Lo acordado por la comunidad
La colección de subagentes VoltAgent incluye a más de cien subagentes especializados, que abarcan expertos en idiomas, revisores de seguridad, depuradores, asistentes de infraestructura y orquestadores. Otro buen conjunto se encuentra en el repositorio Everything Claude Code. Pocas personas necesitarían ni siquiera una quinta parte de ellos, por lo que la cantidad no es lo importante; lo relevante es la estructura. Cada entrada en estas colecciones tiene un alcance específico, ya sea un especialista en TypeScript, un experto en SQL, un operador de Kubernetes o un auditor de seguridad. Ninguno intenta abarcar más de un dominio. Ese es el consenso tras más de un año de uso real: muchos agentes especializados superan a un agente de uso general.
Un breve vistazo a los equipos de agentes
Los equipos de agentes merecen ser conocidos, pero son una característica distinta a los subagentes.
Los subagentes permanecen dentro de una misma sesión. La instancia principal de Claude Code los crea, trabajan de forma aislada y devuelven resultados, mientras que tú sigues siendo el orquestador.
Los equipos de agentes son sesiones independientes de Claude Code que se comunican entre sí a través de una lista de tareas compartida y mensajería directa entre pares. Cada miembro del equipo tiene su propia ventana de contexto y estado de sesión, y puede asignar tareas a otros así como recibirlas.
La documentación de los equipos enumera en qué situaciones resulta útil este mecanismo adicional: en la investigación o revisión cuando varios miembros exploran diferentes ángulos juntos; en la depuración mediante hipótesis concurrentes, donde los miembros cuestionan las teorías de los demás; y en la creación de nuevos módulos, donde cada miembro se encarga de su propio componente y evita conflictos con los demás.
Configurarlos no es sencillo, por lo que quedan fuera del alcance de esta explicación, y no hay motivo para adoptarlos por miedo a quedarse atrás. Los equipos añaden una carga adicional de coordinación y consumen muchos más tokens, ya que cada miembro del equipo tiene su propia ventana de contexto facturada de forma independiente. Son una opción experimental y vienen desactivados por defecto, pudiéndose activar mediante una variable de entorno.
Una regla práctica: siempre que tus subagentes te informen y no necesiten comunicarse entre sí, no son necesarios los equipos. Cuando un subagente debe entregar sus hallazgos a otro o cuestionar sus conclusiones, la mejora comienza a justificar su costo. Hasta entonces, los subagentes son suficientes.
Cuando un agente es la herramienta inadecuada
Las directrices propias de Anthropic para crear agentes eficaces merecen ser tomadas en serio. Recomiendan buscar la solución más sencilla y viable, y añadir complejidad solo cuando sea necesario, lo que podría significar no crear sistemas de agentes en absoluto.
Eso se aplica directamente. Algunas situaciones en las que un subagente genera complicaciones sin aportar nada:
- Tareas puntuales. Un subagente implica costos adicionales de creación: nombramiento, redacción de la descripción, selección de herramientas, pruebas y mantenimiento. Una tarea que se realizará una sola vez no justifica todo eso, por lo que es mejor redactar una buena instrucción. La inversión solo rinde frutos cuando un flujo de trabajo se repite con suficiente frecuencia como para que valga la pena mantener una definición.
El principio general es optar por la herramienta más simple que resuelva el problema real. Añade agentes cuando sea necesario aislar el contexto, aplicar restricciones especializadas o realizar una ejecución dedicada, y no porque los agentes parezcan más potentes.
La versión breve
En pocas palabras, los subagentes gestionan el contexto y delimitan los límites de una ejecución, aunque la mayoría de las personas los consideran una mejora en las capacidades.
Un agente configurado con cuidado es algo que se puede completar en una tarde razonable. No hay necesidad de un sistema de orquestación para obtener beneficios aquí: una descripción clara, un conjunto limitado de herramientas y una tarea sencilla son suficientes. La complejidad puede aumentar a partir de ahí, pero no tiene por qué comenzar así.
Hay algunas preguntas que vale la pena hacerse. ¿Qué tarea de su flujo de trabajo actual le gustaría entregarle a un trabajador aislado y qué es lo que lo detiene? Si ya utiliza subagentes, ¿cuál fue la primera tarea en la que el aislamiento fue realmente importante, donde ejecutarla en la sesión principal habría causado un problema real? ¿Y cómo gestiona el acceso a las herramientas: restringiéndolo por agente o heredándolo de la sesión principal y ajustándolo?