Slash commands personalizados

Módulo 4 · Configuración y personalización · Lección 4 de 5

Al terminar esta lección sabrás crear un comando slash personalizado desde cero y compartirlo como un recurso reutilizable del equipo.

Si se lo pides a Claude más de dos veces, conviértelo en un comando.

Qué son los comandos

Un comando es un archivo Markdown con frontmatter YAML

No hay una sintaxis especial que aprender. Los comandos slash personalizados convierten los prompts repetidos en recursos reutilizables y versionados del equipo. Cualquier archivo .md que coloques en .claude/commands/ se convierte automáticamente en un comando slash. El nombre del archivo determina el nombre del comando.

Elemento	Qué es	Detalle
Ubicación · .claude/commands/	Ámbito de proyecto	Se confirma en git y está disponible para todos los desarrolladores del equipo. Aparece en Claude como /<nombre-del-archivo>.
Nombre del archivo	Se convierte en el nombre del comando	Los archivos dentro de carpetas crean espacios de nombres. review-pr.md → /review-pr · security/audit.md → /security:audit
Frontmatter	Metadatos YAML opcionales	Controla el comportamiento: qué herramientas puede invocar el comando y qué aparece en el selector de comandos. Campos: allowed-tools y description.
Argumentos · $ARGUMENTS	Marcador de posición	Úsalo en cualquier parte del cuerpo del prompt para pasar texto desde la invocación del comando. Ejemplo: /review-pr 1234

flowchart LR
    A[".claude/commands/review-pr.md"] --> B["/review-pr"]
    C[".claude/commands/security/audit.md"] --> D["/security:audit"]

Construir un comando

De un archivo en blanco a un comando funcional en cuatro líneas

Este es un comando personalizado completo para revisar pull requests según la lista de verificación de seguridad de un engagement. Es el tipo de comando que vale la pena entregar a los clientes como artefacto reutilizable.

.claude/commands/review-pr.md

---
description: Review a pull request against the security checklist
allowed-tools: Read, Bash(git *)
---

## PR Review: $ARGUMENTS

You are reviewing PR $ARGUMENTS against Acme Corp's security checklist.

Run `git diff main` to inspect the changed files, then evaluate:

- No credentials, tokens, or API keys in changed files
- No new eval() or dynamic code execution patterns
- No new external network calls without logging
- Dependency changes have corresponding security review notes

Summarise your findings as: approved / needs changes / blocked.
For each finding, cite the specific file and line number.

Se invoca como /review-pr 847. Claude sustituye $ARGUMENTS por 847, restringe el uso de herramientas a Read y Bash(git *) y ejecuta automáticamente la evaluación de la lista de verificación.

flowchart TD
    A["Invocas /review-pr 847"] --> B["$ARGUMENTS se sustituye por 847"]
    B --> C["Herramientas permitidas: Read y Bash(git *)"]
    C --> D["Claude ejecuta la lista de verificación"]
    D --> E["Resumen: approved / needs changes / blocked, con archivo y línea por hallazgo"]

Principio de diseño

Escribe el comando para la persona que lo usará el peor día de un sprint: bajo presión, cambiando de contexto. El cuerpo del prompt debe ser lo bastante específico para ejecutarse sin pensar y lo bastante corto para leerse en menos de 30 segundos.

Alcance

Comandos del equipo frente a comandos personales

Los comandos en .claude/commands/ son de proyecto: se confirman en el repositorio y se comparten con el equipo. Los comandos personales viven en ~/.claude/commands/ y están disponibles en todos los proyectos de esa máquina. Ninguno de los dos tipos requiere registro ni reinicio: Claude descubre automáticamente los nuevos archivos de comando.

Tipo	Ubicación	Alcance
Del equipo	.claude/commands/	Se confirma en git y se comparte con todo el equipo
Personal	~/.claude/commands/	Disponible en todos los proyectos de esa máquina

En un engagement con un cliente, la distinción importa: entrega los comandos del equipo en el repositorio como artefacto de entrega, y anima a cada desarrollador a construir su propia biblioteca personal de atajos que persista entre engagements.

Comprueba tu comprensión

Escenario: ¿Qué diseño de comando es mejor?

Un desarrollador de un engagement con un cliente de fintech quiere crear un comando para resumir los cambios de código antes de una publicación. ¿Qué enfoque crea un comando más útil y reutilizable?

El desarrollador redacta dos versiones de un comando /release-summary. La Opción A tiene un prompt breve: «Resume qué cambió en esta versión.». La Opción B usa $ARGUMENTS para la etiqueta de versión, especifica las herramientas permitidas (Read, Bash(git *)) e incluye requisitos de formato de salida estructurado y contexto de audiencia (notas de la versión para un stakeholder no técnico). ¿Cuál se entrega como mejor comando del equipo?

• A. Corto y flexible: el prompt breve deja espacio para que el desarrollador añada contexto en el momento de la invocación, manteniéndolo de propósito general.
• B. Específico, con $ARGUMENTS, herramientas y audiencia: la versión estructurada, con herramientas permitidas y formato de salida, puede ejecutarse sin que quien la usa tenga que pensar.

Ver respuesta

La opción B es el mejor comando del equipo. El sentido de un comando compartido es que cualquier desarrollador del equipo pueda invocarlo sin reconstruir el prompt desde cero. Especificar las herramientas permitidas, el marcador $ARGUMENTS y el formato de salida dentro del propio comando hace que se ejecute de forma consistente, sin importar quién lo llame ni cuánto contexto tenga en ese momento. La flexibilidad de la opción A es una ilusión: solo traslada el trabajo cognitivo al momento de la invocación, lo que anula el propósito de construir un recurso reutilizable. En los artefactos de entrega del equipo, la especificidad es el objetivo.

