14. Personalización: subagentes, comandos y permisos

Objetivo del tema

Transformar Claude Code de asistente general en una herramienta adaptada al equipo: delegar tareas acotadas a subagentes, convertir procedimientos repetidos en Skills invocables y limitar cada capacidad mediante permisos explícitos. Al finalizar construiremos una configuración de proyecto versionable, comprobable y segura.

14.1 Elegir la capa de personalización correcta

No todo texto repetido pertenece al mismo archivo. La primera decisión de diseño consiste en separar reglas permanentes, procedimientos bajo demanda, contextos especializados y controles de seguridad.

Diagnóstico rápido: ¿dónde debe vivir cada necesidad?

Necesidad	Mecanismo	Motivo
“Los controladores nunca acceden directamente a la base”	CLAUDE.md o regla por ruta	Es una convención transversal y permanente.
“Revisa este PR con nuestro checklist”	Skill	Es un procedimiento repetible que usa el contexto principal.
“Investiga la autenticación y devuelve un informe”	Subagente	La exploración puede ser extensa y su resultado es autocontenido.
“Nunca leas archivos .env”	permissions.deny	Debe impedirse técnicamente, aunque un prompt solicite lo contrario.

14.2 Qué es un subagente y cuándo conviene usarlo

Un subagente es un asistente especializado que recibe una tarea, trabaja en su propio contexto y devuelve el resultado a la conversación principal. Esto evita que búsquedas, registros o lecturas voluminosas consuman el contexto donde se toman las decisiones. Claude Code incluye agentes internos como Explore, Plan y general-purpose, y permite definir otros.

Un buen encargo para subagente tiene entrada, frontera y salida claras. Por ejemplo: “inspecciona el módulo de pagos sin modificarlo; devuelve riesgos ordenados por severidad con archivo y línea”. No conviene delegar una corrección mínima que depende de intercambios frecuentes ni fragmentar un flujo donde planificación, implementación y prueba comparten continuamente la misma información.

14.3 Crear y ubicar un subagente

El comando /agents permite administrar definiciones desde la interfaz. También puedes crear un archivo Markdown manualmente. La ubicación determina su alcance y la prioridad resuelve nombres duplicados:

Ámbitos principales de un subagente

Ubicación	Alcance	Uso recomendado
Configuración administrada	Organización	Políticas y agentes distribuidos centralmente.
--agents	Sesión actual	Experimentos o automatización efímera.
.claude/agents/	Proyecto	Especialistas compartidos y versionados con el repositorio.
~/.claude/agents/	Usuario	Preferencias personales reutilizables.
<plugin>/agents/	Plugin habilitado	Distribución modular entre proyectos.

Crearemos .claude/agents/api-reviewer.md. El frontmatter empieza obligatoriamente en la primera línea; name y description identifican el agente, mientras que el cuerpo reemplaza su prompt de sistema:

---
name: api-reviewer
description: Revisa cambios de API y detecta defectos de contrato, seguridad y compatibilidad. Úsalo después de modificar endpoints.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
maxTurns: 12
---

Eres responsable de revisar APIs, no de modificarlas.

1. Lee el diff y localiza los endpoints afectados.
2. Contrasta validación, autorización, códigos HTTP y esquema público.
3. Identifica las pruebas pertinentes y propone cómo ejecutarlas; no alteres estado.
4. Devuelve hallazgos ordenados por severidad.

Para cada hallazgo incluye: archivo y línea, escenario reproducible,
impacto y corrección mínima. No informes preferencias cosméticas.

La descripción debe explicar cuándo delegar y ser breve; los detalles operativos van en el cuerpo y solo ocupan contexto cuando el agente se ejecuta. Comprueba las definiciones con /agents, /doctor o, en versiones compatibles, con:

claude plugin validate .claude/agents
claude --debug

14.4 Herramientas, modelo, aislamiento y límites

El frontmatter es una interfaz operativa. No agregues campos por costumbre: cada capacidad debe derivarse del trabajo real.

Campos útiles de una definición de subagente

Campo	Función	Criterio
tools	Lista permitida de herramientas.	Para auditoría, comienza con lectura y agrega Bash solo si debe ejecutar pruebas.
disallowedTools	Elimina herramientas heredadas.	Útil para conservar el conjunto general excepto Edit y Write.
model	Elige modelo o inherit.	Equilibra complejidad, latencia y consumo.
permissionMode	Modo de aprobación del agente.	plan es apropiado para una revisión que no debe editar.
maxTurns	Limita turnos internos.	Evita investigaciones abiertas sin criterio de salida.
skills	Precarga conocimiento reutilizable.	Incluye convenciones específicas que el agente realmente necesita.
isolation: worktree	Crea un árbol Git temporal.	Úsalo cuando el subagente modifica código en paralelo.
memory	Conserva memoria según el ámbito configurado.	Solo para conocimiento acumulativo que pueda revisarse.

---
name: test-fixer
description: Corrige pruebas fallidas aislando sus cambios en un worktree
tools: Read, Grep, Glob, Edit, Write, Bash
disallowedTools: WebFetch, WebSearch
isolation: worktree
maxTurns: 18
skills:
  - testing-conventions
