Tus propios /comandosconvierte lo que le repites a Claude en un comando que se dispara solo cuando lo dices

01 el punto de partida

Anatomía de un comando

Un comando es un archivo .md cuyo nombre es el nombre del comando: deploy.md crea /deploy. Vive en ~/.claude/commands/ si lo quieres en todos tus proyectos, o en .claude/commands/ dentro de un repo si es de ese proyecto. Adentro tiene dos partes:

---
description: Explica el archivo que te pasen en tres frases. Usa cuando pregunten "qué hace este archivo" o "explícame esto".
---

Explica $ARGUMENTS en tres frases: qué hace, quién lo llama y qué rompería si se borra.

02 la idea central

El description como lista de gatillos

Claude tiene dos maneras de ejecutar un comando: tú escribes /nombre, o Claude decide solo que lo que dijiste encaja con la descripción. Para lo segundo, la descripción tiene que contener las frases que realmente dices. No 'gestiona el cierre de la sesión de trabajo' sino, literal, 'termino por hoy', 'guarda lo que hicimos', 'ya, paso aquí'.

Esta es la fórmula que uso en todos mis comandos. Primero qué hace, en una frase. Luego la palabra 'Usa cuando se mencione' y una lista de frases entre comillas:

---
description: Cierra la sesión guardando el resumen en STATE.md y termina la conversación. Usa cuando se mencione "cerrar sesión", "termino por hoy", "guarda el estado", "guarda lo que hicimos", "registra esta sesión", "voy a cerrar", "ya, paso aquí".
---

• Escribe las frases como las dices tú, con tus muletillas. Si sueles decir 'súbelo', pon 'súbelo', no 'desplegar a producción'.
• Incluye variantes: 'cierra todos', 'cierra todas las sesiones', 'apaga todo'. Cada una es una puerta más.
• Pon el caso de uso principal al inicio. La descripción se corta a 1,536 caracteres en el listado que Claude ve, así que lo importante va primero.
• Si dos comandos comparten frases, Claude puede confundirlos. Dales gatillos que no se crucen o une los comandos.

Si el description te queda largo, hay un campo aparte para las frases: when_to_use. Claude Code lo pega a continuación del description en el listado, así que funciona igual para disparar el comando, pero te deja el description limpio (qué hace) y las frases en su propio renglón. Ojo: los dos juntos cuentan para el mismo tope de 1,536 caracteres.

---
description: Cierra la sesión guardando el resumen en STATE.md y deja lista la siguiente.
when_to_use: "termino por hoy", "guarda lo que hicimos", "ya, paso aquí", "cierra la sesión", "registra esta sesión"
---

03 los campos que sí cambian algo

Frontmatter: lo que vale la pena conocer

Hay más de quince campos posibles. Estos son los ocho que cambian el comportamiento en la práctica; el resto (effort, hooks, disallowed-tools, agent, background) puedes ignorarlo hasta que lo necesites.

La decisión más importante es disable-model-invocation. Un comando que hace algo irreversible no debe poder dispararse porque Claude 'entendió' que querías. Si el comando despliega, cobra o manda mensajes, ponlo en true y lánzalo tú.

04 parámetros

Pasar argumentos

Todo lo que escribas después del nombre del comando llega al cuerpo. $ARGUMENTS es el texto completo; $0, $1, $2 son cada palabra por separado (con comillas para agrupar varias). Si el cuerpo no usa ningún marcador, Claude Code pega el texto al final como 'ARGUMENTS: ...', así que nunca se pierde.

---
description: Crea un componente React con su archivo de estilos y su prueba.
argument-hint: [Nombre] [carpeta]
---

Crea el componente $0 dentro de $1 con tres archivos:
$0.tsx, $0.module.css y $0.test.tsx.
Si $1 está vacío, usa components/.

/componente Boton ui/botones

05 el truco más útil

Inyectar la salida de la terminal antes de que Claude lea