Simulación: Diseño de comandos en Vantage

Vantage Capital es una gestora de activos de tamaño medio. Estás configurando Claude Code para el equipo de ingeniería cuantitativa dos semanas antes de un ciclo importante de lanzamiento de modelos. Tres decisiones, seis puntos. Las decisiones tienen consecuencias.

Decisión 1 de 3 · Dónde vive

El equipo ejecuta git log --oneline -20 antes de cada standup para revisar los cambios de la noche. ¿Dónde debe estar el comando?

• A. ~/.claude/commands/ en la máquina del ingeniero líder.
• B. .claude/commands/ en el repositorio, confirmado en git.
• C. Dejarlo como prompt manual: los comandos son para tareas complejas.

Ver respuesta

• A · 1 punto (parcial). Acierto parcial. Un comando personal funciona, pero este ritual de equipo beneficia a todos los desarrolladores. Ponerlo en la carpeta personal obliga a cada persona a crear su propia copia.
• B · 2 puntos (mejor opción). Correcta. Cualquier ritual repetido del equipo pertenece al repositorio del proyecto. Cada desarrollador lo recibe al hacer pull y viaja con el código base.
• C · 0 puntos. Incorrecta. Si el equipo lo ejecuta antes de cada standup, se repite más de dos veces. Ese es exactamente el umbral para crear un comando.

Decisión 2 de 3 · Afina el comando

Una senior quant quiere un comando para explicar cualquier función del código base. Redacta: «Explica esta función.». ¿Cómo debería mejorarse antes de entregarlo?

• A. Entregarlo tal cual: la brevedad lo mantiene flexible.
• B. Añadir $ARGUMENTS para el nombre de la función, fijar allowed-tools en Read y especificar la audiencia (un analista cuantitativo no familiarizado con este módulo).
• C. Añadir solo $ARGUMENTS y mantener todo lo demás al mínimo.

Ver respuesta

• A · 0 puntos. Incorrecta. «Explica esta función» producirá resultados inconsistentes. El modelo tiene que adivinar la audiencia, la profundidad y qué cuenta como una buena explicación. Eso es trabajo del desarrollador, no del modelo.
• B · 2 puntos (mejor opción). Correcta. $ARGUMENTS lo hace reutilizable, allowed-tools evita escrituras de archivos innecesarias y el contexto de audiencia hace que la salida salga calibrada cada vez.
• C · 1 punto (parcial). Crédito parcial. $ARGUMENTS es esencial, pero sin el contexto de audiencia y las restricciones de herramientas, el comando producirá salidas inconsistentes entre los distintos desarrolladores que lo invoquen.

Decisión 3 de 3 · Personal o compartido

Una desarrolladora quiere un comando personal para dar formato a sus notas con un estilo específico que usa. ¿Dónde debe ir?

• A. .claude/commands/ en el repositorio del equipo.
• B. ~/.claude/commands/ en su máquina.
• C. No debería ser un comando en absoluto.

Ver respuesta

• A · 0 puntos. Incorrecta. Una preferencia personal de formato aplicada al repositorio del equipo afecta a todos los que lo clonan. Los comandos personales se quedan personales.
• B · 2 puntos (mejor opción). Correcta. Las preferencias personales van en el directorio de comandos de nivel de usuario. Disponible para ella en todos los proyectos e invisible para los demás.
• C · 1 punto (parcial). Incorrecta. Una tarea personal repetida es exactamente para lo que sirve un comando. El problema es solo dónde vive: en el directorio personal, no en el repositorio del equipo.

Ver cierre de la simulación

• 5–6 puntos · Instintos listos para entregar. Sólidos instintos de diseño de comandos. Sabes cuándo compartir, cuándo mantener algo personal y cómo escribir un comando que realmente se ejecute sin pensar.
• 3–4 puntos · Base sólida. Buena base. La cuestión de la especificidad es la que separa los comandos que se usan de los que se ignoran.
• 0–2 puntos · Repasa los principios. Los comandos personalizados son el artefacto con mayor apalancamiento que puedes dejar a un equipo cliente. Vale la pena dedicar más tiempo a los principios de diseño antes del próximo engagement.

Artefacto del curso

Contribución de la lección 4: entrada en el catálogo de slash commands

1. Escribe tu comando como un archivo .md en .claude/commands/ del repositorio de ejemplo. Usa la plantilla de frontmatter de esta lección.
2. Confirma que aparece en el selector de comandos slash de Claude escribiendo / en una sesión de Claude dentro del repositorio.
3. Añade una descripción de una línea al documento de catálogo de comandos del equipo: nombre del comando, qué hace y para qué roles es más útil. Este documento es el artefacto que entregarás al cliente al cierre del engagement.

Ideas clave

Un archivo en una carpeta. Un comando para el equipo.

Los comandos personalizados son uno de los artefactos de configuración con mayor apalancamiento que puedes dejar a un cliente. Codifican el conocimiento institucional en la propia cadena de herramientas, de modo que la mejor forma de usar Claude no depende de quien la descubrió primero.

• Si pides a Claude algo más de dos veces, conviértelo en un comando dentro de .claude/commands/.
• El nombre del archivo define el comando, y las carpetas crean espacios de nombres (security/audit.md → /security:audit).
• El frontmatter (allowed-tools y description) y $ARGUMENTS permiten acotar herramientas y recibir datos desde la invocación.
• Escribe el comando para que se ejecute sin pensar: específico, con herramientas acotadas y formato de salida definido.
• Los comandos del equipo se confirman en el repositorio; los personales viven en ~/.claude/commands/.

Siguiente: Output styles: cómo Claude comunica