Subagentes en Claude Code: cómo crearlos y para qué sirven

Un subagente en Claude Code es un asistente especializado que corre en su propia ventana de contexto, con su propio system prompt, sus herramientas y sus permisos. Claude le delega una tarea concreta (buscar en el código, revisar, depurar) y solo recibe de vuelta el resumen, manteniendo tu conversación principal limpia.

La idea es simple: cuando una tarea secundaria generaría un montón de resultados de búsqueda, logs o contenido de archivos que no vas a volver a mirar, ese trabajo lo hace un subagente aparte y te devuelve solo lo que importa.

Para qué sirven (cuándo usarlos)

Los subagentes te ayudan a:

• Preservar contexto: la exploración y el ruido quedan fuera de tu conversación principal.
• Imponer límites: restringes qué herramientas puede usar cada subagente (por ejemplo, uno de solo lectura).
• Especializar: un system prompt enfocado a un dominio concreto.
• Controlar costos: rutear tareas a modelos más rápidos y baratos como Haiku.
• Reutilizar: defines un subagente una vez y lo usas en todos tus proyectos.

La señal de que necesitas uno propio es cuando te encuentras lanzando el mismo tipo de trabajador con las mismas instrucciones una y otra vez.

Ya estás usando subagentes (los integrados)

Claude Code trae subagentes integrados que usa solo cuando conviene:

• Explore: agente rápido de solo lectura para buscar y analizar el código sin modificar nada. Según la documentación usa el modelo de la conversación principal; si quieres que explore con uno más barato, defines tu propio subagente Explore con model: haiku.
• Plan: investiga el código en plan mode para reunir contexto antes de proponer un plan; también de solo lectura.
• General-purpose: agente capaz con acceso a todas las herramientas, para tareas multi-paso que mezclan exploración y cambios.

Por eso a veces ves que Claude "delega" parte del trabajo: ya está repartiendo en subagentes para no ensuciar tu contexto.

Cómo crear uno pidiéndoselo a Claude (lo recomendado)

La forma más cómoda es pedírselo a Claude en la misma sesión. En las versiones actuales, /agents ya no abre un asistente: solo te recuerda que se lo pidas a Claude o que edites .claude/agents/ y ~/.claude/agents/ directamente (el asistente con las pestañas Running y Library quedó en la v2.1.197 y anteriores).

1. Describe el subagente en lenguaje natural y dile dónde guardarlo: ~/.claude/agents/ lo deja disponible en todos tus proyectos; .claude/agents/ lo deja en el proyecto y lo versionas con tu equipo.
2. Indica las herramientas (para un revisor, pide que sea de solo lectura) y el modelo (Sonnet para análisis, Haiku para tareas rápidas y baratas).
3. Claude escribe el archivo con name, description, la lista de tools, el model y el system prompt. Ábrelo y revisa que el frontmatter sea lo que pediste.
4. Úsalo. Claude Code vigila esas carpetas y toma el subagente sin reiniciar; solo hace falta reiniciar si la carpeta agents no existía cuando arrancó la sesión.

Crear uno a mano (formato del archivo)

Un subagente es un archivo markdown con frontmatter YAML + un cuerpo que es su system prompt. Lo guardas en .claude/agents/ (proyecto) o ~/.claude/agents/ (usuario):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
 
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Solo name y description son obligatorios:

• name: identificador único en minúsculas y guiones.
• description: cuándo debe Claude delegar a este subagente. Es lo que Claude lee para decidir si lo usa, así que escríbela clara.
• tools (opcional): las herramientas que puede usar. Si la omites, hereda todas las de la conversación principal.
• model (opcional): sonnet, opus, haiku, fable, un ID completo o inherit. Si lo omites, usa el modelo de la conversación principal, o el de CLAUDE_CODE_SUBAGENT_MODEL si definiste esa variable.

Hay más campos opcionales útiles: disallowedTools, permissionMode, skills, mcpServers (para darle acceso a servidores MCP), memory (memoria persistente entre sesiones) y color. Si editas el archivo a mano, Claude Code detecta el cambio en unos segundos y la siguiente delegación ya usa la versión nueva. Reinicia solo si creaste la carpeta agents después de abrir la sesión o si el subagente vive en un directorio agregado con --add-dir.

Cómo decide Claude a quién delegar

Claude usa la description de cada subagente para decidir cuándo delegarle una tarea automáticamente. Por eso una buena descripción ("Úsalo proactivamente después de cambios de código") es la mitad del trabajo. También puedes invocarlo de forma explícita:

Usa el agente code-reviewer para revisar los cambios de este proyecto.

El subagente recibe solo su system prompt y detalles básicos del entorno (no el system prompt completo de Claude Code), trabaja en su contexto y te devuelve el resultado.

Buenas prácticas

• Descripción precisa: define el "cuándo" como si se lo explicaras a un compañero nuevo.
• Mínimos privilegios: dale solo las herramientas que necesita. Un revisor o un buscador van perfectos en solo lectura.
• Modelo según la tarea: Haiku para búsquedas y tareas mecánicas (rápido y barato); Sonnet u Opus para razonamiento.
• Uno por responsabilidad: subagentes enfocados (revisar, depurar, buscar) funcionan mejor que uno que intenta todo.
• Versiona los de proyecto: guarda los .claude/agents/ en git para que tu equipo los use y mejore.

Subagentes, orquestación y tu setup

Un subagente resuelve una tarea; lo siguiente es orquestar varios que se reparten el trabajo y comparten contexto. Eso ya no es solo Claude Code: ahí entran metaharness como Solo (SoloTerm), que deja a un agente líder lanzar subagentes y coordinarlos vía MCP. Y para que tus subagentes hereden el contexto correcto de tu proyecto, todo arranca en un buen CLAUDE.md.

Preguntas frecuentes