Escribe tu primer subagente de Claude Code

Un subagente es un ayudante que trabaja en su propia ventana de contexto y devuelve un resumen. Es un archivo Markdown normal, así que puedes escribir uno en cinco minutos.

Cuándo conviene un subagente

Úsalo cuando una tarea lateral llenaría tu conversación con salida que no vas a volver a mirar: pasar una batería de tests, buscar en muchos archivos, revisar un diff. Solo vuelve el resumen. Si no tienes claro si quieres un subagente, una skill o un hook, lee antes cuál necesitas.

Dónde va el archivo

• .claude/agents/ dentro de un proyecto: solo ese proyecto, y puedes subirlo a git para que lo tenga tu equipo.
• ~/.claude/agents/: todos tus proyectos, solo en tu máquina.

Si dos subagentes tienen el mismo nombre, gana el que está en el sitio de mayor prioridad, y la carpeta del proyecto gana a la personal. Claude Code mira también dentro de subcarpetas. El nombre sale del campo name del archivo, no del nombre del archivo ni de la ruta.

Un ejemplo para pegar

Guárdalo como .claude/agents/test-runner.md:

---
name: test-runner
description: Runs the project's tests and reports only the failures. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: haiku
---

You run the project's test suite and report back.

1. Find the test command in the project files. If there are several, pick the main one and say which.
2. Run it once.
3. Report: how many passed, how many failed, and for each failure the test name, the error line and the file.
4. Do not edit any file. Do not try to fix anything.
5. If the tests cannot run, say why in one line.

Lo que va entre las rayas es la configuración. Todo lo de después son las instrucciones del subagente. Solo name y description son obligatorios. El ejemplo está en inglés a propósito: las instrucciones del archivo puedes escribirlas en el idioma que prefieras.

Los campos que más importan

• descriptionLo que lee Claude para decidir cuándo pasarle trabajo a este subagente. Di con claridad cuándo usarlo. Una frase como «use proactively» anima a Claude a delegar por su cuenta.
• toolsUna lista de permitidas. Si no la pones, el subagente puede usar todas las herramientas disponibles para subagentes. Un revisor de solo lectura debería listar solo las herramientas de lectura.
• disallowedToolsUna lista de prohibidas, que se aplica antes que la de permitidas.
• modelsonnet, opus, haiku, un ID de modelo completo o inherit. Para un trabajo mecánico suele bastar un modelo pequeño.
• maxTurnsPara al subagente tras ese número de turnos; es una protección barata contra un ayudante que se pierde.
• skillsSkills cuyo texto completo se carga en el subagente al arrancar.
• permissionModeCómo trata los avisos de permiso. Déjalo quieto hasta que sepas por qué lo necesitas.

Hay más campos, entre ellos memory, background e isolation. Claude Code ignora sin avisar un campo que no reconoce, así que una errata no hace nada. Revisa la ortografía, con las mayúsculas.

Cómo llamarlo

• Deja que Claude lo elija. Claude compara tu petición con cada descripción.
• Pídelo por su nombre. «Usa el subagente test-runner con los cambios de autenticación.»
• Usa @. Escribe @ y elige el subagente de la lista.
• Haz que toda la sesión sea él. claude --agent test-runner.

Qué sabe y qué no

Un subagente empieza con un contexto limpio. No ve tu conversación ni los archivos que Claude ya leyó. Recibe sus propias instrucciones, la tarea que Claude le escribe, tus archivos CLAUDE.md y las skills que le hayas puesto. Así que mete en la tarea todo lo que necesite y mantén cortas y concretas las instrucciones del archivo.

Vienen tres subagentes de serie: Explore y Plan, que son de solo lectura, y uno de propósito general que puede usar todas las herramientas.

Límites

• Las descripciones se cargan en el contexto de Claude para que pueda elegir. Anthropic avisa al arrancar cuando las de tus subagentes suman unos 15.000 tokens, así que mantén cada una breve y deja el detalle en el cuerpo del archivo.
• Un subagente que solo tiene Read, Glob y Grep no puede cambiar archivos. Eso es un límite real, a diferencia de una línea que diga «no edites».
• No confíes en un subagente para nada donde una respuesta equivocada salga cara. Lee lo que te cuenta.

Comprueba que funciona

1. Guarda el archivo en .claude/agents/ de un proyecto de pruebas. La mayoría de los cambios se recogen sin reiniciar.
2. Pídelo por su nombre en un proyecto que tenga algunos tests.
3. Compara el resumen con lo que ves al pasar tú mismo los tests.

Esta página sigue la documentación de subagentes de Anthropic tal como la leemos en octubre de 2026. Esa página manda, y no tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado el ejemplo en todos los sistemas.

Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).