---

Reproduce primero el fallo. Modifica solamente lo necesario,
vuelve a ejecutar la prueba afectada y resume cambios y evidencia.

tools limita qué herramientas recibe el subagente, pero sus llamadas siguen sujetas a las reglas de permisos de la sesión. Una lista de herramientas no equivale a una autorización universal.

14.5 Invocar, observar y evaluar subagentes

Claude puede delegar automáticamente cuando la solicitud coincide con la descripción. Para mayor control, nombra el agente en lenguaje natural o selecciónalo mediante una mención @. También puedes convertir una definición en el agente principal de toda la sesión:

Usa el subagente api-reviewer para revisar el cambio actual.

@"api-reviewer (agent)" revisa solamente los endpoints de autenticación.

claude --agent api-reviewer

Los subagentes en primer plano detienen la conversación hasta terminar; los de fondo permiten continuar otras tareas. El paralelismo reduce tiempo de espera, pero multiplica trabajo, uso de contexto y posibles colisiones. Una devolución profesional debe hacer posible verificar el resultado.

Evalúa el agente con casos positivos y negativos: un cambio defectuoso que deba detectar, uno correcto que no deba marcar y un repositorio sin información suficiente donde deba reconocer la incertidumbre. Si produce ruido, ajusta la descripción, el criterio de evidencia y el formato de salida antes de aumentar herramientas.

14.6 De comandos personalizados a Skills

Los comandos personalizados se integraron al sistema de Skills. Los archivos existentes en .claude/commands/nombre.md continúan creando /nombre, pero para una personalización nueva se recomienda .claude/skills/nombre/SKILL.md. Una Skill admite recursos auxiliares, control de invocación, contexto separado y descubrimiento automático.

Ubicación y precedencia de Skills

Origen	Ruta	Disponibilidad
Empresa	Configuración administrada	Todos los usuarios cubiertos por la política.
Personal	~/.claude/skills/<nombre>/SKILL.md	Todos tus proyectos.
Proyecto	.claude/skills/<nombre>/SKILL.md	El repositorio y sus colaboradores.
Plugin	<plugin>/skills/<nombre>/SKILL.md	Donde el plugin esté habilitado; usa nombre con espacio de nombres.

Ante el mismo nombre, una Skill prevalece sobre un archivo legado de .claude/commands/. Entre los ámbitos habituales, empresa prevalece sobre personal y personal sobre proyecto. Evita reutilizar nombres sin revisar esta resolución.

14.7 Crear una Skill invocable y segura

Crearemos .claude/skills/review-pr/SKILL.md. La propiedad disable-model-invocation: true reserva su ejecución al usuario, una buena elección para tareas cuyo momento no debe decidir el modelo:

---
name: review-pr
description: Revisa un pull request con el estándar del equipo
argument-hint: "[numero-pr]"
disable-model-invocation: true
allowed-tools:
  - Bash(gh pr view *)
  - Bash(gh pr diff *)
---

Revisa el PR $ARGUMENTS.

1. Obtén título, descripción, archivos y diff mediante GitHub CLI.
2. Busca errores funcionales, seguridad, regresiones y pruebas ausentes.
3. No cambies archivos ni publiques comentarios.
4. Separa hechos demostrados de hipótesis.
5. Termina con una recomendación y sus condiciones.

/review-pr 142

allowed-tools preautoriza las operaciones listadas solamente durante el turno de invocación; no elimina las demás herramientas ni concede permisos permanentes. Para restringir herramientas durante la Skill usa disallowed-tools; para una prohibición global utiliza permissions.deny.

14.8 Argumentos, contexto dinámico y archivos auxiliares

$ARGUMENTS recibe todo lo escrito después del comando. Para parámetros posicionales usa $0, $1 o $ARGUMENTS[0]. El prefijo ! con un comando entre acentos graves inyecta su salida antes de que Claude procese la Skill.

---
name: summarize-module
description: Resume cambios de un módulo y propone pruebas
argument-hint: "[ruta-modulo]"
disable-model-invocation: true
allowed-tools:
  - Bash(git status --short --branch)
  - Bash(git diff -- *)
  - Read
  - Grep
  - Glob
---

## Rama y estado
!`git status --short --branch`

## Diferencias del módulo
!`git diff -- $0`

Analiza únicamente `$0`. Resume intención, riesgos y pruebas faltantes.
Si la ruta no existe o el diff está vacío, indícalo sin inventar cambios.

/summarize-module src/auth

Una Skill puede acompañarse de references/, examples/, plantillas y scripts. Usa ${CLAUDE_SKILL_DIR} para referenciar su propia carpeta y ${CLAUDE_PROJECT_DIR} para la raíz del proyecto. Mantén SKILL.md breve y carga recursos solo cuando sean necesarios.

.claude/skills/release-notes/
├── SKILL.md
├── references/
│   └── style-guide.md
├── templates/
│   └── release.md
└── scripts/
    └── collect-changes.sh

