Saltar al contenido principal
Los suagentes personalizados en Claude Code son asistentes de IA especializados que pueden ser invocados para manejar tipos específicos de tareas. Permiten una resolución de problemas más eficiente al proporcionar configuraciones específicas de tareas con indicaciones del sistema personalizadas, herramientas y una ventana de contexto separada.

​
¿Qué son los suagentes?

Los suagentes son personalidades de IA preconfiguradas a las que Claude Code puede delegar tareas. Cada suagente:
  • Tiene un propósito específico y un área de experiencia
  • Utiliza su propia ventana de contexto separada de la conversación principal
  • Puede configurarse con herramientas específicas que se le permite usar
  • Incluye un indicador del sistema personalizado que guía su comportamiento
Cuando Claude Code encuentra una tarea que coincide con la experiencia de un suagente, puede delegar esa tarea al suagente especializado, que trabaja de forma independiente y devuelve resultados.

​
Beneficios clave

Preservación del contexto

Cada suagente opera en su propio contexto, evitando la contaminación de la conversación principal y manteniéndola enfocada en objetivos de alto nivel.

Experiencia especializada

Los suagentes pueden ajustarse con instrucciones detalladas para dominios específicos, lo que genera tasas de éxito más altas en tareas designadas.

Reutilización

Una vez creados, los suagentes pueden usarse en diferentes proyectos y compartirse con tu equipo para flujos de trabajo consistentes.

Permisos flexibles

Cada suagente puede tener diferentes niveles de acceso a herramientas, permitiéndote limitar herramientas poderosas a tipos de suagentes específicos.

​
Inicio rápido

Para crear tu primer suagente:
1

Abre la interfaz de suagentes

Ejecuta el siguiente comando:
/agents
2

Selecciona 'Crear nuevo agente'

Elige si deseas crear un suagente a nivel de proyecto o a nivel de usuario
3

Define el suagente

  • Recomendado: Genera con Claude primero, luego personaliza para hacerlo tuyo
  • Describe tu suagente en detalle y cuándo debe usarse
  • Selecciona las herramientas a las que deseas otorgar acceso (o déjalo en blanco para heredar todas las herramientas)
  • La interfaz muestra todas las herramientas disponibles, facilitando la selección
  • Si estás generando con Claude, también puedes editar el indicador del sistema en tu propio editor presionando e
4

Guarda y usa

¡Tu suagente ya está disponible! Claude lo usará automáticamente cuando sea apropiado, o puedes invocarlo explícitamente:
> Usa el suagente code-reviewer para verificar mis cambios recientes

​
Configuración del suagente

​
Ubicaciones de archivos

Los suagentes se almacenan como archivos Markdown con frontmatter YAML en dos ubicaciones posibles:
TipoUbicaciónAlcancePrioridad
Suagentes de proyecto.claude/agents/Disponible en el proyecto actualMás alta
Suagentes de usuario~/.claude/agents/Disponible en todos los proyectosMás baja
Cuando los nombres de suagentes entran en conflicto, los suagentes a nivel de proyecto tienen prioridad sobre los suagentes a nivel de usuario.

​
Agentes de complementos

Los complementos pueden proporcionar suagentes personalizados que se integren sin problemas con Claude Code. Los agentes de complementos funcionan de forma idéntica a los agentes definidos por el usuario y aparecen en la interfaz /agents. Ubicaciones de agentes de complementos: Los complementos incluyen agentes en su directorio agents/ (o rutas personalizadas especificadas en el manifiesto del complemento). Uso de agentes de complementos:
  • Los agentes de complementos aparecen en /agents junto con tus agentes personalizados
  • Pueden invocarse explícitamente: “Usa el agente code-reviewer del security-plugin”
  • Pueden invocarse automáticamente por Claude cuando sea apropiado
  • Pueden gestionarse (verse, inspeccionarse) a través de la interfaz /agents
Consulta la referencia de componentes de complementos para obtener detalles sobre cómo crear agentes de complementos.

​
Configuración basada en CLI

También puedes definir suagentes dinámicamente usando la bandera CLI --agents, que acepta un objeto JSON: 
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Prioridad: Los suagentes definidos por CLI tienen menor prioridad que los suagentes a nivel de proyecto pero mayor prioridad que los suagentes a nivel de usuario. Caso de uso: Este enfoque es útil para:
  • Pruebas rápidas de configuraciones de suagentes
  • Suagentes específicos de sesión que no necesitan guardarse
  • Scripts de automatización que necesitan suagentes personalizados
  • Compartir definiciones de suagentes en documentación o scripts
Para obtener información detallada sobre el formato JSON y todas las opciones disponibles, consulta la documentación de referencia de CLI.

​
Formato de archivo

