# Referencia Completa: Frontmatter de Skills y Hook Events

Fuente: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

---

## Frontmatter completo de SKILL.md (12 campos)

| Campo | Requerido | Tipo | Descripción |
|-------|-----------|------|-------------|
| `name` | No* | string | Nombre kebab-case, max 64 chars. Se convierte en `/nombre` para invocación. *Si se omite, usa el nombre del directorio |
| `description` | Recomendado | string | Max 1024 chars. QUÉ hace + CUÁNDO usar. Guía la auto-activación de Claude |
| `argument-hint` | Opcional | string | Hint de autocompletado: `[archivo]`, `[issue-num]`, `[file] [format]` |
| `allowed-tools` | Opcional | array | Tools que Claude puede usar sin pedir permiso cuando la skill está activa |
| `paths` | Opcional | array/string | Patrones glob: cargar skill SOLO al trabajar con archivos que coinciden |
| `context` | Opcional | string | `fork` = ejecutar en subagente aislado con su propia conversación |
| `agent` | Opcional | string | Tipo de subagente si `context: fork` (Explore, Plan, general-purpose) |
| `model` | Opcional | string | Override de modelo para esta skill |
| `effort` | Opcional | string | Nivel de esfuerzo: `low`, `medium`, `high`, `max` (Opus only) |
| `shell` | Opcional | string | `bash` o `powershell`. Controla bloques `!comando` embebidos |
| `disable-model-invocation` | Opcional | boolean | `true` = solo el usuario puede invocar (no auto-trigger). Usar para skills con side-effects como `/deploy` |
| `user-invocable` | Opcional | boolean | `false` = solo Claude la ve (conocimiento de background). No aparece en menú `/` |

### Ejemplo completo

```yaml
---
name: api-test-generator
description: >
  Genera tests de integracion para endpoints REST. Auto-activar cuando el usuario
  crea o modifica un endpoint en src/api/. Produce tests con httpx y pytest que
  cubren happy path, validacion de input, auth y error handling.
argument-hint: "[endpoint-path]"
allowed-tools: ["Read", "Grep", "Glob", "Write"]
paths:
  - "src/api/**/*.py"
  - "tests/integration/**/*.py"
model: claude-sonnet-4-6
effort: high
disable-model-invocation: false
user-invocable: true
---
```

### Sustituciones de string disponibles

| Variable | Valor |
|----------|-------|
| `$ARGUMENTS` | Argumentos pasados al invocar la skill |
| `$0`, `$1`, `$2`... | Argumentos posicionales |
| `${CLAUDE_SESSION_ID}` | ID unico de la sesion actual |
| `${CLAUDE_SKILL_DIR}` | Path absoluto al directorio de la skill |
| `${env:VAR_NAME}` | Variable de entorno del sistema |

---

## 25 Hook Events oficiales

### Ciclo de vida de sesión

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `SessionStart` | Al iniciar o resumir sesión | `startup`, `resume`, `clear`, `compact` | Cargar contexto, setup env |
| `SessionEnd` | Al terminar sesión | `clear`, `resume`, `logout`, `other` | Cleanup, archivado |
| `InstructionsLoaded` | CLAUDE.md o rules/ cargados | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | Log que instrucciones se cargaron |

### Ejecución de herramientas

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `PreToolUse` | Antes de ejecutar herramienta | Nombre de tool (Bash, Edit, Read, mcp__*) | Bloquear ops inseguras, validar |
| `PostToolUse` | Después de ejecutar herramienta (éxito) | Nombre de tool | Auto-lint, format, log |
| `PostToolUseFailure` | Cuando falla herramienta | Nombre de tool | Notificar, reintentar |
| `PermissionRequest` | Se muestra diálogo de permiso | Nombre de tool | Auto-aprobar acciones seguras |

### Respuesta y control

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `Stop` | Claude termina de responder | Ninguno (siempre se dispara) | Verificar tarea completa |
| `StopFailure` | Error de API en Stop | `rate_limit`, `authentication_failed`, `billing_error`, `server_error` | Notificar fallos |
| `UserPromptSubmit` | Usuario envía prompt | Ninguno | Interceptar/enriquecer input |

### Compactación de contexto

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `PreCompact` | Antes de compactar | `manual`, `auto` | Salvar estado crítico |
| `PostCompact` | Después de compactar | `manual`, `auto` | Re-inyectar contexto |

### Subagentes

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `SubagentStart` | Al spawnar subagente | `Explore`, `Plan`, `general-purpose`, nombres custom | Log creación |
| `SubagentStop` | Al terminar subagente | Mismos que SubagentStart | Cleanup worktrees |
| `TeammateIdle` | Miembro de equipo idle | Ninguno | Keep alive, escalar |

### Tasks

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `TaskCreated` | Al crear tarea | Ninguno | Log, validar tasks |
| `TaskCompleted` | Al completar tarea | Ninguno | Notificar, log |

### Configuración y archivos

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `ConfigChange` | Cambio en settings | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | Auditar, bloquear no autorizado |
| `CwdChanged` | Cambio de directorio de trabajo | Ninguno | Recargar direnv, actualizar env |
| `FileChanged` | Archivo observado cambia | Patrón de nombre (`.envrc`, `.env`) | Recargar config, re-lint |

### Git worktrees

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `WorktreeCreate` | Git worktree creado | Ninguno | Setup custom |
| `WorktreeRemove` | Git worktree removido | Ninguno | Cleanup recursos |

### MCP

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `Elicitation` | Servidor MCP pide input | Nombre del servidor MCP | Gate user input |
| `ElicitationResult` | Usuario responde a MCP | Nombre del servidor MCP | Validar/transformar respuesta |

### Notificaciones

