Crear subagentes personalizados

• Preservar contexto manteniendo la exploración e implementación fuera de su conversación principal
• Aplicar restricciones limitando qué herramientas puede usar un subagente
• Reutilizar configuraciones en proyectos con subagentes a nivel de usuario
• Especializar comportamiento con mensajes del sistema enfocados para dominios específicos
• Controlar costos enrutando tareas a modelos más rápidos y económicos como Haiku

​

Subagentes integrados

• Para bloquear un tipo integrado específico, agréguelo a permissions.deny como se muestra en Deshabilitar subagentes específicos.
• Para evitar que Claude delegue a cualquier subagente, deniegue la herramienta Agent en sí con permissions.deny.
• Para eliminar solo los subagentes integrados Explore y Plan, establezca CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude lee y explora archivos directamente en lugar de delegarlos. Requiere Claude Code v2.1.198 o posterior.
• En modo no interactivo y el Agent SDK, establezca CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 para eliminar todos los tipos integrados y proporcionar solo los suyos.

​

Inicio rápido: crear su primer subagente

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Configurar subagentes

​

Elegir el alcance del subagente

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

​

Escribir archivos de subagentes

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

​

Campos de frontmatter soportados

​

Elegir un modelo

• Alias de modelo: Use uno de los alias disponibles: sonnet, opus, haiku, o fable
• ID de modelo completo: Use un ID de modelo completo como claude-opus-4-8 o claude-sonnet-5. Acepta los mismos valores que la bandera --model
• inherit: Use el mismo modelo que la conversación principal
• Omitido: Si no se especifica, por defecto es inherit (usa el mismo modelo que la conversación principal)

1. La variable de entorno CLAUDE_CODE_SUBAGENT_MODEL, cuando está establecida en un alias de modelo o ID de modelo
2. El parámetro model por invocación
3. El frontmatter model de la definición del subagente
4. El modelo de la conversación principal

​

Controlar capacidades de subagentes

​

Herramientas disponibles

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, a menos que el permissionMode del subagente sea plan
• ScheduleWakeup
• WaitForMcpServers

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Restringir qué subagentes pueden ser generados

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Alcance de servidores MCP a un subagente

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config y --bare
• Configuración de MCP administrada empresarial
• Políticas allowedMcpServers y deniedMcpServers

​

Modos de permiso

​

Precargar skills en subagentes

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Habilitar memoria persistente

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• El mensaje del sistema del subagente incluye instrucciones para leer y escribir en el directorio de memoria.
• El mensaje del sistema del subagente también incluye las primeras 200 líneas o 25KB de MEMORY.md en el directorio de memoria, lo que sea menor, con instrucciones para curar MEMORY.md si excede ese límite.
• Las herramientas Read, Write y Edit se habilitan automáticamente para que el subagente pueda administrar sus archivos de memoria.

• project es el alcance predeterminado recomendado. Hace que el conocimiento del subagente sea compartible a través de control de versiones.
• Pida al subagente que consulte su memoria antes de comenzar el trabajo: “Review this PR, and check your memory for patterns you’ve seen before.”
• Pida al subagente que actualice su memoria después de completar una tarea: “Now that you’re done, save what you learned to your memory.” Con el tiempo, esto construye una base de conocimiento que hace que el subagente sea más efectivo.
• Incluya instrucciones de memoria directamente en el archivo markdown del subagente para que mantenga proactivamente su propia base de conocimiento:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Reglas condicionales con hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

​

Deshabilitar subagentes específicos

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Definir hooks para subagentes

• En el frontmatter del subagente: defina hooks que se ejecuten solo mientras ese subagente está activo
• En settings.json: defina hooks que se ejecuten en la sesión principal cuando los subagentes comienzan o se detienen

​

Hooks en frontmatter de subagentes

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hooks a nivel de proyecto para eventos de subagentes

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Trabajar con subagentes

​

Entender delegación automática

​

Invocar subagentes explícitamente

• Lenguaje natural: nombre el subagente en su solicitud; Claude decide si delegar
• @-mention: garantiza que el subagente se ejecute para una tarea
• Sesión completa: toda la sesión usa el mensaje del sistema del subagente, restricciones de herramientas y modelo a través de la bandera --agent o la configuración agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Ejecutar subagentes en primer plano o fondo

• Subagentes en primer plano bloquean la conversación principal hasta completarse. Las solicitudes de permiso se le pasan a usted a medida que surgen.
• Subagentes en fondo se ejecutan concurrentemente mientras continúa trabajando. A partir de v2.1.186, cuando un subagente en fondo alcanza una llamada de herramienta que necesita permiso, la solicitud aparece en su sesión principal y nombra el subagente que está preguntando. Apruebe para permitir que el subagente continúe, o presione Esc para denegar esa llamada de herramienta sin detener el subagente. Antes de v2.1.186, los subagentes en fondo denegaban automáticamente cualquier llamada de herramienta que habría solicitado.