Cada suagente se define en un archivo Markdown con esta estructura: 
---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sonnet  # Optional - specify model alias or 'inherit'
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
Campos de configuración

CampoRequeridoDescripción
nameSíIdentificador único usando letras minúsculas y guiones
descriptionSíDescripción en lenguaje natural del propósito del suagente
toolsNoLista separada por comas de herramientas específicas. Si se omite, hereda todas las herramientas del hilo principal
modelNoModelo a usar para este suagente. Puede ser un alias de modelo (sonnet, opus, haiku) o 'inherit' para usar el modelo de la conversación principal. Si se omite, usa por defecto el modelo de suagente configurado

​
Selección de modelo

El campo model te permite controlar qué modelo de IA usa el suagente:
  • Alias de modelo: Usa uno de los alias disponibles: sonnet, opus o haiku
  • 'inherit': Usa el mismo modelo que la conversación principal (útil para consistencia)
  • Omitido: Si no se especifica, usa el modelo predeterminado configurado para suagentes (sonnet)
Usar 'inherit' es particularmente útil cuando deseas que tus suagentes se adapten a la elección de modelo de la conversación principal, asegurando capacidades consistentes y estilo de respuesta en toda tu sesión.

​
Herramientas disponibles

Los suagentes pueden tener acceso a cualquiera de las herramientas internas de Claude Code. Consulta la documentación de herramientas para obtener una lista completa de herramientas disponibles.
Recomendado: Usa el comando /agents para modificar el acceso a herramientas - proporciona una interfaz interactiva que lista todas las herramientas disponibles, incluidas las herramientas del servidor MCP conectado, facilitando la selección de las que necesitas.
Tienes dos opciones para configurar herramientas:
  • Omite el campo tools para heredar todas las herramientas del hilo principal (predeterminado), incluidas las herramientas MCP
  • Especifica herramientas individuales como una lista separada por comas para un control más granular (puede editarse manualmente o a través de /agents)
Herramientas MCP: Los suagentes pueden acceder a herramientas MCP de servidores MCP configurados. Cuando se omite el campo tools, los suagentes heredan todas las herramientas MCP disponibles para el hilo principal.

​
Gestión de suagentes

​
Usando el comando /agents (Recomendado)

El comando /agents proporciona una interfaz completa para la gestión de suagentes: 
/agents
Esto abre un menú interactivo donde puedes:
  • Ver todos los suagentes disponibles (integrados, de usuario y de proyecto)
  • Crear nuevos suagentes con configuración guiada
  • Editar suagentes personalizados existentes, incluido su acceso a herramientas
  • Eliminar suagentes personalizados
  • Ver qué suagentes están activos cuando existen duplicados
  • Gestionar fácilmente permisos de herramientas con una lista completa de herramientas disponibles

​
Gestión directa de archivos

También puedes gestionar suagentes trabajando directamente con sus archivos: 
# Crear un suagente de proyecto
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# Crear un suagente de usuario
mkdir -p ~/.claude/agents
# ... crear archivo de suagente

​
Uso efectivo de suagentes

​
Delegación automática

Claude Code delega tareas de forma proactiva basándose en:
  • La descripción de la tarea en tu solicitud
  • El campo description en configuraciones de suagentes
  • El contexto actual y las herramientas disponibles
Para fomentar un uso más proactivo de suagentes, incluye frases como “usar PROACTIVAMENTE” o “DEBE SER USADO” en tu campo description.

​
Invocación explícita

Solicita un suagente específico mencionándolo en tu comando: 
> Usa el suagente test-runner para corregir pruebas fallidas
> Haz que el suagente code-reviewer revise mis cambios recientes
> Pídele al suagente debugger que investigue este error

​
Suagentes integrados

Claude Code incluye suagentes integrados que están disponibles de inmediato:

​
Suagente Plan

El suagente Plan es un agente integrado especializado diseñado para usarse durante el modo de plan. Cuando Claude opera en modo de plan (modo sin ejecución), utiliza el suagente Plan para realizar investigaciones y recopilar información sobre tu base de código antes de presentar un plan. Características clave:
  • Modelo: Usa Sonnet para análisis más capaz
  • Herramientas: Tiene acceso a herramientas Read, Glob, Grep y Bash para exploración de base de código
  • Propósito: Busca archivos, analiza la estructura del código y recopila contexto
  • Invocación automática: Claude usa automáticamente este agente cuando está en modo de plan y necesita investigar la base de código
Cómo funciona: Cuando estás en modo de plan y Claude necesita entender tu base de código para crear un plan, delega tareas de investigación al suagente Plan. Esto evita el anidamiento infinito de agentes (los suagentes no pueden generar otros suagentes) mientras permite que Claude recopile el contexto necesario. Escenario de ejemplo: 
Usuario: [En modo de plan] Ayúdame a refactorizar el módulo de autenticación

