Subagentes de Claude Code. Qué son y cómo crear el tuyo

Si has pasado una tarde con Claude Code montando una landing, seguro que lo has notado. Al principio responde rápido y acierta, pero una hora después, con decenas de archivos en el hilo, empieza a olvidar lo que le pediste. Los subagentes de Claude Code existen para sacar ese trabajo fuera de la conversación y que el hilo siga limpio.

A un subagente le encargas una tarea, la resuelve en su propia conversación y te devuelve solo el resultado, así que tu sesión sigue ligera y Claude sigue sabiendo dónde estaba.

Al terminar sabrás qué es exactamente un subagente, cuándo compensa repartir una tarea entre varios y cómo crear el primero sin tocar nada que dé miedo.

Un subagente trabaja en su propia ventana de contexto

Cada vez que hablas con Claude Code, todo lo que ocurre en la conversación entra en su ventana de contexto, su memoria de trabajo, formada por tus mensajes, sus respuestas y cada archivo que abre. Esa memoria tiene un límite y, además, se ensucia.

Si le pides que revise los cincuenta textos de tu web, los cincuenta entran enteros en el hilo y ahí se quedan aunque ya no los necesites. A eso se le llama contaminación de contexto, y un subagente lo evita porque tiene cuatro cosas propias, según la documentación oficial.

• Su propia ventana de contexto, así que lo que lee no ocupa sitio en la tuya.
• Su propio mensaje del sistema, es decir, las instrucciones que le dicen cómo trabajar.
• Sus propias herramientas, solo las que tú le permitas.
• Sus propios permisos, independientes de los del hilo principal.

Con esas cuatro cosas aparte, el trabajo pesado ocurre en otra habitación y a tu conversación solo llega el resumen. Eso sí, el subagente vive dentro de tu sesión y solo le reporta a Claude. No lo confundas con un equipo de agentes, otra función de Claude Code en la que varias sesiones separadas se coordinan entre sí.

Claude Code ya trae subagentes que usas sin saberlo

Vienen de serie con Claude Code y se lanzan solos cuando toca, sin que tengas que pedírselo a Claude. La terminal es la ventana de texto en la que le das órdenes a Claude Code, y si ya has escrito alguna ahí, alguno de estos subagentes ha trabajado para ti sin que lo configuraras.

El más habitual es Explore, al que Claude manda a mirar cuando le pides algo sobre tu proyecto y necesita entender qué hay en las carpetas antes de tocar nada, y al hilo principal solo vuelve lo que ha encontrado.

Son seis en total, los tienes en la tabla, y verás que dos llevan un modelo fijo. El modelo es la versión de Claude que hace el trabajo, y hay varias, así que fijar uno para un subagente es la misma decisión que tomas al elegir entre Claude Sonnet y Opus para tu chat, rapidez y precio frente a capacidad de razonar.

Tareas que es mejor no dividir

Son tareas de ida y vuelta, donde cada paso depende de lo que decidiste en el anterior. Un subagente arranca sin saber nada de tu conversación, así que recopilar ese contexto le costaría más de lo que ahorra.

• Ajustar el diseño de una landing. Tocas un color, miras, tocas el espaciado. Cada paso necesita conocer el anterior, y el hilo principal ya lo tiene.
• Conectar un formulario con una base de datos. Los campos, la tabla y la validación van juntos, y repartirlo obliga a explicar tres veces lo mismo.
• Un retoque rápido en un texto. Pedírselo a un subagente tarda más que hacerlo, porque tiene que arrancar y situarse antes de escribir una frase.
• Automatizar un proceso de negocio que todavía estás definiendo. Mientras las reglas cambian a cada mensaje, el contexto compartido es justo lo que necesitas.

Crea tu primer subagente paso a paso

Crear un subagente es escribir un archivo de texto con extensión .md, igual que personalizas la herramienta al configurar hooks en Claude Code. Puede vivir en dos carpetas. En .claude/agents/, dentro del proyecto, solo existe para ese proyecto. En ~/.claude/agents/, tu carpeta de usuario, lo tienes en todos.

Empieza con un frontmatter, la cabecera entre guiones del ejemplo, y sigue con las instrucciones. Solo name y description son obligatorios, el identificador en minúsculas con guiones y cuándo delegar en él. Entre los opcionales, tools limita las herramientas y model elige el modelo por su alias, o inherit para usar el del hilo principal.

---
name: investigador-herramientas
description: Compara herramientas no-code para una idea concreta y devuelve una recomendación razonada. Úsalo de forma proactiva cuando el usuario pregunte qué herramienta usar o pida alternativas a una que ya conoce.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
---

Eres un investigador de herramientas no-code. Cuando recibas una idea de producto, busca tres o cuatro herramientas que sirvan para construirla y compáralas por precio, curva de aprendizaje y límites del plan gratuito.

Devuelve una tabla con la comparación y una recomendación final de una sola frase. No copies textos de marketing: resume con tus palabras y cita la fuente de cada precio.


Un aviso, porque muchos tutoriales te dirán que escribas el comando /agents para abrir un asistente que te guía paso a paso. Desde la versión 2.1.198 ese asistente ya no existe y el comando solo te recuerda que se lo pidas a Claude o edites la carpeta .claude/agents/ a mano.