• Pida a Claude que ejecute una tarea en el fondo o en primer plano
• Presione Ctrl+B para poner en fondo una tarea en ejecución

​

Errores de API en subagentes

• Primer plano: si un límite de velocidad, sobrecarga o error de servidor corta un subagente que ya produjo salida, la herramienta Agent devuelve esa salida parcial con una nota de que el subagente fue cortado y no completó su tarea. Un subagente que no produjo nada, o cuya única salida fueron llamadas de herramientas, falla con Agent terminated early due to an API error, seguido del detalle del error. En v2.1.199, un límite de velocidad, sobrecarga o error de servidor que cortó la forma de solo llamadas de herramientas devolvió un resultado parcial vacío que contenía solo la nota de corte en su lugar.
• Fondo: el subagente se marca como fallido, y el mensaje que Claude recibe cuando termina nombra el error de API e incluye la última salida del subagente, por lo que el trabajo parcial no se pierde.

​

Patrones comunes

​

Aislar operaciones de alto volumen

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Ejecutar investigación en paralelo

Research the authentication, database, and API modules in parallel using separate subagents

​

Encadenar subagentes

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Elegir entre subagentes y conversación principal

• La tarea necesita ida y vuelta frecuente o refinamiento iterativo
• Múltiples fases comparten contexto significativo, como planificación, implementación y prueba
• Está haciendo un cambio rápido y dirigido
• La latencia importa. Los subagentes comienzan frescos y pueden necesitar tiempo para recopilar contexto

• La tarea produce salida detallada que no necesita en su contexto principal
• Desea aplicar restricciones de herramientas específicas o permisos
• El trabajo es autónomo y puede devolver un resumen

​

Generar subagentes anidados

​

Administrar contexto de subagentes

​

Qué se carga al inicio

• Mensaje del sistema: el mensaje del agente propio más detalles de entorno que Claude Code añade, no el mensaje del sistema completo de Claude Code. Los subagentes personalizados definen el suyo en el cuerpo markdown o campo prompt. Los agentes integrados tienen mensajes predefinidos.
• Mensaje de tarea: el mensaje de delegación que Claude escribe cuando entrega el trabajo.
• CLAUDE.md y memoria: cada nivel de la jerarquía de memoria que la conversación principal carga, incluyendo ~/.claude/CLAUDE.md, reglas del proyecto, CLAUDE.local.md y archivos de política administrados. Los agentes Explore y Plan integrados omiten esto.
• Estado de Git: una instantánea tomada al inicio de la sesión principal. Ausente cuando el directorio de trabajo no es un repositorio de Git o cuando includeGitInstructions es false. Explore y Plan lo omiten de todas formas.
• Habilidades precargadas: contenido completo de cualquier habilidad nombrada en el campo skills del agente. Los agentes integrados no precargan habilidades.
• Roster de hermanos: un recordatorio del sistema que enumera main y cada otro agente nombrado en la sesión, cada uno un valor to válido para SendMessage. Requiere Claude Code v2.1.206 o posterior. El roster aparece solo cuando las herramientas del subagente incluyen SendMessage y al menos otro agente tiene un nombre, ya sea que Claude lo nombró cuando lo generó o se ejecuta como un compañero de equipo de agentes. Es una instantánea tomada cuando el subagente comienza, por lo que los agentes nombrados más tarde no aparecen.

​

Reanudar subagentes

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Compactación de conversación principal: Cuando la conversación principal se compacta, las transcripciones de subagentes no se ven afectadas. Se almacenan en archivos separados.
• Persistencia de sesión: Las transcripciones de subagentes persisten dentro de su sesión. Puede reanudar un subagente después de reiniciar Claude Code reanudando la misma sesión.
• Limpieza automática: Las transcripciones se limpian basadas en la configuración cleanupPeriodDays, que por defecto es 30 días.

​

Auto-compactación

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Bifurcar la conversación actual

• Claude puede generar un fork solicitando explícitamente el tipo de subagente fork. Los spawns sin un tipo de subagente aún utilizan el subagente general-purpose, y los subagentes nombrados como Explore aún se generan como antes.
• Cada generación de subagente se ejecuta en el fondo, ya sea un fork o un subagente nombrado. Establezca CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1 para mantener los spawns síncronos.

/fork draft unit tests for the parser changes so far

​

Observar y dirigir forks en ejecución

​

Cómo los forks difieren de los subagentes nombrados

​

Limitaciones

​

Subagentes 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 clear 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 the 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.

​

Validador de consultas de base de datos

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Próximos pasos

• Distribuir subagentes con plugins para compartir subagentes entre equipos o proyectos
• Ejecutar Claude Code programáticamente con el Agent SDK para CI/CD y automatización
• Usar servidores MCP para dar a los subagentes acceso a herramientas y datos externos