14.9 Cómo funciona el sistema de permisos

Las reglas tienen forma Herramienta o Herramienta(especificador). Claude Code evalúa primero deny, después ask y por último allow. Una coincidencia amplia en deny no se neutraliza con un allow más específico.

Intención de cada lista

Lista	Comportamiento	Ejemplo
allow	Ejecuta sin aprobación manual.	Bash(npm test *)
ask	Solicita confirmación cada vez que coincide.	Bash(git push *)
deny	Bloquea la operación.	Read(./.env)

Un nombre desnudo, como Bash, cubre toda la herramienta; un patrón acota usos concretos. En Bash, el espacio antes de * importa: Bash(npm test *) coincide con el comando base y sus argumentos sin confundirlo con otro ejecutable de prefijo semejante. Los operadores compuestos se analizan por subcomando, por lo que autorizar una orden no autoriza silenciosamente todo lo que siga tras &&.

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Read(./tests/**)",
      "Bash(npm test *)",
      "Bash(npm run lint *)"
    ],
    "ask": [
      "Bash(git push *)",
      "WebFetch(domain:api.github.com)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)"
    ]
  }
}

14.10 Ámbitos de configuración y modos de aprobación

Guarda decisiones compartidas en .claude/settings.json y preferencias no versionadas en .claude/settings.local.json. Las opciones personales globales viven en ~/.claude/settings.json; las políticas administradas tienen máxima prioridad y no pueden ser rebajadas por el proyecto.

Modos de permisos

Modo	Comportamiento	Escenario adecuado
default	Pide autorización según la operación y las reglas.	Trabajo interactivo general.
acceptEdits	Acepta ediciones y operaciones comunes del workspace.	Implementación supervisada y bien delimitada.
plan	Explora sin editar el código fuente.	Análisis, diseño y revisión.
auto	Usa comprobaciones de seguridad para decidir llamadas.	Disponible como función en evolución; requiere política organizativa.
dontAsk	Rechaza lo que no fue preautorizado.	Automatización cerrada con lista permitida.
bypassPermissions	Omite la mayoría de las confirmaciones.	Solo contenedores o máquinas virtuales desechables y aisladas.

{
  "permissions": {
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable",
    "allow": ["Bash(npm test *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env*)"]
  }
}

Inspecciona y modifica reglas con /permissions; el diálogo muestra también el archivo de origen. El permiso efectivo combina los ámbitos: si cualquier nivel niega una operación, otro nivel no puede habilitarla. Las concesiones del proyecto requieren aceptar la confianza del workspace.

14.11 Caso integrador: revisión de cambios de API

Combinaremos las capas sin duplicar responsabilidades:

La Skill .claude/skills/review-api/SKILL.md puede ejecutar el procedimiento en un contexto bifurcado usando el subagente definido anteriormente:

---
name: review-api
description: Audita los cambios actuales de la API sin modificarlos
disable-model-invocation: true
context: fork
agent: api-reviewer
background: false
---

Revisa el diff actual de la API.

Comprueba contrato público, autenticación, autorización, validación,
errores y compatibilidad. Indica qué pruebas aportarían evidencia.
Devuelve alcance, hallazgos, pruebas ejecutadas e incertidumbres.

/review-api

El flujo es auditable: la Skill define el procedimiento, el subagente define especialización y límites, y settings.json conserva la última palabra sobre las operaciones. Si mañana cambia el checklist, se modifica la Skill; si cambia el rol, se modifica el agente; si cambia el riesgo tolerado, se modifican los permisos.

14.12 Pruebas, mantenimiento y checklist final

La configuración también es código. Revísala en pull requests, prueba casos representativos y elimina personalizaciones obsoletas. Un prompt elegante que nunca se activa, un agente con acceso excesivo o una regla imposible de cumplir son defectos de producto.

Lista de comprobación antes de compartir la personalización

Control	Pregunta verificable
Responsabilidad	¿Cada regla, Skill y agente tiene una función distinta y necesaria?
Activación	¿La descripción dispara el recurso en casos correctos y evita falsos positivos?
Entrada	¿Argumentos, rutas y estados vacíos se manejan explícitamente?
Salida	¿El resultado contiene evidencia, límites y formato estable?
Capacidad	¿Las herramientas concedidas son las mínimas para completar la misión?
Seguridad	¿Secretos, publicación, borrado y producción están bloqueados o requieren confirmación?
Concurrencia	¿Los agentes que editan en paralelo usan aislamiento o fronteras no solapadas?
Versionado	¿La configuración compartida está documentada, revisada y sin datos personales?

Consulta la documentación oficial de subagentes, Skills y comandos personalizados, permisos y comandos integrados para comprobar disponibilidad y cambios de versión.

Conclusión: una personalización mantenible separa conocimiento, proceso, especialización y autoridad. Los subagentes aíslan trabajos, las Skills convierten procedimientos en herramientas reutilizables y los permisos establecen fronteras efectivas. En el próximo tema añadiremos Hooks para reaccionar de forma determinista a los eventos del ciclo de vida.