Agentes custom

Estructura de un agente custom

Los agentes custom de Claude Code se definen como archivos markdown con metadatos en formato YAML (frontmatter). El frontmatter configura el comportamiento del agente (nombre, herramientas, modelo, permisos) y el cuerpo del archivo contiene el prompt de sistema que guía su comportamiento.

Un agente custom mínimo tiene esta estructura:

---
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.

El campo name identifica al agente de forma única. El campo description es lo que Claude lee para decidir cuándo delegar una tarea a ese agente. Si la descripción incluye frases como "use proactively", Claude lo invocará de forma proactiva cuando detecte tareas que coincidan con el perfil.

El prompt de sistema del agente (el cuerpo del archivo markdown) es lo único que recibe el subagente como instrucciones iniciales, junto con información básica del entorno como el directorio de trabajo. No hereda el prompt de sistema completo de Claude Code, sino que opera con sus propias instrucciones.

Campos del frontmatter

El frontmatter YAML admite los siguientes campos de configuración:

| Campo | Obligatorio | Descripción | |---|---|---| | name | Sí | Identificador único en minúsculas y guiones | | description | Sí | Cuándo debe Claude delegar a este agente | | tools | No | Herramientas permitidas (hereda todas si se omite) | | disallowedTools | No | Herramientas denegadas explícitamente | | model | No | Modelo a usar: sonnet, opus, haiku o inherit | | permissionMode | No | Modo de permisos: default, acceptEdits, dontAsk, plan | | maxTurns | No | Número máximo de turnos antes de detenerse | | skills | No | Skills que se inyectan en el contexto al inicio | | mcpServers | No | Servidores MCP disponibles para el agente | | hooks | No | Hooks del ciclo de vida del agente | | memory | No | Ámbito de memoria persistente: user, project o local | | background | No | Si es true, se ejecuta siempre en segundo plano | | isolation | No | Si es worktree, se ejecuta en un worktree de Git aislado |

Control de herramientas

El campo tools actúa como lista de herramientas permitidas. Si se omite, el agente hereda todas las herramientas de la conversación principal, incluidas las herramientas MCP. Si se especifica, el agente solo tiene acceso a las herramientas listadas.

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

El campo disallowedTools complementa a tools: permite especificar herramientas a denegar, que se eliminan de la lista heredada o especificada. Ambos campos pueden usarse juntos para un control granular.

Selección de modelo

El campo model controla qué modelo utiliza el subagente:

• sonnet: equilibrio entre capacidad y velocidad, adecuado para la mayoría de tareas.
• opus: máxima capacidad de razonamiento, útil para tareas complejas.
• haiku: rápido y económico, ideal para tareas de lectura y búsqueda.
• inherit (valor por defecto): usa el mismo modelo que la conversación principal.

La selección del modelo impacta directamente en el coste y la latencia del subagente. Un agente de revisión de código que solo lee archivos puede funcionar con Haiku, mientras que un agente que debe razonar sobre arquitectura compleja se beneficia de Sonnet u Opus.

Alcance y ubicación de los agentes

Los agentes custom se almacenan en ubicaciones distintas según su alcance de visibilidad. Cuando existen agentes con el mismo nombre en distintas ubicaciones, la de mayor prioridad prevalece.

| Ubicación | Alcance | Prioridad | |---|---|---| | --agents (flag CLI) | Sesión actual | 1 (máxima) | | .claude/agents/ | Proyecto actual | 2 | | ~/.claude/agents/ | Todos los proyectos del usuario | 3 | | Directorio agents/ de un plugin | Donde el plugin está habilitado | 4 (mínima) |

Agentes de proyecto

Los agentes en .claude/agents/ son específicos del repositorio. Al estar dentro del directorio del proyecto, pueden versionarse con Git y compartirse con todo el equipo. Esta es la ubicación recomendada para agentes que aplican convenciones o flujos de trabajo propios del proyecto.

mi-proyecto/
  .claude/
    agents/
      code-reviewer.md
      test-runner.md

Agentes de usuario

Los agentes en ~/.claude/agents/ son personales y están disponibles en todos los proyectos del usuario. Son adecuados para flujos de trabajo genéricos que no dependen de un proyecto concreto, como un agente de documentación o un asistente de debugging.

Agentes por CLI

El flag --agents permite definir agentes como JSON al lanzar Claude Code. Estos agentes existen solo durante la sesión y no se guardan en disco:

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"
  }
}'

Esta opción es útil para pruebas rápidas o para automatización mediante scripts que necesitan subagentes temporales sin modificar archivos del proyecto.

Crear agentes con el comando /agents

Claude Code ofrece una interfaz interactiva para gestionar agentes mediante el comando /agents. Este comando permite:

