Generador de subagentes de Claude Code
Describe una tarea única y bien definida que quieras delegar - revisar PRs en busca de fallos de seguridad, escribir pruebas unitarias, investigar cómo funciona algo en una base de código - y obtén un archivo .claude/agents/<nombre>.md completo listo para colocar directamente en Claude Code. La IA redacta el contenido; el nombre, el encabezado YAML y la lista de herramientas permitidas se verifican frente a las reglas reales de los subagentes mientras editas, y una descripción de solo lectura que incluye herramientas capaces de escribir se marca automáticamente.
1. Describe la tarea que quieres delegar
Un lenguaje sencillo está bien. Piensa en una porción de trabajo bien definida que le confiarías con gusto a un especialista, del que solo leerías el resumen - eso es exactamente para lo que sirve un subagente.
O empieza desde uno de estos
Tu .claude/agents/<name>.md aparecerá aquí, totalmente editable, con el nombre y la descripción comprobados frente a las restricciones reales de los subagentes mientras escribes.
Lo que realmente contiene un archivo de subagente
Un subagente es un único archivo markdown: frontmatter YAML arriba, un cuerpo markdown abajo. El cuerpo no es una pista ni un añadido - es el system prompt completo del subagente, que sustituye al de Claude Code por defecto durante todo el tiempo que se ejecute ese subagente. También arranca en su propia ventana de contexto, sin que se traslade nada de tu conversación actual, así que todo lo que necesite saber tiene que estar escrito en ese cuerpo.
Solo dos campos del frontmatter son obligatorios. name usa solo letras minúsculas y guiones, no contiene dos puntos, y debe ser único entre tus subagentes - es el nombre del archivo y cómo invocas al subagente a mano. description es el campo que merece que te lo pienses bien, porque es el único texto que Claude lee para decidir qué subagente debe recibir una tarea. Dos subagentes con descripciones vagas se robarán el trabajo entre sí.
Todo lo demás es opcional, y este generador conecta realmente cada uno de ellos en el archivo: tools (una lista blanca separada por comas - omítela para heredar todas las herramientas), disallowedTools (la lista negra), model (sonnet, opus, haiku, fable, un ID de modelo completo, o inherit), permissionMode, maxTurns (un tope de turnos agénticos antes de que se detenga y devuelva una salida parcial), skills (nombres de skills precargados en su contexto) y color, que es solo visual.
Lo más valioso que puedes hacer con esa lista es mantener tools acotado. Un revisor de código que solo tiene Read, Glob, Grep no puede reescribir tu rama mientras «ayuda», sin importar cómo vaya la conversación. Esta herramienta verifica la lista blanca contra lo que dice tu descripción sobre la función del subagente, y marca una tarea de solo lectura a la que de alguna forma se le haya dado Write, Edit o Bash.
Preguntas frecuentes
¿Qué es exactamente un subagente de Claude Code?
Un subagente es una instancia especializada de Claude que se ejecuta en su propia ventana de contexto separada con un system prompt diferente, de modo que puedes delegarle una subtarea bien definida y recibir solo el resumen. Se define mediante un único archivo markdown en .claude/agents/<nombre>.md: un encabezado YAML con un nombre y una descripción arriba, y un cuerpo que se convierte en el system prompt completo de ese subagente. Como trabaja en un contexto aislado, la larga y desordenada exploración que realiza - leer cincuenta archivos, ejecutar greps, seguir pistas muertas - nunca llega a tu conversación principal. Solo llega su informe final. Ese aislamiento es todo el propósito: mantiene tu contexto principal limpio, y permite darle a una tarea estrecha y potencialmente peligrosa si se usa mal un conjunto igualmente estrecho de herramientas.
Agentes vs skills en Claude Code - ¿cuál es la diferencia?
Una skill carga instrucciones en la conversación que ya estás teniendo; un subagente inicia una conversación completamente nueva. Cuando se activa una skill, el cuerpo de su SKILL.md se añade al contexto actual de Claude, y Claude sigue trabajando como él mismo, con todo lo que ya sabía. Cuando se activa un subagente, Claude genera una instancia separada con un contexto en blanco y un system prompt diferente, esa instancia trabaja sola, y solo vuelve su mensaje final. Así que recurre a una skill cuando quieras enseñarle a Claude a hacer algo que luego hará aquí mismo - un estilo propio, una checklist, un procedimiento de lanzamiento. Recurre a un subagente cuando quieras que el trabajo se haga en otro lugar y solo quieras la conclusión: una búsqueda grande que no quieres que llene tu contexto, o una revisión que quieras que realice algo que literalmente no puede editar tus archivos. Un comando slash es una tercera cosa, aún más simple: un prompt guardado que activas escribiendo /nombre, ejecutado en línea, sin aislamiento y sin identidad propia.
¿Cómo creo un subagente en Claude Code?
Crea la carpeta con mkdir -p .claude/agents, guarda en ella un archivo markdown con el nombre del subagente, y recarga Claude Code. El archivo necesita un encabezado YAML con al menos name (solo letras minúsculas y guiones, sin dos puntos, único) y description (cuándo Claude debe delegarle), seguido del cuerpo que actúa como su system prompt. Colócalo en .claude/agents/ dentro del repositorio para hacer commit en git y compartirlo con tu equipo, o en ~/.claude/agents/ en tu carpeta personal para mantenerlo personal en todos tus proyectos. Si ambos existen con el mismo nombre, gana el del proyecto dentro de ese repositorio. Este generador escribe todo el archivo por ti y muestra la ruta exacta y el comando mkdir para el ámbito que elijas.
¿Por qué importa tanto la lista de herramientas permitidas?
Porque es el único límite estricto sobre lo que puede hacer un subagente. Si omites tools, el subagente hereda todo lo que tiene la conversación principal, incluidas las herramientas MCP - está bien para un ayudante de confianza, innecesariamente arriesgado para uno cuyo único trabajo es mirar e informar. Un revisor de seguridad con Read, Glob, Grep no puede modificar físicamente tu árbol de trabajo; el mismo revisor con Bash y Write sí puede. La regla general es el mínimo privilegio: otorga lo mínimo necesario para el trabajo, añade Write y Edit solo para un subagente que deba cambiar archivos, y añade Bash solo cuando genuinamente tenga que ejecutar algo como una suite de pruebas. Este creador señala el desajuste en ambos sentidos - una descripción de revisión con herramientas de escritura, y una descripción de corrección sin forma de escribir nada.
¿Cómo decide Claude qué subagente usar?
Compara la tarea con la descripción de cada subagente, así que esa cadena es tu tabla de enrutamiento. Una descripción como 'Revisa código' no le da a Claude nada para discriminar y será elegida para todo o para nada. En su lugar, nombra los disparadores concretos: 'Revisa el código modificado en busca de vulnerabilidades de seguridad - inyección, falta de autorización, deserialización insegura, secretos filtrados. Úsalo proactivamente después de cualquier cambio en la autenticación o el manejo de entradas, y cada vez que el usuario pida una revisión de seguridad.' Decir 'usar proactivamente' fomenta la delegación automática; siempre puedes anularlo pidiendo uno por nombre - 'usa el subagente security-code-reviewer para revisar este diff'. En una configuración multiagente donde varios subagentes se solapan, las descripciones necesitan trazar límites claros entre ellos, por eso este generador advierte en vivo cuando la tuya suena genérica o le falta la parte del 'cuándo'.
Dos herramientas complementarias a esta: el Claude Skill Generator escribe un SKILL.md que carga instrucciones en la conversación en la que ya estás, y el AI Slash Command Generator escribe la versión de archivo único en /command.