Cómo crear un agente en Claude Code: agentes personalizados con --agent

Crea agentes especializados como archivos Markdown y lanza sesiones con claude --agent. Cada agente tiene su propio system prompt, herramientas y modelo.

Claude Code permite crear agentes especializados como archivos Markdown con frontmatter YAML. Cada agente tiene su propio system prompt, herramientas restringidas y modelo. Cuando lanzas una sesión con claude --agent <nombre>, toda la conversación se transforma. No es un subagent delegado, es tu sesión principal operando con una personalidad y reglas diferentes.

Es como tener múltiples versiones de Claude Code, cada una diseñada para un rol concreto: reviewer, debugger, deployer, o lo que necesites.

TL;DR Crea un archivo .md en ~/.claude/agents/, define el rol en el frontmatter YAML, y lánzalo con claude --agent nombre. Tu sesión entera se convierte en ese agente especializado.

Resultado, un agente de revisión de código listo para usar:

# ~/.claude/agents/reviewer.md
---
name: reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Provide feedback organized by priority:
   - Critical (must fix)
   - Warnings (should fix)
   - Suggestions (consider improving)

Include specific examples of how to fix each issue.

Configuración

1. Crear el archivo del agente

Crea un archivo .md en una de estas ubicaciones:

# Global: disponible en todos tus proyectos
~/.claude/agents/reviewer.md

# Proyecto: compartido con el equipo via git
.claude/agents/reviewer.md

2. Lanzar la sesión como agente

claude --agent reviewer

Claude Code arranca con el system prompt, las herramientas y el modelo que definiste. No verás el prompt habitual: estás dentro del agente.

3. Usar el asistente interactivo

Si prefieres no escribir el archivo a mano:

claude
# Dentro de la sesión:
/agents

Selecciona "Create new agent", elige el scope (user o project), y Claude te guía paso a paso, e incluso puede generar el system prompt por ti.

4. Definir agentes efímeros desde la CLI (opcional)

Para probar sin crear archivo, usa --agents (plural) con JSON inline:

claude --agents '{
  "reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer. Focus on quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Nota: --agent (singular) transforma tu sesión principal en un agente existente. --agents (plural) define subagents efímeros que Claude puede delegar durante la sesión.

Referencia

Campo	Requerido	Descripción
`name`	Sí	Identificador único (letras minúsculas y guiones)
`description`	Sí	Cuándo debe usarse este agente
`tools`	No	Herramientas permitidas. Si se omite, hereda todas
`disallowedTools`	No	Herramientas explícitamente denegadas
`model`	No	`sonnet`, `opus`, `haiku` o `inherit` (por defecto)
`permissionMode`	No	`default`, `acceptEdits`, `dontAsk`, `plan`, `bypassPermissions`
`hooks`	No	Hooks del ciclo de vida del agente
`memory`	No	`user`, `project` o `local`, memoria persistente entre sesiones (cuándo usarla y cuándo no)
`skills`	No	Skills precargadas en el contexto del agente
`mcpServers`	No	Servidores MCP disponibles para el agente

Ubicación	Alcance	Prioridad
`--agents` (CLI flag)	Sesión actual	1 (máxima)
`.claude/agents/`	Proyecto	2
`~/.claude/agents/`	Global (personal)	3
Directorio de plugins	Donde el plugin esté activo	4 (mínima)

Documentación oficial: Crear subagentes personalizados

¿Tus agentes le piden verificar o delegar? Con Opus 5 esas líneas juegan en tu contra: los 8 consejos de Anthropic incluyen ponerle un tope explícito a la delegación. El campo model es donde se decide de verdad tu reparto de coste: yo dejo Sonnet 5 viviendo aquí dentro y Opus orquestando fuera. Cómo reparto los tres modelos, incluido lo que hace memory al arranque en frío del subagente. Si le pasas mcpServers, ten presente que las llamadas MCP de un subagente no se van a segundo plano al pasar de dos minutos: eso solo ocurre en la conversación principal, así que un servidor lento sí le retiene el turno. Falta un campo en esa tabla, y decide dónde corre el subagente cuando Claude lo delega: background. Puesto a true lo manda siempre al fondo, y el fondo le quita herramientas nativas aunque las hayas declarado en tools. El recorte del segundo plano.