• Ver todos los agentes disponibles (built-in, usuario, proyecto y plugins)
• Crear nuevos agentes con un asistente guiado o generados por Claude
• Editar la configuración y herramientas de agentes existentes
• Eliminar agentes custom

Al crear un agente con /agents, se puede elegir entre escribir la configuración manualmente o seleccionar "Generate with Claude", donde se describe en lenguaje natural qué debe hacer el agente y Claude genera el prompt de sistema y la configuración automáticamente.

/agents

Para listar los agentes configurados desde la línea de comandos sin iniciar una sesión interactiva, se puede usar:

claude agents

Este comando muestra los agentes agrupados por origen (built-in, proyecto, usuario, plugins) e indica si alguno está siendo sobrescrito por una definición de mayor prioridad.

Los agentes creados manualmente como archivos markdown se cargan al inicio de la sesión. Si se crea un archivo de agente durante una sesión activa, es necesario reiniciar la sesión o usar /agents para cargarlo.

Ejemplos de agentes custom

Revisor de código

Un agente de solo lectura que analiza código sin modificarlo. Al limitar las herramientas a lectura, se garantiza que no introducirá cambios accidentales:

---
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

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

Debugger

Un agente con permisos de escritura para diagnosticar y corregir problemas. Incluye Edit porque la corrección de bugs requiere modificar código:

---
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

Validador de consultas SQL

Un agente que permite ejecutar Bash pero valida los comandos mediante un hook para permitir solo consultas de lectura:

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data.
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.

El hook PreToolUse intercepta cada comando Bash antes de ejecutarlo. El script de validación recibe el comando como JSON por stdin y devuelve código de salida 2 para bloquearlo si detecta operaciones de escritura (INSERT, UPDATE, DELETE, DROP).

Modos de permisos

El campo permissionMode permite controlar cómo gestiona el subagente las solicitudes de aprobación:

| Modo | Comportamiento | |---|---| | default | Verificación estándar de permisos con aprobación | | acceptEdits | Acepta automáticamente las ediciones de archivos | | dontAsk | Deniega automáticamente las solicitudes de permisos | | bypassPermissions | Omite todas las verificaciones de permisos | | plan | Modo de solo lectura para exploración |

El modo dontAsk resulta útil para agentes que deben operar de forma autónoma dentro de los permisos ya configurados. Las herramientas que ya están en la lista de permitidas funcionan con normalidad, las que requerirían aprobación se deniegan silenciosamente.

El modo bypassPermissions debe usarse con precaución. Al omitir todas las verificaciones, el agente puede ejecutar cualquier operación sin aprobación, incluidos comandos Bash potencialmente destructivos.

Inyección de skills

El campo skills permite cargar el contenido completo de skills específicas en el contexto del subagente al inicio de su ejecución. Esto proporciona al agente conocimiento de dominio sin que tenga que descubrir y cargar las skills durante la ejecución.

---
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.

Las skills se inyectan en el contexto del subagente, no solo se hacen disponibles para invocación. Los subagentes no heredan las skills de la conversación principal, por lo que deben listarse explícitamente.

Memoria persistente

El campo memory permite que un subagente mantenga un directorio persistente que sobrevive entre sesiones. A medida que el agente trabaja, puede escribir notas, patrones descubiertos y decisiones arquitectónicas que reutilizará en invocaciones futuras.

---
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 ámbito de la memoria determina dónde se almacenan los archivos:

| Ámbito | Ubicación | Uso recomendado | |---|---|---| | user | ~/.claude/agent-memory/<nombre>/ | Conocimiento aplicable a todos los proyectos | | project | .claude/agent-memory/<nombre>/ | Conocimiento específico del proyecto, versionable | | local | .claude/agent-memory-local/<nombre>/ | Conocimiento del proyecto, no versionable |

Cuando la memoria está habilitada, el subagente recibe las primeras 200 líneas de su archivo MEMORY.md en el prompt de sistema. Las herramientas Read, Write y Edit se habilitan automáticamente para que pueda gestionar sus archivos de memoria.

La memoria persistente convierte a un subagente en un agente que aprende con el uso. Un revisor de código que recuerda los patrones del proyecto, las convenciones del equipo y los errores recurrentes produce revisiones cada vez más precisas y relevantes.

Desactivar agentes

Para impedir que Claude use un agente específico (built-in o custom), se puede añadir a la lista deny de los permisos en settings.json:

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

También se puede usar el flag --disallowedTools desde la línea de comandos:

claude --disallowedTools "Agent(Explore)"

Esta configuración permite un control preciso sobre qué agentes están disponibles en cada contexto de trabajo.