Claude: Déjame investigar tu implementación de autenticación primero...
[Internamente invoca el suagente Plan para explorar archivos relacionados con autenticación]
[El suagente Plan busca en la base de código y devuelve hallazgos]
Claude: Basándome en mi investigación, aquí está mi plan propuesto...
El suagente Plan solo se usa en modo de plan. En modo de ejecución normal, Claude usa el agente de propósito general u otros suagentes personalizados que hayas creado.

​
Suagentes de ejemplo

​
Revisor de código

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​
Depurador

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

​
Científico de datos

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​
Mejores prácticas

  • Comienza con agentes generados por Claude: Recomendamos altamente generar tu suagente inicial con Claude y luego iterarlo para hacerlo personalmente tuyo. Este enfoque te da los mejores resultados - una base sólida que puedes personalizar según tus necesidades específicas.
  • Diseña suagentes enfocados: Crea suagentes con responsabilidades únicas y claras en lugar de intentar que un suagente lo haga todo. Esto mejora el rendimiento y hace que los suagentes sean más predecibles.
  • Escribe indicadores detallados: Incluye instrucciones específicas, ejemplos y restricciones en tus indicadores del sistema. Cuanta más orientación proporciones, mejor será el rendimiento del suagente.
  • Limita el acceso a herramientas: Solo otorga herramientas que sean necesarias para el propósito del suagente. Esto mejora la seguridad y ayuda al suagente a enfocarse en acciones relevantes.
  • Control de versiones: Verifica los suagentes de proyecto en el control de versiones para que tu equipo pueda beneficiarse de ellos y mejorarlos colaborativamente.

​
Uso avanzado

​
Encadenamiento de suagentes

Para flujos de trabajo complejos, puedes encadenar múltiples suagentes: 
> Primero usa el suagente code-analyzer para encontrar problemas de rendimiento, luego usa el suagente optimizer para corregirlos

​
Selección dinámica de suagentes

Claude Code selecciona inteligentemente suagentes basándose en el contexto. Haz que tus campos description sean específicos y orientados a la acción para obtener los mejores resultados.

​
Suagentes reanudables

Los suagentes pueden reanudarse para continuar conversaciones anteriores, lo que es particularmente útil para tareas de investigación o análisis de larga duración que necesitan continuarse en múltiples invocaciones. Cómo funciona:
  • Cada ejecución de suagente se asigna un agentId único
  • La conversación del agente se almacena en un archivo de transcripción separado: agent-{agentId}.jsonl
  • Puedes reanudar un agente anterior proporcionando su agentId a través del parámetro resume
  • Cuando se reanuda, el agente continúa con contexto completo de su conversación anterior
Flujo de trabajo de ejemplo: Invocación inicial: 
> Usa el agente code-analyzer para comenzar a revisar el módulo de autenticación

[El agente completa el análisis inicial y devuelve agentId: "abc123"]
Reanuda el agente: 
> Reanuda el agente abc123 y ahora analiza también la lógica de autorización

[El agente continúa con contexto completo de la conversación anterior]
Casos de uso:
  • Investigación de larga duración: Divide el análisis de base de código grande en múltiples sesiones
  • Refinamiento iterativo: Continúa refinando el trabajo de un suagente sin perder contexto
  • Flujos de trabajo de múltiples pasos: Haz que un suagente trabaje en tareas relacionadas secuencialmente mientras mantiene el contexto
Detalles técnicos:
  • Las transcripciones de agentes se almacenan en tu directorio de proyecto
  • La grabación se deshabilita durante la reanudación para evitar duplicar mensajes
  • Tanto los agentes síncronos como asincronos pueden reanudarse
  • El parámetro resume acepta el ID del agente de una ejecución anterior
Uso programático: Si estás usando el Agent SDK o interactuando directamente con AgentTool, puedes pasar el parámetro resume: 
{
  "description": "Continue analysis",
  "prompt": "Now examine the error handling patterns",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from previous execution
}
Mantén un registro de los IDs de agentes para tareas que podrías querer reanudar más tarde. Claude Code muestra el ID del agente cuando un suagente completa su trabajo.

​
Consideraciones de rendimiento

  • Eficiencia de contexto: Los agentes ayudan a preservar el contexto principal, permitiendo sesiones generales más largas
  • Latencia: Los suagentes comienzan con una pizarra limpia cada vez que se invocan y pueden agregar latencia mientras recopilan el contexto que requieren para hacer su trabajo de manera efectiva.

​
Documentación relacionada

  • Complementos - Extiende Claude Code con agentes personalizados a través de complementos
  • Comandos de barra - Aprende sobre otros comandos integrados
  • Configuración - Configura el comportamiento de Claude Code
  • Ganchos - Automatiza flujos de trabajo con manejadores de eventos