C Claude Code Internals
EN | ES

Agentes Personalizados

Los agentes personalizados son personas de IA especializadas definidas como archivos markdown con frontmatter YAML. Cada agente tiene su propio prompt de sistema, lista de herramientas permitidas, modelo, modo de permisos, servidores MCP, hooks, memoria persistente e identidad de color.

4 tipos de definición 6 niveles de prioridad 3 alcances de memoria 8 colores disponibles
i Un archivo, un agente
Coloca un archivo .md en .claude/agents/ y se convierte inmediatamente en un agente disponible. El frontmatter YAML configura todo — herramientas, modelo, memoria, hooks, MCP — y el cuerpo markdown es el prompt de sistema. No se requiere código.

Tipos de Definición y Prioridad

4 tipos de definición

Tipo Fuente Prompt
Built-in builtInAgents.ts Dinámico (función)
Personalizado .claude/agents/*.md Estático (cuerpo markdown)
Plugin plugin/agents/*.md Estático + sustitución de variables
Flag --agents CLI flag JSON (estático)

Prioridad de descubrimiento (mayor gana)

1 (menor) Built-in code Todos los proyectos
2 Plugin agents/ Ámbito del plugin
3 ~/.claude/agents/ Personal, todos los proyectos
4 <cwd>/.claude/agents/ Proyecto, compartido con equipo
5 --agents CLI flag Solo sesión
6 (mayor) <managed>/.claude/agents/ Toda la empresa

Un agente de proyecto con el mismo nombre que uno built-in lo sobreescribe. CLAUDE_CODE_SIMPLE=true omite todos los agentes personalizados.

Formato del Archivo de Agente

Ubicación: .claude/agents/my-agent.md

---
name: my-agent
description: Usa este agente para revisiones de código.
  Verifica seguridad, rendimiento y buenas prácticas.
tools:
  - Read
  - Grep
  - Glob
  - Bash
disallowedTools:
  - Write
  - Edit
model: opus
color: red
memory: project
maxTurns: 20
---

Eres un revisor de código especializado. Tu trabajo es
revisar cambios de código en busca de vulnerabilidades
de seguridad, problemas de rendimiento y buenas prácticas.

## Directrices

1. Siempre verifica el OWASP top 10
2. Busca patrones N+1 en queries
3. Verifica el manejo de errores

Construcción del prompt de sistema

1. El cuerpo markdown (todo después de ---) se recorta
2. Si memoria habilitada → añadir MEMORY.md + directrices de alcance
3. Para plugins → sustituir ${CLAUDE_PLUGIN_ROOT} y ${user_config.X}
4. Al spawn → envolver con enhanceSystemPromptWithEnvDetails() (OS, shell, CWD, modelo, fecha, notas de agente)
5. Contexto de usuario añadido: jerarquía CLAUDE.md (a menos que omitClaudeMd)
6. Contexto de sistema añadido: git status

Prompt de respaldo por defecto

Si no se define cuerpo, el agente usa DEFAULT_AGENT_PROMPT: un prompt de uso general que instruye al agente a usar las herramientas disponibles, completar la tarea completamente y devolver un informe conciso.

Esquema Completo de Frontmatter

Campos obligatorios

Campo Descripción
name Identificador único → agentType. Usado para selección por subagent_type.
description Texto whenToUse mostrado al modelo. Soporta \n para saltos de línea.

Campos opcionales

Campo Por defecto Valores / Notas
tools Todas String o array. []=ninguna, *=todas
disallowedTools Ninguna Lista de denegación aplicada sobre la lista de permisos
model Heredar sonnet, opus, haiku, inherit, o ID completo
effort Heredar low, medium, high, max
permissionMode Heredar default, acceptEdits, bypassPermissions, dontAsk, plan, auto
color Ninguno red, blue, green, yellow, purple, orange, pink, cyan
maxTurns Sin límite Entero positivo
background false Siempre ejecutar como tarea en segundo plano
initialPrompt Ninguno Antepuesto al primer turno del usuario (uso en hilo principal)
memory Ninguno user, project, local
isolation Mismo CWD worktree — worktree git aislado, limpiado automáticamente
hooks Ninguno Con ámbito de sesión, soporta los 27 eventos
mcpServers Ninguno Referencias a strings o definiciones de servidores inline
skills Ninguno Nombres de skills a precargar (contenido inyectado antes del primer turno)

Configuración de herramientas

Flujo de resolución

1. tools indefinido → todas las herramientas
2. tools: [] → sin herramientas
3. tools: ["*"] → todas las herramientas
4. lista explícita → solo esas herramientas
5. disallowedTools aplicado como denylist encima
6. memoria + lista explícita → auto-inyectar Read, Write, Edit
7. herramientas MCP del agente fusionadas de forma aditiva
8. agentes async → herramientas de tipo UserInput eliminadas
# Agente de solo lectura
tools:
  - Read
  - Grep
  - Glob
disallowedTools:
  - Agent
  - Write
  - Edit
  - Bash

# Herramientas MCP (nombre completo requerido)
tools:
  - Bash
  - Read
  - mcp__github__create_issue
  - mcp__slack__search_public

Servidores MCP y Memoria

Configuración de servidores MCP

Referenciar servidores existentes

mcpServers:
  - slack    # Usa "slack" de configuración user/project
  - github   # Comparte conexión, NO se limpia al terminar

Definición inline

mcpServers:
  - my-api:
      type: http
      url: https://api.example.com/mcp
      headers:
        Authorization: Bearer `${API_TOKEN}`
# Creado para el agente, se limpia al terminar

Mixto

mcpServers:
  - slack                    # referencia
  - custom:                  # inline
      command: node
      args: ["`${plugin_root}`/server.js"]

3 alcances de memoria

Alcance Directorio VCS
user ~/.claude/agent-memory/<name>/ No
project <cwd>/.claude/agent-memory/<name>/ Sí
local <cwd>/.claude/agent-memory-local/<name>/ No

Cómo funciona la memoria

1. Directorio de memoria creado si no existe
2. loadAgentMemoryPrompt() carga el índice MEMORY.md → añadido al prompt de sistema
3. Se añaden directrices específicas del alcance ("mantener aprendizajes generales" para user)
4. Si lista de herramientas explícita → auto-inyectar Read, Write, Edit para que el agente gestione su memoria

Snapshots de memoria (distribución VCS)

Almacenados en <cwd>/.claude/agent-memory-snapshots/<agentType>/. Al cargar: si no hay memoria local pero existe snapshot, copia el snapshot a local. Los equipos pueden hacer commit de snapshots para compartir conocimiento base del agente.

Hooks por Agente

Ejemplo de hooks en frontmatter

---
name: formatter
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "prettier --write \"$(cat | jq -r '.tool_input.file_path')\""
          timeout: 10
          statusMessage: "Formateando..."
  Stop:
    - hooks:
        - type: command
          command: "npm test"
---

Comportamiento

✓ Registrados como hooks de sesión cuando el agente inicia
✓ Limpiados automáticamente cuando el agente termina
✓ Los hooks Stop del agente se convierten automáticamente a SubagentStop
✓ Hooks con ámbito al ID del agente (sin filtración entre agentes)
⚠ Con strictPluginOnlyCustomization, solo fuentes de confianza admin pueden registrar hooks

Los 27 eventos de hook están soportados en el frontmatter del agente.

Invocación de Agentes

Esquema de entrada AgentTool

{
  description: string        // 3-5 palabras (REQUERIDO)
  prompt: string             // Prompt completo de tarea (REQUERIDO)
  subagent_type?: string     // Nombre del agente (default: general-purpose)
  model?: 'sonnet'|'opus'|'haiku'
  run_in_background?: boolean
  name?: string              // Para equipos multi-agente
  team_name?: string
  mode?: PermissionMode      // Override para teammate
  isolation?: 'worktree'
  cwd?: string               // Dir. de trabajo (solo KAIROS)
}

Flujo de ejecución (10 pasos)

1. Resolver definición del agente desde subagent_type
2. Inicializar servidores MCP específicos del agente
3. Construir prompt de sistema (markdown + memoria + detalles de entorno)
4. Cargar contexto usuario/sistema (opcionalmente omitir CLAUDE.md)
5. Configurar override de modo de permisos (si está definido)
6. Registrar hooks del agente (con ámbito al ciclo de vida del agente)
7. Precargar skills (inyectar como mensajes de usuario)
8. Llamar query() con contexto y herramientas del agente
9. Transmitir mensajes conforme llegan
10. Al completar: limpiar servidores MCP, hooks

Fork vs agente nuevo

Aspecto Fork (sin subagent_type) Nuevo (con subagent_type)
Historial Hereda contexto del padre Empieza vacío
Herramientas Conjunto exacto del padre Definidas por el agente
Prompt de sistema Prompt del padre Markdown del agente
Ventana de contexto Compartida con padre Nueva
Propósito Trabajo en segundo plano sin saturar al padre Ejecución especializada

Modos de aislamiento

isolation: worktree — crea un worktree git temporal para el agente. Si no se hacen cambios, el worktree se limpia automáticamente. Si se hacen cambios, se devuelven la ruta y la rama del worktree.
isolation: remote — ejecuta en el Cloud Code Runner de Anthropic (solo ANT-internos).

Restricciones de Plugin y Agentes Integrados

Restricciones de seguridad en agentes plugin

Campo Estado
permissionMode IGNORADO — no puede escalar más allá de la confianza en la instalación
hooks IGNORADO — no puede registrar hooks personalizados
mcpServers IGNORADO — no puede definir servidores MCP
Todos los demás campos Permitidos (name, tools, model, color, etc.)

Los nombres de agentes plugin llevan namespace: pluginName:agentName (ej. my-plugin:test-runner).

Definiciones JSON de agentes (flag --agents)

Todos los campos de frontmatter disponibles como claves JSON. Múltiples agentes por objeto JSON.

Los agentes NO se pueden definir en settings.json — no existe clave agents en el esquema de settings.

Agentes integrados (6)

Agente Modelo Características clave
general-purpose Heredar Todas las herramientas, investigación y tareas multi-paso
Explore Haiku Solo lectura, búsqueda rápida en código, omite CLAUDE.md
Plan Heredar Solo lectura, planificación de arquitectura, omite CLAUDE.md
claude-code-guide Haiku Búsqueda en docs, modo de permisos dontAsk
statusline-setup Sonnet Solo Read + Edit, color naranja
verification Heredar Segundo plano, salida VERDICT, con feature flag, rojo

CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=true deshabilita todos los agentes integrados (solo no interactivo).

Ejemplos Prácticos

Revisor de seguridad (solo lectura, opus)

---
name: security-review
description: Usar para revisiones de seguridad.
  Verifica OWASP top 10, inyección, auth, exposición.
tools: [Read, Grep, Glob, Bash]
disallowedTools: [Write, Edit, Agent]
color: red
model: opus
---

Eres un revisor de código de seguridad...

Agente de despliegue (MCP + maxTurns)

---
name: deployer
description: Usar para desplegar código a staging o prod.
  Requiere deploy-server MCP conectado.
tools: [Bash, Read, Grep]
mcpServers:
  - deploy-server
color: orange
permissionMode: default
maxTurns: 20
---

Eres un especialista en despliegues...

Agente de aprendizaje (memoria user)

---
name: tutor
description: Usar para aprender sobre el código.
  Recuerda lo que el usuario ya ha aprendido.
tools: [Read, Grep, Glob]
memory: user
color: green
effort: high
---

Eres un tutor de código paciente...

Auto-formateador (hooks por agente)

---
name: formatter
description: Usar cuando escribir código que necesita
  auto-formateo después de cada edición.
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "prettier --write \"$(cat | jq -r '.tool_input.file_path')\""
          timeout: 10
---

Escribes código limpio. Prettier formatea automáticamente.

Comando /agents

Interfaz de gestión interactiva

Listar todos los agentes agrupados por fuente (built-in, user, project, plugin)
Ver detalles del agente (prompt, herramientas, configuración)
Crear nuevos agentes mediante asistente paso a paso
Editar agentes existentes user/project
Eliminar agentes user/project

Los agentes built-in y plugin se muestran pero están marcados como no editables.

Asistente de creación de agentes (7 pasos)

1. Selección de nombre
2. Descripción (whenToUse)
3. Edición del prompt de sistema
4. Configuración de herramientas
5. Selección de modelo
6. Selección de color (componente ColorPicker)
7. Ubicación de guardado: user (~/.claude/agents/) o project (.claude/agents/)
i La descripción del agente es crítica para la selección
El campo description es la única señal que usa el modelo para decidir qué agente elegir. Escríbelo como "Usa este agente cuando..." seguido de escenarios específicos y concretos. Las descripciones vagas llevan a una mala selección de agentes. Soporta \n para formato multi-línea en la lista de agentes mostrada al modelo.