Subagentes de Claude Code: guía para principiantes paso a paso

Qué es un subagente, en palabras sencillas

Imagina Claude Code como el jefe de un equipo pequeño. Habla contigo y tiene presente toda la tarea, mientras los encargos pesados de al lado se los pasa a sus ayudantes: uno relee veinte archivos, otro revisa un texto, un tercero busca datos en internet. Cada uno trabaja tranquilo en su mesa y vuelve con una nota corta.

Esos ayudantes son los subagentes de Claude Code. También se les llama «agentes de Claude Code» o «agentes personalizados». Es lo mismo.

¿Para qué montar todo esto si puedes hacerlo todo en un solo chat? Hay cuatro motivos.

• El Claude principal mantiene la cabeza despejada. Cada conversación tiene un límite de memoria que se llama ventana de contexto. Cuando Claude lee decenas de páginas, todo ese texto se acumula en el chat y a media jornada empieza a perder el hilo. El subagente lo lee todo en su propia ventana y devuelve solo lo esencial.
• Especialización. El subagente tiene sus propias instrucciones. Un editor de posts revisa siempre lo mismo y con la misma lista, y no tienes que volver a explicarle el trabajo.
• Restricciones. Puedes permitir que un subagente solo lea archivos. Así no puede romper nada, aunque quiera.
• Ahorro de límite. El trabajo sencillo puede ir al modelo Haiku, rápido y barato, y lo que exige pensar se queda en Opus.

Algunos agentes ya vienen de serie y Claude los llama por su cuenta. Explore busca en los archivos y no cambia nada. Plan reúne contexto cuando le pides primero un plan. General-purpose se encarga de tareas de varios pasos en las que hay que buscar y también cambiar cosas. Si ves en la ventana una línea como Explore(Find every mention of the price), es un subagente trabajando.

Tus propios subagentes tienen sentido cuando le das a Claude una y otra vez el mismo encargo con las mismas explicaciones. Describes al ayudante una vez y a partir de ahí trabaja con tu estándar.

Qué necesitas y cuánto cuesta

Los subagentes viven dentro de Claude Code. Así que necesitas Claude Code y un plan de pago: el plan Free no lo incluye. Puedes trabajar en la terminal o en la pestaña Code de la app de escritorio de Claude, y los subagentes se cargan en las dos. Si todavía no tienes Claude Code, empieza por la guía de cómo usar Claude Code. En Windows, sigue la guía aparte para instalar Claude Code en Windows.

Los precios salen de la página oficial claude.com/pricing. Si quieres ver con calma qué plan encaja con qué trabajo, tienes el desglose en planes y precios de Claude.

Un detalle que casi nadie menciona: cada subagente gasta el mismo límite de uso que tu conversación principal. Cinco agentes en paralelo lo agotan cinco veces más rápido, así que con Pro empieza con uno o dos y con un modelo barato.

Regístrate en claude.ai con cualquier correo, elige un plan y entra en Claude Code con esa misma cuenta.

Cómo crear subagentes en Claude Code: el primero en 10 minutos

No hace falta crear archivos a mano. Le describes el subagente a Claude con palabras normales y Claude escribe el archivo. Vamos a montar un editor de posts que revise el texto antes de publicarlo y que no cambie nada sin ti.

Crea un subagente editor-de-posts en la carpeta .claude/agents de este proyecto.
Tarea: revisar un post para redes sociales o una newsletter ya terminados antes de publicarlos.
Devuelve: una lista de errores (erratas, jerga, frases largas, repeticiones) con una cita y una corrección para cada uno, una nota para la primera línea y una versión más fuerte de esa línea.
Solo lee archivos y nunca cambia nada. Modelo: haiku. Respuesta de 15 líneas como máximo.

Para que el agente esté disponible en todos tus proyectos, pídele a Claude que lo guarde en tu carpeta personal: «guarda este agente en ~/.claude/agents para que funcione en todos los proyectos». La documentación oficial muestra la diferencia:

La carpeta .claude/agents/ dentro de un proyecto guarda agentes solo para ese proyecto. La carpeta ~/.claude/agents/ de tu directorio personal guarda agentes para todos los proyectos de tu ordenador. Si dos agentes se llaman igual, gana el del proyecto.

Las guías antiguas enseñan el comando /agents con un asistente de configuración. Ese asistente solo existe hasta la versión 2.1.197. Hoy /agents se limita a recordarte que se lo pidas a Claude o que edites la carpeta de agentes, así que el chat es ahora la forma principal de crearlos.

Prueba real: cómo el agente corrigió un post

Creé este editor y le di un post malo a propósito. El post estaba en ruso. Traducido, decía así: «¡Amigos, hola a todos! Hoy me gustaría hablaros acerca de que la realización de ventas a través de una consulta es el medio más eficaz de obtención de clientes para los especialistas del sector servicios. Apuntaos a una consulta».