Elige la tarea que quieres delegar

Vuelve a la lista de tareas que ganan al dividirse y quédate con una, por ejemplo investigar herramientas o revisar todas las páginas de una web. Escribe en una frase qué tiene que hacer y qué tiene que devolverte.

Sabes que has elegido bien si esa frase cabe en una línea y el resultado es algo concreto, una tabla, una lista de fallos, un resumen. Si necesitas tres condiciones y dos excepciones, va mejor en el hilo principal.

Pídele el subagente a Claude

Abre Claude Code y descríbelo en lenguaje normal, por ejemplo con "crea un subagente llamado investigador-herramientas en ~/.claude/agents/ que compare herramientas no-code para una idea y devuelva una tabla con tres opciones y una recomendación".

Claude escribe el archivo con su name, su description, una lista de tools, un model y las instrucciones del cuerpo. Al terminar te confirma la ruta y, si abres la carpeta, el .md está ahí con ese nombre.

Revisa el archivo generado

Abre el archivo con un editor de texto y lee el frontmatter con calma, porque la description es lo que más importa y tiene que decir en qué situaciones usarlo, no qué es. Si describe la tarea en abstracto, Claude no sabrá cuándo delegar.

Mira también que tools se limite a lo que la tarea necesita, que model sea el que quieres pagar y que las instrucciones del cuerpo fijen el formato de la respuesta. Con esas tres cosas en su sitio, el archivo está listo para probarlo.

Pruébalo con un encargo real

Pídele a Claude una tarea real, la que apuntaste en el primer paso, sin mencionar todavía el subagente. Si delega solo, la descripción funciona, y si hace el trabajo él mismo, llámalo tú escribiendo @ y su nombre, y anota que la descripción necesita un retoque.

Ha salido bien si Claude te indica que está delegando y, al terminar, en tu hilo aparece solo el resultado. Si dice que no encuentra el subagente porque la carpeta ~/.claude/agents/ no existía al abrir la sesión, reinicia Claude Code y prueba otra vez.

Llama tú al subagente cuando Claude no lo elige solo

Claude decide a quién delegar leyendo la description de cada subagente, junto con lo que le pides y el contexto de la conversación. De ahí que la documentación recomiende frases como "úsalo de forma proactiva". Si aun así no lo elige, tienes tres maneras de llamarlo, y no todas garantizan lo mismo.

• Nombrarlo en lenguaje natural. Con algo como "usa el subagente revisor-textos para repasar la página de inicio". No hay sintaxis especial y Claude normalmente delega, pero es una propuesta y puede hacerlo él mismo.
• Mencionarlo con arroba. Escribiendo @ y eligiéndolo de la lista que aparece, o tecleando @agent-revisor-textos. Esto sí garantiza que se ejecute ese subagente y no otro.
• Fijarlo al arrancar. Con claude --agent revisor-textos desde la terminal, cuando toda la sesión va a ser esa tarea. El hilo principal toma entonces las instrucciones, herramientas y modelo del subagente.

Para que se vea la diferencia entre una descripción que se activa sola y otra que no, compara estas tres.

• "Ayudante para textos de webs". No dice cuándo, así que Claude nunca sabrá que le toca, y tendrás que llamarlo siempre con arroba.
• "Revisa ortografía, tono y enlaces rotos en los textos de una web. Úsalo de forma proactiva cuando el usuario pida repasar o publicar una página". Se activa sola en cuanto pides revisar algo.
• "Compara herramientas no-code para una idea. Úsalo cuando el usuario pregunte qué elegir". Se activa solo ante esa consulta directa, no cuando nombras una herramienta de pasada.

Los errores que echan a perder un subagente

Cuando un subagente no responde como esperabas, casi siempre falla por cómo está escrito el archivo, y alguna vez por la tarea que le has dado. Las dos cosas se arreglan en dos minutos si sabes dónde mirar.

• Una descripción vaga. Se nota porque Claude nunca lo lanza solo y acabas llamándolo siempre con arroba. Reescribe description con los casos concretos en los que debe activarse y añade que lo use de forma proactiva.
• Delegarle tareas que no compensan. Se nota porque tarda más que si lo hubieras hecho en el hilo y encima vuelve pidiendo contexto. Devuelve al hilo principal las tareas de ida y vuelta.
• No limitarle las herramientas. Se nota cuando un subagente que solo debía leer y resumir ha modificado archivos por su cuenta. Añade tools con lo justo, Read, Grep y Glob bastan para uno de solo lectura.
• Darle instrucciones demasiado escuetas. Se nota en que cada vez devuelve el resultado en un formato distinto o se salta partes. Amplía el cuerpo del archivo con qué mirar, en qué formato devolverlo y qué tiene prohibido.

‍

Los subagentes de Claude Code son ayudantes con ventana de contexto, instrucciones, herramientas y permisos propios, que hacen el trabajo ruidoso fuera de tu conversación y devuelven un resumen. Compensan cuando la tarea genera mucho volumen o se parte en piezas independientes, y el primer paso es elegir una y pedirle a Claude el archivo.

Si quieres construir tus propios productos con esta herramienta, en el curso gratuito de Vibe Coding con Claude Code aprendes a montar tu primera aplicación solo describiéndola. Empieza gratis y convierte tus ideas en productos.