Crear un subagente

Crear un subagente

La forma más fácil de crear un subagente es pedirle a Claude que lo escriba por ti. Describe el subagente que quieres y dónde guardarlo, y Claude escribe el archivo. El video y las primeras tres capturas de pantalla de esta lección muestran el asistente /agents, que se eliminó en Claude Code v2.1.198. El archivo del subagente y sus campos no han cambiado, así que sigues eligiendo un alcance, herramientas, un modelo y un color. Incluye esas elecciones en tu solicitud.

Primero, elige el alcance de tu subagente. Un archivo en .claude/agents/ es a nivel de proyecto, y un archivo en ~/.claude/agents/ es a nivel de usuario:

• A nivel de proyecto -- disponible solo en el proyecto actual
• A nivel de usuario -- compartido en todos los proyectos de tu máquina

A continuación, puedes elegir cómo crearlo. Puedes escribir la configuración manualmente, pero el enfoque recomendado es dejar que Claude la genere por ti. Solo describe lo que quieres que haga el subagente, y Claude producirá un nombre, una descripción y una indicación del sistema basados en tu entrada.



Personalizar herramientas

Durante la creación, tienes la oportunidad de personalizar a qué herramientas puede acceder el subagente. Las categorías de herramientas incluyen:

• Herramientas de solo lectura
• Herramientas de edición
• Herramientas de ejecución
• Herramientas MCP
• Otras herramientas



Piensa en lo que realmente necesita tu subagente. Es probable que un revisor de código no necesite herramientas de edición: debe leer y analizar código, no cambiarlo. Sin embargo, podrías querer mantener habilitadas las herramientas de ejecución para que pueda identificar más fácilmente los cambios pendientes.

Elegir un modelo y un color

Después de configurar las herramientas, seleccionas qué modelo de Claude impulsa al subagente. Tus opciones incluyen:

• Haiku -- ideal para tareas rápidas y ligeras
• Sonnet -- un buen punto intermedio entre velocidad y profundidad
• Opus -- ideal para análisis complejos
• Inherit -- usa el modelo que esté ejecutando tu conversación principal

Finalmente, eliges un color. Esto aparece en la interfaz para que puedas identificar rápidamente qué subagente está activo. Es un detalle pequeño, pero ayuda cuando tienes varios subagentes en ejecución.



El archivo de configuración

Una vez completada la creación, el archivo de configuración del subagente se guarda en la carpeta correspondiente al alcance que elegiste (para un subagente a nivel de proyecto, normalmente .claude/agents/your-agent-name.md). Así es como se ve una configuración típica de subagente:

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

Desglosemos cada campo:

• name -- Un identificador único para el subagente. Así es como lo referencias, ya sea pidiéndoselo directamente a Claude o escribiendo @agent-code-quality-reviewer en tu mensaje.
• description -- Controla cuándo Claude decide usar el subagente. Debe ser una sola línea (usa caracteres de salto de línea escapados \n si necesitas saltos). Puedes incluir conversaciones de ejemplo aquí para ayudar a Claude a entender cuándo es apropiado delegar.
• tools -- Enumera a qué herramientas puede acceder el subagente. Claude completa esto a partir de tu solicitud, pero puedes editar la lista aquí en cualquier momento.
• model -- Especifica qué modelo de Claude usar: un alias (sonnet, opus, haiku o fable), un ID de modelo completo como claude-sonnet-5, o inherit.
• color -- El color de la interfaz para identificar al subagente.

Indicaciones del sistema

El cuerpo del archivo markdown (todo lo que está debajo del frontmatter YAML) es la indicación del sistema. Aquí es donde le das al subagente sus instrucciones: en qué debe enfocarse, cómo debe analizar las cosas y cómo debe reportar los hallazgos al agente principal.

Una indicación del sistema bien escrita marca la diferencia entre un subagente útil y uno que no da en el blanco. Sé específico sobre qué debe buscar el subagente y cómo debe estructurar su salida.

Hacer que Claude use tu subagente automáticamente

Si quieres que Claude delegue tareas al subagente sin que se lo pidas explícitamente, incluye la palabra "proactively" en el campo description. Por ejemplo:

description: Proactively suggest running this agent after major code changes...

También puedes agregar conversaciones de ejemplo a la descripción para ayudar a Claude a entender escenarios específicos en los que se debe usar el subagente. Cuanto más concretos sean tus ejemplos, mejor se le dará a Claude saber cuándo delegar.

Probar tu subagente

Después de crear tu subagente, pruébalo haciendo algunos cambios de código y pidiéndole a Claude que los revise. Si la carpeta agents no existía cuando comenzó tu sesión, reinicia Claude Code primero para cargar el nuevo subagente.



Si el subagente no se está usando cuando esperas que lo haga, vuelve atrás y revisa la descripción. Agregar ejemplos y escenarios desencadenantes más específicos ayuda a Claude a entender cuándo delegar trabajo a tu subagente.