Kata 24 · Slash Commands Custom y Skills

Corrección de hechos (oficial). [DOC] Esta kata describe allowed-tools como una "whitelist que limita operaciones destructivas". Es inexacto: allowed-tools pre-aprueba (evita prompts) las tools listadas pero NO cierra las demás — para limitar/quitar tools usa disallowed-tools o permissions.deny. Además, los slash commands están fusionados en skills (.claude/commands/x.md ≡ .claude/skills/x/SKILL.md). Ver custom-tooling-extension y claude-command-authoring para el detalle corregido.

Qué es

Claude Code extiende la sesión con dos mecanismos de extensión distintos. Los slash commands viven en .claude/commands/X.md y se disparan explícitamente escribiendo /X. Las skills viven en .claude/skills/X/SKILL.md y se activan on-demand cuando el modelo detecta que la metadata del frontmatter encaja con la tarea. El frontmatter de una skill declara su contrato operativo: context: fork aísla la ejecución en un sub-agente, allowed-tools define la whitelist de herramientas permitidas, y argument-hint documenta los argumentos esperados.

Por qué importa (falla que evita)

Un command guardado en ~/.claude/commands/ no se replica al equipo: solo existe en la máquina personal de quien lo creó, así que el resto del equipo nunca lo recibe vía git. Una skill sin context: fork contamina la sesión principal con output verbose (un análisis exploratorio puede inyectar unos 5000 tokens de ruido en el contexto activo). Y una skill que no declara disallowed-tools (ni permissions.deny) deja abiertas operaciones destructivas: recuerda que allowed-tools solo pre-aprueba, no cierra las demás tools.

Modelo mental

• Slash command = trigger explícito que el usuario invoca; skill = workflow on-demand con metadata que el modelo decide activar.
• Project scope (.claude/) viaja con git y llega a todo el equipo; user scope (~/.claude/) es personal y no se comparte.
• context: fork aísla la skill en un sub-agente → economía de contexto: el output verbose no contamina la sesión principal.
• allowed-tools pre-aprueba las tools listadas (evita prompts) pero NO cierra las demás; para impedir Write/Bash usa disallowed-tools o permissions.deny.
• Las convenciones siempre-aplicables van en CLAUDE.md, no en una skill ni en un command: CLAUDE.md es para reglas permanentes, las skills para workflows on-demand.

Patrón correcto

# .claude/skills/codebase-analysis/SKILL.md
---
name: codebase-analysis
description: "Mapea estructura y dependencias de un módulo o feature."
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "<dir-or-feature>"
---
# El body hace Glob -> Grep -> devuelve un resumen tipado.
# context:fork aísla los ~5000 tokens de exploración en un sub-agente.
# allowed-tools sin Write ni Bash impide mutaciones por accidente.

Anti-patrón

# ~/.claude/skills/codebase-analysis/SKILL.md   (user scope: NO replica al equipo)
---
name: codebase-analysis
# sin context: fork  -> 5000 tokens contaminan la sesión principal
# sin allowed-tools  -> puede Write/Bash y borrar por accidente
---

Argumento de certificación

• Escoger command vs skill según trigger (explícito vs on-demand) y scope (project vs user).
• Explicar el frontmatter: context, allowed-tools y argument-hint.
• Conectar context: fork con la economía de contexto (sub-agente aislado).
• Defender que las convenciones permanentes van en CLAUDE.md, no en una skill ni en un command.

Cuándo activar

• El usuario pregunta por crear o versionar slash commands custom.
• Hay que decidir entre command y skill, o entre project scope y user scope.
• Se diseña el frontmatter de una skill (context: fork, allowed-tools, argument-hint).
• Se discute dónde ubicar convenciones permanentes del equipo.

Skills relacionadas

• katas-context-dilution-mitigation
• katas-prefix-caching
• katas-session-resume-fork

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.