Si una línea del cuerpo empieza con !`comando`, Claude Code ejecuta ese comando y sustituye la línea por su salida antes de mandarle el texto a Claude. Claude no ve el comando: ve el resultado. Es la diferencia entre 'revisa mis cambios' (Claude tiene que ir a buscarlos, y a veces adivina) y darle el diff ya pegado.

---
description: Resume los cambios sin commitear y señala riesgos. Usa cuando se mencione "qué cambié", "resume mis cambios", "revisa el diff", "dame un mensaje de commit".
allowed-tools: Bash(git *)
---

## Cambios actuales

!`git status --short`

!`git diff HEAD`

## Instrucciones

1. Resume los cambios en dos o tres bullets, agrupados por tema (no por archivo).
2. Señala riesgos: manejo de errores faltante, valores fijos en código, pruebas que habría que actualizar.
3. Propón un mensaje de commit de una línea en imperativo.
Si el diff está vacío, di que no hay cambios sin commitear y termina.

Para varias líneas de comandos, en vez de la forma inline se abre un bloque de código con ```! y se cierra normal. Dos detalles: el ! tiene que ir al inicio de línea o tras un espacio, y la salida no se vuelve a escanear (un comando no puede generar otro).

06 para copiar

Tres comandos completos

Los tres están en el repo público de esta guía y cubren los tres patrones que más se repiten: lectura con contexto inyectado (el de arriba), acción con efectos que solo tú lanzas, y alias.

mkdir -p ~/.claude/commands && for c in resumen-cambios deploy-preview estudio; do curl -fsSL https://raw.githubusercontent.com/davidiriza-lab/slash-commands-claude-code/main/commands/$c.md -o ~/.claude/commands/$c.md; done

2. Un despliegue que solo tú puedes lanzar

---
description: Despliega un preview del proyecto actual y devuelve la URL para revisar. Nunca a producción.
argument-hint: [rama opcional]
disable-model-invocation: true
allowed-tools: Bash(git *), Bash(npm run build), Bash(vercel *)
---

Despliega un preview del proyecto en el directorio actual.

1. Si $ARGUMENTS no está vacío, cámbiate a esa rama con git checkout.
2. Corre la build local (npm run build). Si falla, muestra el error y DETENTE: no despliegues nada roto.
3. Despliega como preview (sin la bandera de producción).
4. Responde solo con: la URL del preview, la rama y el hash corto del último commit.

Prohibido: cualquier bandera de producción, cualquier cambio de alias o dominio. Si el usuario lo pide, dile que use el comando de producción por separado.

Fíjate en tres cosas: disable-model-invocation para que 'esto ya está listo' no se convierta en un despliegue; allowed-tools para que no te pida permiso en cada paso de terminal; y una lista explícita de prohibiciones al final. Los comandos con efectos se escriben pensando en lo que NO deben hacer.

3. Un alias de una línea

---
description: Alias de /diseno — dirección de arte antes de construir cualquier pieza visual.
---

Ejecuta el comando /diseno con estos argumentos: $ARGUMENTS

Sirve para tener dos nombres para lo mismo (uno formal y uno que se te sale solo) o para renombrar un comando sin romper el hábito. El cuerpo es una sola línea que delega.

07 quién gana

Global, proyecto, plugin: cómo conviven

En cuanto tienes comandos en dos lugares aparecen las dudas: ¿cuál corre si dos se llaman igual? ¿Tengo que reiniciar cuando edito uno? ¿Los ve Claude si abro la terminal en una subcarpeta? Esto es lo que comprobé contra la documentación:

• Mismo nombre en ~/.claude/ y en el repo: gana el global. Si quieres que un proyecto tenga su propio /deploy distinto del tuyo, ponle otro nombre (deploy-cliente) o no tengas uno global.
• Mismo nombre como archivo suelto (commands/) y como carpeta (skills/): gana la carpeta.
• Un comando tuyo con el nombre de uno integrado (code-review) lo reemplaza, pero los alias del integrado (/review) siguen apuntando al original.
• Los comandos que vienen en un plugin llevan prefijo (/mi-plugin:deploy), así que nunca chocan con los tuyos.
• Editar, crear o borrar un archivo se detecta en la sesión abierta, sin reiniciar. La excepción: si creas la carpeta commands/ o skills/ desde cero, reinicia para que Claude Code empiece a vigilarla.
• Si arrancas en una subcarpeta del repo, los comandos de la raíz se cargan igual. Y en un monorepo, una subcarpeta puede tener sus propios comandos: aparecen con nombre calificado (apps/web:deploy) y aplican cuando Claude trabaja archivos de ahí.
• Las carpetas que agregas con --add-dir o /add-dir no cargan casi nada de configuración, pero los comandos son la excepción: sus .claude/commands/ y .claude/skills/ sí entran.

08 diagnóstico

Cuando un comando no se dispara (o se dispara de más)

Si no se dispara

1. Pregúntale a Claude, en texto normal, qué comandos o skills tiene disponibles. Si el tuyo no aparece, es un problema de ubicación o de YAML, no de gatillos.
2. Si aparece pero no se dispara, escribe la frase exacta que usaste en la vida real y compárala con el description. Casi siempre la frase no está, o está al final y se recortó.
3. Corre /doctor: te estima cuánto contexto ocupa el listado de comandos y quiénes son los que más pesan. Si el listado se pasa del presupuesto (1% de la ventana del modelo), Claude Code recorta descriptions empezando por los comandos que menos invocas, y con ellas se van tus gatillos.
4. En /context, la fila Skills muestra el tamaño real del listado ya recortado. Es la cifra que sí llega al modelo.
5. Lánzalo con /nombre. Si así funciona pero solo nunca, vuelve al YAML: un frontmatter mal cerrado deja el cuerpo vivo y el description vacío.

Si se dispara de más

1. Haz el description más específico: quita frases que también usas para otras cosas ('revisa esto' dispara cualquier cosa).
2. Si el comando tiene efectos, ponle disable-model-invocation: true y listo: solo tú lo lanzas.
3. Si es un comando de un repo compartido y no quieres editar el archivo, abre /skills, selecciónalo y pulsa espacio para cambiarlo a 'solo usuario' o apagarlo; se guarda en .claude/settings.local.json, sin tocar el repo.

09 no todo lo escribes tú

Instalar comandos de otros (y compartir los tuyos)

Como un comando es un archivo, compartirlo es copiar un archivo: el curl de arriba es la forma más honesta. Pero hay dos caminos más cómodos cuando son varios o cuando quieres que se actualicen.

npx skills add mattpocock/skills -l

/plugin install claude-code-setup@claude-plugins-official

Para el otro sentido, publicar los tuyos, ve de menos a más: un repo con la carpeta commands/ y un curl en el README basta para uno o tres comandos. Cuando son una colección con archivos de apoyo, conviértelos en skills (carpeta por comando) para que la CLI de arriba los instale con una línea. El plugin es el último escalón, cuando además quieres empaquetar hooks o MCPs y tener prefijo propio.

10 cuando pasan de cinco

Organizar una colección

• Global vs proyecto: lo que usas en todos lados (sesiones, revisiones, copy) va en ~/.claude/commands/. Lo que solo tiene sentido en un repo (su despliegue, sus plantillas) va en .claude/commands/ de ese repo, y viaja con él.
• Un comando, una acción. Si el cuerpo tiene 'y luego, si el usuario quiere...', son dos comandos.
• Cuando un comando necesita archivos de apoyo (plantillas, listas, ejemplos), conviértelo en skill: una carpeta con SKILL.md y los archivos al lado, referenciados con ${CLAUDE_SKILL_DIR}.
• Versiona los globales. ~/.claude/commands/ como repo de git te da historial y te deja instalarlos en otra máquina con un clone.
• Revisa el listado de vez en cuando: cada description ocupa contexto en todas tus conversaciones. Un comando que no usas hace tres meses se borra, se marca disable-model-invocation o se deja en 'solo nombre' desde /skills.
• Un archivo por comando también en git: cuando un description cambia y el comando deja de dispararse, el diff te dice qué frase quitaste.