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

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

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. Desde la v2.1.284, model: sonnet corre en Sonnet 5.5, que en tareas acotadas hace el mismo trabajo que Opus 5.5 por la mitad. Y desde la v2.1.293, model: haiku corre en Haiku 5.5, que en un subagente con pocas herramientas sale un 90% más económico que Haiku 4.5. 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.