| Evento | Cuándo se dispara | Matchers | Uso típico |
|--------|-------------------|----------|-----------|
| `Notification` | Claude espera input | `permission_prompt`, `idle_prompt`, `auth_success` | Alertas desktop, sonidos |

---

## Frontmatter completo de agents (.claude/agents/*.md) — 16 campos

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `name` | string | Nombre kebab-case del agente |
| `description` | string | Cuándo invocarlo — usar `"PROACTIVELY"` para invocación eager |
| `model` | string | Override de modelo (`sonnet`, `haiku`, `opus`) |
| `color` | string | Color del agente en terminal (green, blue, red, etc.) |
| `maxTurns` | number | Máximo de turnos antes de terminar |
| `permissionMode` | string | `acceptEdits`, `dontAsk`, `plan`, `default` |
| `memory` | string | `project`, `user`, `local`, `none` |
| `skills` | array | Skills precargados como conocimiento de background |
| `isolation` | string | `worktree` = rama git aislada por ejecución |
| `allowed-tools` | array | Herramientas permitidas sin pedir permiso |
| `hooks` | object | Hooks específicos del agente (SubagentStop, PreToolUse, etc.) |
| `stop` | string | Instrucción de cuándo detenerse |
| `shell` | string | `bash` o `powershell` |
| `effort` | string | `low`, `medium`, `high`, `max` |
| `disable-model-invocation` | boolean | Solo invocación manual |
| `user-invocable` | boolean | Visible en menú o solo invocable por Claude |

**Gotcha**: El evento `Stop` en frontmatter de agente se dispara como `SubagentStop`, no como `Stop`.

---

## Frontmatter de commands (.claude/commands/*.md) — 13 campos

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `name` | string | Se convierte en `/nombre` (o subcarpeta: `/dir:nombre`) |
| `description` | string | Descripción mostrada en autocompletado |
| `argument-hint` | string | Hint visual: `[archivo]`, `[issue-num]` |
| `allowed-tools` | array | Tools permitidos sin pedir permiso |
| `model` | string | Override de modelo |
| `effort` | string | Nivel de esfuerzo |
| `shell` | string | `bash` o `powershell` |
| `user-invocable` | boolean | Default `true` — commands siempre son user-invocable |
| `disable-model-invocation` | boolean | `true` = Claude no puede auto-invocar |

**Diferencia clave**: commands NUNCA se auto-invocan — siempre requieren `/nombre` del usuario.

---

## Orden de resolución (cuando múltiples coinciden)

```
Skill (inline, preferido) > Agent (contexto separado) > Command (nunca auto-invocado)
```

Si un skill y un agent tienen descripciones similares, Claude prefiere el skill
porque se ejecuta inline sin el overhead de un subagente.

---

## Tipos de handler para hooks

| Tipo | Descripción | Ejemplo |
|------|-------------|---------|
| `command` | Ejecuta comando shell | `"command": "node .claude/hooks/lint.js"` |
| `prompt` | Claude decide qué hacer | `"prompt": "Verifica que el archivo..."` |
| `agent` | Claude con herramientas propias | `"agent": "Analiza y corrige..."` |
| `http` | POST a endpoint HTTP | `"url": "https://webhook.example.com/hook"` |

### Códigos de retorno para hooks command

| Código | Significado |
|--------|-------------|
| `0` | Permitir (allow) |
| `2` | Bloquear (block) — la operación no se ejecuta |
| Otro | Error — Claude decide qué hacer |

### Opciones avanzadas de hooks

| Opción | Tipo | Descripción |
|--------|------|-------------|
| `async` | boolean | Ejecutar en background sin bloquear — fire-and-forget |
| `timeout` | number | Timeout en ms (default varía por evento) |
| `once` | boolean | Ejecutar solo la primera vez que el evento ocurre |
| `asyncRewake` | boolean | Re-despertar al agente cuando el hook async termina |
| `statusMessage` | string | Mensaje mostrado mientras el hook ejecuta |
| `if` | string | Condicional (v2.1.85+) — solo ejecutar si la condición se cumple |

### Campos JSON de retorno del hook

| Campo | Tipo | Efecto |
|-------|------|--------|
| `continue` | boolean | `false` = detener la cadena de hooks |
| `stopReason` | string | Razón de detención (si `continue: false`) |
| `suppressOutput` | boolean | No mostrar output del hook al usuario |
| `systemMessage` | string | Inyectar mensaje al contexto del sistema |
| `additionalContext` | string | Agregar contexto adicional a la conversación |
| `updatedInput` | object | Solo PreToolUse — modificar el input de la herramienta antes de ejecución |

---

## Patrones de permisos en settings.json

### Patrones comunes de allow

```json
"allow": [
  "Bash(git:*)",
  "Bash(npm:*)",
  "Bash(python:*)",
  "Bash(uv:*)",
  "Bash(pytest:*)",
  "Read(**/src/**)",
  "Write(**/src/**)",
  "Read(**/tests/**)",
  "Write(**/tests/**)"
]
```

### Patrones comunes de deny

```json
"deny": [
  "Bash(rm -rf:*)",
  "Bash(curl * | bash:*)",
  "Bash(sudo:*)",
  "Read(**/env:*)",
  "Read(**/.env*)",
  "Write(**/node_modules/**)"
]
```

---

## Estructura de plugin.json

```json
{
  "name": "mi-plugin",
  "version": "1.0.0",
  "description": "Descripción del plugin",
  "author": "Tu nombre",
  "skills": ["skills/mi-skill"],
  "agents": ["agents/mi-agent.md"],
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "node hooks/validate.js"
      }
    ]
  },
  "mcpServers": {
    "mi-server": {
      "command": "node",
      "args": ["mcp-servers/server.js"]
    }
  }
}
```
