Crea agentes personalizados en Claude Code 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 — 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