Dos conclusiones de esta prueba. Primera: incluso un modelo barato con buenas instrucciones encuentra en tu texto cosas que ya no ves. Segunda: lee tú mismo lo que devuelve el agente. Un ayudante intenta ser útil y puede «mejorar» tu texto con datos inventados. Añade una línea a las instrucciones, «no añadas cifras ni datos que no estén en el texto original», y te llevarás menos sorpresas.

Qué hay dentro del archivo de un subagente

El archivo de un subagente es un archivo de texto normal en formato Markdown. Arriba, entre dos líneas de tres guiones, están los ajustes. Debajo van las instrucciones del agente con tus propias palabras. No tienes que editarlo a mano: dile a Claude qué quieres cambiar y él mismo corregirá el archivo. Aun así, viene bien saber qué hay dentro.

Solo dos campos son obligatorios: name y description. Todo lo demás es opcional.

Sobre las herramientas. Un agente que solo revisa y aconseja necesita Read, Grep y Glob: leer archivos, buscar dentro del texto y encontrar archivos. Un agente que tiene que crear cosas necesita además Write y Edit. Un agente que busca en internet necesita WebSearch y WebFetch. Cuantos menos permisos, más tranquilo duermes.

Qué modelo elegir para un subagente

Cada agente puede trabajar con su propio modelo: el chat principal se queda en un modelo potente y la rutina va a uno más barato.

Claude Code elige el modelo en este orden: el que Claude indica para una llamada concreta, luego el campo model del archivo del agente, después el ajuste CLAUDE_CODE_SUBAGENT_MODEL y, por último, el modelo de tu conversación principal. Si fijas el modelo en el archivo, sabrás qué te vas a encontrar.

Para ver qué modelo usa de verdad un agente en marcha, escribe /tasks. Claude Code muestra el modelo en la fila de cada subagente.

Cómo llamar a un subagente y escribir su descripción

Hay tres formas de llamar a un subagente.

• Nombrarlo en tu mensaje. «Pídele a editor-de-posts que revise este post». Claude casi siempre le pasa la tarea, pero la decisión sigue siendo de Claude.
• Mencionarlo con @. Escribe @ y elige el agente de la lista, igual que eliges un archivo. Así te aseguras de que el agente se ejecute.
• No decir nada. Claude llama al agente por su cuenta cuando la tarea encaja con su descripción. Para eso, la descripción tiene que ser precisa.

La tercera forma es la más cómoda y depende por completo del campo description. Claude lee las descripciones de todos tus agentes y decide a quién le toca qué. Una buena descripción responde a la pregunta «cuándo hay que llamar a este».

Una descripción floja: «Ayuda con textos». Casi cualquier cosa encaja ahí, así que Claude llamará al agente en momentos aleatorios o nunca.

Una descripción fuerte: «Revisa un post terminado antes de publicarlo. Úsalo cuando te pidan corregir, revisar o pulir un post». Tiene la tarea y las palabras clave que le dicen a Claude que ha llegado el momento.

Si quieres que el agente entre solo en cualquier tarea que encaje, añade «use proactively» a la descripción. La documentación de Anthropic recomienda justo eso. Y mantén las descripciones cortas: cuando las descripciones de todos tus agentes juntas superan los 15.000 tokens, Claude Code muestra un aviso al arrancar. Los detalles de cómo debe trabajar el agente ponlos más abajo, en las instrucciones. Solo se cargan mientras el agente está trabajando.

Los subagentes también trabajan en paralelo. Pide: «Lanza tres agentes a la vez: uno revisa el post, otro encuentra todas las menciones del precio antiguo y otro investiga a tres competidores». Por defecto trabajan en segundo plano mientras tú sigues hablando. Pueden funcionar hasta 20 a la vez en una sesión, y cada uno gasta tu límite por separado.

Ejemplos de subagentes de Claude Code: 5 agentes para quienes venden servicios y cursos

Estos son cinco ayudantes que merece la pena crear primero. Cada uno se crea con un solo mensaje en el chat, como en la sección 03.

El espía de la competencia es el que más contexto ahorra. Abre diez páginas, las lee de arriba abajo y te devuelve una sola tabla ordenada:

Crea un subagente espia-de-competencia en ~/.claude/agents para que funcione en todos los proyectos.
Tarea: a partir de una lista de enlaces a webs de la competencia, montar una tabla con producto, precio, promesa principal, formato (curso, consulta, programa de acompañamiento), bonus y garantías.
Herramientas: WebSearch, WebFetch, Read. Nunca cambia archivos. Modelo: sonnet.
Si no encuentra un precio, escribe «no indicado» y nunca se lo inventa.

En el revisor de landings sí compensa gastar límite en Opus. Un punto débil en tu oferta cuesta más que unas cuantas peticiones de más:

