Qué es un subagente
Un subagente es un asistente de IA especializado que trabaja en su propia ventana de contexto, con su propio system prompt, herramientas limitadas y permisos independientes. Según la documentación oficial, sirve para sacar de tu conversación las tareas que generan mucho texto (búsquedas, logs, lectura de archivos) y recibir solo el resumen.
Así tu conversación principal no se llena de ruido y Claude conserva espacio para lo importante.
Crea tu primer subagente
Es un archivo Markdown con una cabecera YAML entre ---. El cuerpo es el system prompt. Guárdalo como .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Revisa código en busca de calidad y buenas prácticas
tools: Read, Glob, Grep
model: sonnet
---
Eres un revisor de código. Al ser invocado, analiza el código y da
retroalimentación específica y accionable sobre calidad, seguridad
y buenas prácticas.Solo son obligatorios name y description. La descripción es lo que Claude lee para decidir cuándo delegar en él. Cuidado con las mayúsculas: los campos son sensibles a ellas (camelCase) y uno mal escrito se ignora sin avisar.
Dónde se guardan
.claude/agents/Proyecto actual. Se puede compartir con git.~/.claude/agents/Todos tus proyectos.Si creas la primera carpeta agents/ con Claude Code ya abierto, reinícialo para que la cargue. A partir de ahí detecta los cambios en pocos segundos.
Cómo usarlo
- En lenguaje natural: «Usa el subagente code-reviewer para revisar mis cambios».
- Con @: escribe
@y elígelo en la lista. - Para toda la sesión: abre Claude Code así.
claude --agent code-reviewerEl comando /agents también existe. En las versiones recientes te recuerda que puedes pedirle a Claude que cree el subagente o editar la carpeta a mano; en la 2.1.197 y anteriores abre un asistente interactivo.
Cuándo no merece la pena
Un subagente compensa para tareas largas que ensucian el contexto. Para una pregunta rápida no hace falta. Dale solo las herramientas que necesita (tools): un revisor, por ejemplo, no tiene por qué poder editar. Para instrucciones que se cargan solo cuando hacen falta, mira las skills. Si aún no usas Claude Code, empieza por instalarlo y por CLAUDE.md.
Esta guía forma parte de Claude Code en español: todas las guías, en orden.
Preguntas frecuentes
¿Qué es un subagente en Claude Code?
Un asistente especializado que trabaja en su propia ventana de contexto, con su prompt y permisos propios, y devuelve a tu conversación solo un resumen.
¿Dónde se guardan los subagentes?
En .claude/agents/ para el proyecto actual o en ~/.claude/agents/ para todos tus proyectos. Son archivos Markdown con cabecera YAML.
¿Qué campos son obligatorios?
Solo name y description. Los demás (tools, model, permissionMode…) son opcionales.
¿Cómo llamo a un subagente?
Pidiéndolo en lenguaje natural, con @ y su nombre, o abriendo la sesión con claude --agent nombre.
¿Para qué sirve el comando /agents?
En versiones recientes recuerda cómo crear o editar subagentes; en la 2.1.197 y anteriores abre un asistente interactivo con las pestañas Running y Library.
