≡En resumen
- Un subagente tiene su propia ventana de contexto: lee y trabaja aparte y devuelve un resumen al agente principal.
- Se definen en archivos Markdown con nombre, descripción, herramientas permitidas y modelo opcional.
- Claude los usa automáticamente según su descripción o cuando se lo pides de forma explícita.
- Son ideales para búsquedas amplias, revisiones independientes y tareas en paralelo; no para todo.
- Más subagentes significa más tokens consumidos: úsalos cuando el aislamiento compensa.
01 ¿Qué son los subagentes?
Cuando trabajas con Claude Code, la conversación principal acumula todo lo que se lee y se hace: archivos, resultados de comandos, búsquedas. Si para responder una pregunta hay que revisar cincuenta archivos, todo ese texto ocupa la ventana de contexto aunque solo necesites la conclusión. Los subagentes resuelven esto: Claude encarga la tarea a otra instancia que trabaja aparte y solo devuelve el resultado.
Cada subagente tiene sus propias instrucciones (su prompt de sistema), su propio contexto, que empieza en blanco, y un conjunto de herramientas que puedes limitar. No ve tu conversación ni lo que ya has hablado con Claude, así que el encargo debe ser autosuficiente.
02 Para qué sirven los subagentes
Proteger el contexto
La exploración pesada ocurre fuera de la conversación principal, que conserva espacio para lo importante.
Especializar
Un revisor de seguridad, un redactor de pruebas o un analista de datos con instrucciones y herramientas propias.
Paralelizar
Varios subagentes investigan partes distintas de un proyecto a la vez y Claude junta los resultados.
Revisar con ojos nuevos
Un subagente que no ha escrito el código lo revisa sin los sesgos de la conversación que lo produjo.
Limitar permisos
Un subagente de solo lectura no puede editar archivos aunque se lo pidan.
Ahorrar coste
Las tareas sencillas se pueden asignar a un modelo más rápido y barato que el de la conversación principal.
03 Subagentes integrados en Claude Code
| Subagente | Para qué lo usa Claude | Permisos |
|---|---|---|
| Explore | Buscar y entender código rápidamente | Solo lectura |
| Plan | Investigar antes de proponer un plan en el modo de planificación | Solo lectura |
| general-purpose | Tareas de varios pasos que requieren explorar y actuar | Acceso completo a herramientas |
No necesitas configurar nada para que Claude use estos subagentes: los lanza cuando la tarea lo justifica. Los tuyos se suman a estos. Si dos definiciones comparten nombre, gana la de mayor prioridad: la gestionada por la organización, después la que se pasa en la línea de comandos, la del proyecto, la del usuario y, por último, la de un plugin.
04 Cómo crear un subagente en Claude Code
Un subagente es un archivo Markdown con un encabezado YAML y, debajo, sus instrucciones. Guárdalo en .claude/agents/ para compartirlo con el equipo en el repositorio o en ~/.claude/agents/ para usarlo en todos tus proyectos. También puedes pedirle a Claude que lo cree por ti. El formato recuerda al de un archivo SKILL.md, pero define a quién se delega, no un procedimiento.
---name: revisor-codigodescription: Revisa cambios de código buscando errores, problemas de seguridad y desviaciones de las convenciones. Úsalo después de modificar código.tools: Read, Grep, Globmodel: sonnet---Eres un revisor de código exigente. Revisa los cambios indicados,clasifica cada hallazgo por gravedad y propone la corrección.No modifiques archivos.
| Campo | Para qué sirve |
|---|---|
| name y description | Obligatorios. La descripción decide cuándo Claude delega en este subagente |
| tools y disallowedTools | Lista de herramientas permitidas o prohibidas |
| model | Alias sonnet, opus, haiku o fable, un identificador completo o inherit para heredar el de la conversación |
| permissionMode | Modo de permisos con el que trabaja |
| skills y mcpServers | Skills precargadas y servidores MCP propios del subagente |
| background, effort, isolation | Ejecutar en segundo plano, nivel de esfuerzo o trabajar en un git worktree temporal |
05 Cómo se usan: automáticos, explícitos y en paralelo
-
1
Delegación automática
Claude compara tu petición con la descripción de cada subagente y delega cuando encaja.
-
2
Petición explícita
Puedes pedirlo con tus palabras: «usa el subagente revisor-codigo para revisar estos cambios».
-
3
Primer plano
Bloquea la conversación hasta terminar; las peticiones de permiso te llegan directamente.
-
4
Segundo plano
Trabaja mientras sigues con otra cosa; con Ctrl+B mandas al fondo una tarea en marcha.
-
5
Varios a la vez
Claude puede lanzar varios subagentes en paralelo y combinar sus respuestas.
06 Subagentes, skills o un solo agente: cuándo usar cada uno
| Situación | Mejor opción | Por qué |
|---|---|---|
| Quieres que Claude siga tu proceso para una tarea | Skill | Añade conocimiento sin separar el contexto |
| Hay que leer mucho para obtener poco | Subagente | La lectura no ensucia la conversación principal |
| Necesitas una revisión independiente | Subagente | Contexto limpio y permisos limitados |
| Partes independientes de un proyecto grande | Varios subagentes en paralelo | Se avanza a la vez y se junta el resultado |
| Tarea corta con todo el contexto ya en la conversación | Agente principal | Delegar obligaría a repetir el contexto |
Las Claude Skills y los subagentes se combinan bien: una skill puede ejecutarse dentro de un subagente y un subagente puede tener skills precargadas. Si un subagente necesita herramientas externas, puedes darle sus propios servidores MCP.
07 Buenas prácticas y costes
La regla de oro es pensar en el subagente como en un compañero que llega sin contexto. Cuanto más claro sea el encargo y más acotado el formato de respuesta, mejor será lo que vuelve a la conversación principal y menos tendrás que corregir después.
- ✓Escribe descripciones concretas: de ellas depende que Claude delegue en el momento adecuado.
- ✓Da a cada subagente solo las herramientas que necesita.
- ✓Redacta el encargo como si fuera para alguien que no ha visto la conversación: objetivo, archivos y formato de respuesta.
- ✓Pide respuestas cortas y estructuradas para no traer de vuelta el ruido.
- ✓Usa modelos más ligeros para búsquedas y reserva los más capaces para decisiones.
- ✓Versiona los subagentes del proyecto en el repositorio para que todo el equipo use los mismos.
08 Subagentes en proyectos reales
En la migración de una aplicación con decenas de módulos, el agente principal pide a varios subagentes Explore que inventaríen cada área: rutas, modelos de datos y dependencias. Con esos resúmenes prepara el plan. Después, un subagente redacta pruebas y otro, de solo lectura, revisa cada cambio antes de darlo por bueno. La conversación principal nunca carga el código completo y el equipo revisa decisiones, no ruido.
Así trabajamos en appyweb cuando abordamos proyectos de desarrollo de aplicaciones con Claude Code. Si quieres aplicar este enfoque de automatización con inteligencia artificial en tu empresa, podemos ayudarte. Y en nuestro directorio de herramientas y recursos para Claude encontrarás más material para empezar.
Preguntas frecuentes sobre Subagentes
Es una instancia de Claude con su propio contexto, instrucciones y herramientas en la que el agente principal delega una tarea, y que al terminar devuelve solo el resultado.
En .claude/agents/ dentro del proyecto para compartirlos con el equipo, en ~/.claude/agents/ para todos tus proyectos o en la carpeta agents/ de un plugin.
No. Empieza con el contexto en blanco y solo recibe el encargo que le pasa el agente principal, por eso ese encargo debe incluir todo lo necesario.
Sí, con el campo model: un alias como sonnet, opus o haiku, un identificador completo de modelo o inherit para usar el de la conversación principal.
Normalmente sí, porque cada uno procesa sus propios tokens. Compensan cuando evitan llenar el contexto principal o cuando el trabajo en paralelo ahorra tiempo.
La skill añade instrucciones al agente que ya está trabajando. El subagente es otro agente con contexto propio al que se le delega la tarea.
Claude Code permite varios subagentes en paralelo con un límite configurable. Más allá del límite técnico, conviene lanzar solo los necesarios, porque cada uno suma consumo.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