Crea un subagente revisor-de-landings en este proyecto.
Tarea: leer la página de venta del enlace con los ojos de alguien que la ve por primera vez y devolver:
1) si en 5 segundos queda claro qué se vende y a quién;
2) las tres objeciones principales que la página no responde;
3) dónde se pierde la llamada a la acción;
4) cinco cambios concretos con el texto nuevo.
Herramientas: WebFetch, Read. Modelo: opus. No inventes testimonios ni cifras.

El agente voz del cliente trabaja con lo que ya tienes. Mete en una carpeta del proyecto tus reseñas exportadas, las respuestas de formularios y los mensajes de clientes, y escribe:

Crea un subagente voz-del-cliente en este proyecto.
Tarea: leer todos los archivos de la carpeta «Reseñas» y devolver 10 dolores de los clientes con sus propias palabras (citas literales), 5 objeciones frecuentes y 5 formas en que los clientes describen su resultado con sus propias palabras.
Herramientas: Read, Grep, Glob. Modelo: sonnet. No parafrasees nada, solo citas.

Esas citas luego van a tus posts, a tu landing y a tus anuncios.

Los subagentes combinan bien con las habilidades: la habilidad marca el orden del trabajo y el agente se queda con la parte pesada. Si quieres un agente que trabaje con horario sin ti, eso ya es el siguiente nivel. Para ver cómo es un agente de IA autónomo, échale un vistazo a Manus, el agente de IA, y para automatizar tareas sin código, a n8n.

Subagentes de Claude Code frente a habilidades

Los dos son archivos de instrucciones en la carpeta .claude, y los dos se pueden crear desde el chat. La diferencia está en dónde se hace el trabajo.

Una habilidad (skill) es un procedimiento por escrito que Claude sigue dentro de tu conversación principal. Ves cada paso y puedes corregirlo sobre la marcha. Un subagente hace el trabajo en una ventana aparte y devuelve solo el resultado. La documentación de Anthropic dice lo mismo: habilidades para flujos de trabajo reutilizables en la conversación principal, subagentes para trabajo aislado.

Además, se combinan. Un subagente puede cargar tus habilidades al arrancar con el campo skills, y así tu editor de posts revisa los textos según tu propia guía de estilo. Y una habilidad puede ejecutarse dentro de un subagente si le añades context: fork. Tienes más sobre habilidades en la guía de habilidades de Claude.

Cuándo no necesitas un subagente

La documentación de Anthropic dice claramente que en algunos casos es mejor quedarse en la conversación principal.

Primero, cuando la tarea exige mucho ir y venir. Estás escribiendo un post y pides cinco veces «más corto», «más cercano», «añade un ejemplo». Un subagente empieza cada vez de cero y no recuerda lo que acordasteis hace un minuto. Aquí es más rápido trabajar directamente.

Segundo, un cambio rápido y puntual. Cambiar un precio en un sitio es más fácil hacerlo tú que esperar a que un agente reúna el contexto.

Tercero, varias etapas que se apoyan en una misma conversación, como una estrategia que ya habéis hablado y de la que ahora sacas textos. Al agente habría que contarle toda la estrategia otra vez.

Los subagentes también pueden llamar a sus propios subagentes, hasta tres niveles de profundidad. Al principio no lo vas a necesitar, pero el techo es alto.

Si algo sale mal

Chuleta

Todo el camino en un minuto. Cópialo para ti.

Chuleta: subagentes de Claude Code
1. Necesitas Claude Code con un plan de pago (Pro desde $20 al mes). Free no incluye Claude Code.
2. Abre la carpeta de tu proyecto y descríbele el agente a Claude con tus palabras.
3. En la descripción: la tarea, cuándo llamarlo, qué herramientas, qué modelo y qué no debe hacer.
4. Agente para un proyecto – .claude/agents; para todos los proyectos – ~/.claude/agents.
5. Claude no encuentra el agente – reinicia Claude Code.
6. Llámalo por su nombre en tu mensaje, o con @ para asegurarte de que se ejecuta.
7. Los agentes que revisan reciben herramientas de solo lectura; las tareas sencillas, el modelo haiku.
8. Lee tú lo que devuelve el agente: puede añadir cosas que no estaban.
9. Mucho ir y venir y cambios rápidos – quédate en el chat principal, sin agente.
10. Procedimiento repetible contigo dentro – una habilidad. Trabajo pesado en solitario – un subagente.

Fuentes

• Claude Code: Create custom subagents (documentación de Anthropic), consultado el 12 nov 2026
• Claude Code: Extend Claude with skills (documentación de Anthropic), consultado el 12 nov 2026
• Claude pricing (página oficial), consultado el 12 nov 2026
• Anthropic: países y regiones admitidos, consultado el 12 nov 2026