--- title: "Subagentes en Claude Code: cómo crearlos y para qué sirven" excerpt: "Qué es un subagente en Claude Code, para qué sirve, cómo crear uno con /agents o a mano, y buenas prácticas para delegar tareas sin ensuciar tu contexto." date: "2026-06-29T13:00:00.000Z" category: "Inteligencia Artificial" tech_article: true author: name: "angel cruz" picture: "https://angelcruzdevcdn.nyc3.cdn.digitaloceanspaces.com/images/me/angel-cruz.png" ogImage: url: "/images/open-graph/og-image.png" seo_title: "Subagentes en Claude Code: tutorial y buenas prácticas" seo_description: "Qué es un subagente en Claude Code, para qué sirve y cómo crear uno con /agents o a mano (name, description, tools, model). Tutorial en español." --- 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**: restringís 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** (corre en Haiku) para buscar y analizar el código sin modificar nada. - **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 con /agents (lo recomendado) La forma más cómoda es el comando `/agents`, que abre una interfaz para gestionarlos: 1. Corre `/agents` en Claude Code. 2. En la pestaña **Library**, elige **Create new agent** y el alcance (**Personal** lo guarda en `~/.claude/agents/`, disponible en todos tus proyectos; **Project** lo guarda en `.claude/agents/` y lo versionas con tu equipo). 3. Elige **Generate with Claude** y describe el subagente en lenguaje natural. Claude genera el identificador, la descripción y el system prompt. 4. Selecciona las **herramientas** (para un revisor de solo lectura, deja solo las de lectura) y el **modelo** (Sonnet para análisis, Haiku para tareas rápidas y baratas). 5. Guarda. Queda disponible de inmediato, sin reiniciar 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): ```markdown --- 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` (por defecto). Hay más campos opcionales útiles: `disallowedTools`, `permissionMode`, `skills`, `mcpServers` (para darle acceso a [servidores MCP](/post/como-crear-un-servidor-mcp)), `memory` (memoria persistente entre sesiones) y `color`. Ojo: si editas el archivo a mano, reinicia la sesión para que lo cargue; los creados vía `/agents` se cargan al instante. ## 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: ```text 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)](/post/soloterm-workspace-agentes-ia), 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](/post/claude-md-buenas-practicas). ## Preguntas frecuentes ### ¿Qué es un subagente en Claude Code? Es un asistente especializado que corre en su propia ventana de contexto, con system prompt, herramientas y permisos propios. Claude le delega una tarea y recibe solo el resumen, sin llenar la conversación principal de ruido. ### ¿Dónde se guardan los subagentes? En `.claude/agents/` para los del proyecto (versionados en git) o en `~/.claude/agents/` para los personales, disponibles en todos tus proyectos. También se pueden definir por sesión con el flag `--agents`. ### ¿Cómo creo un subagente? Lo más fácil es el comando `/agents`, que te guía y hasta genera el system prompt con Claude. También puedes crear el archivo markdown a mano con frontmatter (`name`, `description`, y opcionalmente `tools` y `model`). ### ¿Cómo decide Claude cuándo usar un subagente? Por la `description` de cada subagente: si la tarea encaja, delega automáticamente. También puedes invocarlo a mano ("usa el agente X para..."). ### ¿Puedo limitar qué herramientas usa un subagente? Sí, con el campo `tools` (las que puede usar) o `disallowedTools` (las que se le niegan). Es la forma de tener, por ejemplo, un revisor de solo lectura. --- ## Sitemap Índice completo del sitio: [/sitemap.md](https://www.angelcruz.dev/sitemap.md) Canónico HTML: [https://www.angelcruz.dev/post/subagentes-claude-code](https://www.angelcruz.dev/post/subagentes-claude-code)