Un comando slash personalizado es un archivo Markdown que Claude Code expande en un prompt cuando escribes su nombre. Este laboratorio coloca seis comandos en .claude/commands/, muestra cómo funcionan los argumentos y la portada, y los mantiene fuera del alias /review incluido. Los flags diarios y los archivos de memoria están en la chuleta de Claude Code.
Comandos de proyecto y comandos personales
Los comandos personalizados se fusionaron en habilidades. Un archivo en .claude/commands/deploy.md y una habilidad en .claude/skills/deploy/SKILL.md ambos crean /deploy. Los archivos de comando existentes siguen funcionando. Las habilidades añaden una carpeta para scripts auxiliares y algunos campos que los archivos de comando ignoran. Usa un archivo de comando cuando todo el flujo de trabajo cabe en un archivo Markdown. Usa una habilidad cuando necesites esos archivos extra.
| Alcance | Ruta | Se carga en |
|---|---|---|
| Proyecto | .claude/commands/<archivo>.md en el repo |
Sesiones en este repositorio. Haz commit del archivo |
| Personal | ~/.claude/commands/<archivo>.md |
Todos tus proyectos en esta máquina |
La referencia del directorio lista commands/*.md como proyecto y global, igual que las habilidades. Los archivos globales viven bajo ~/.claude/. En Windows ese directorio es %USERPROFILE%\.claude.
Cuando dos definiciones comparten un nombre de comando, la resolución sigue habilidades:
| Conflicto | Qué ejecuta /nombre |
|---|---|
| Personal y proyecto | El personal |
| Una habilidad y un archivo de comando | La habilidad |
| Tu habilidad y una habilidad incluida | Tu habilidad reemplaza el comando incluido, y los alias incluidos se quedan en el original |
| Tu habilidad y un comando incorporado | En una terminal local, tu habilidad reemplaza el comando incorporado, y los alias incorporados se quedan |
/review es un alias de /code-review incluido. Una habilidad de proyecto llamada code-review reemplaza solo /code-review. Escribir /review sigue ejecutando la revisión incluida. El comando de revisión en este laboratorio es /team:review para que el nombre sea inequívoco.
Los archivos de comando no se observan dentro de directorios que añadiste con --add-dir. Reinicia la sesión después de editar uno allí. Los archivos en .claude/commands/ del proyecto en el que comenzaste se cargan con la sesión.
Las sesiones en la nube no leen ~/.claude/skills/ desde tu laptop. Un comando personal bajo ~/.claude/commands/ es una herramienta de terminal local. Haz commit de comandos de proyecto cuando el equipo deba compartirlos.
Argumentos
Todo después del nombre del comando es la cadena de argumento.
| Marcador de posición | Se expande a |
|---|---|
$ARGUMENTS |
La cadena completa tal como se escribió. Si el archivo nunca lee argumentos, Claude Code añade una línea ARGUMENTS: de todas formas |
$ARGUMENTS[0], $0 |
Primer argumento |
$ARGUMENTS[1], $1 |
Segundo argumento |
Las comillas son de estilo shell. /explain "session cookie" src/auth establece $0 en session cookie y $1 en src/auth. $ARGUMENTS se queda como el texto sin procesar, comillas incluidas como las escribiste.
argument-hint es solo la pista de autocompletado. No analiza nada.
argument-hint: "[path]"
Un valor que el usuario escribe que en sí contiene $1 o $ARGUMENTS se inserta como texto literal. Claude Code no expande marcadores de posición dentro del argumento.
Portada que cambia el comportamiento
Los archivos de comando aceptan portada de habilidad excepto nombre y rutas. El comando que escribes viene de la ruta del archivo. Una clave nombre en un archivo de comando se ignora.
| Campo | Para qué usarlo |
|---|---|
descripción |
Una línea. Claude puede coincidir esto y cargar el comando cuando disable-model-invocation es falso |
argument-hint |
Pista en el menú /, por ejemplo [path] |
allowed-tools |
Herramientas que omiten el prompt de permiso para el turno que invocó el comando. Separadas por espacios, comas o una lista YAML |
modelo |
Modelo para el resto de ese turno. Los mismos valores que /model, o inherit. El modelo de sesión regresa en el siguiente prompt |
disable-model-invocation |
true oculta el comando del uso automático. Todavía lo ejecutas con /nombre |
allowed-tools no elimina otras herramientas. Pre-aprueba las que listas, luego la concesión termina cuando envías el siguiente mensaje. El cuerpo del comando se queda en la conversación. Revisa este campo antes de confiar en un comando que alguien más hizo commit: un comando de repositorio puede otorgarse a sí mismo una regla Bash amplia.
Establece disable-model-invocation: true en cualquier cosa con un efecto secundario, incluidos asistentes de commit y refactores. Déjalo desactivado solo cuando quieras que Claude dispare el comando porque la descripción coincidió con el chat.
modelo: haiku en un comando de explicación mantiene ese turno en el alias más pequeño sin cambiar /model para la sesión. Un alias que tu organización ha bloqueado se omite y el modelo de sesión se queda.
Espacios de nombres con subcarpetas
Un archivo en una subcarpeta de .claude/commands/ obtiene un comando de dos puntos. Cada segmento de carpeta se convierte en un segmento :, luego el nombre del archivo sin .md.
| Archivo | Comando |
|---|---|
.claude/commands/explain.md |
/explain |
.claude/commands/team/review.md |
/team:review |
.claude/commands/frontend/component.md |
/frontend:component |
La misma regla se aplica bajo ~/.claude/commands/. Usa una carpeta cuando el nombre corto ya es un comando incorporado o un alias incluido. Los comandos de complemento añaden el nombre del complemento al frente, como /mi-plugin:bd:migracion, que es un espacio de nombres separado de tus carpetas de proyecto.
Seis comandos que puedes copiar
Crea la carpeta, luego un archivo por sección. Cada comando establece disable-model-invocation: true para que se ejecute cuando escribas su nombre.
mkdir -p .claude/commands/team
Revisión: /team:review
Archivo: .claude/commands/team/review.md
---
description: Review the current diff for bugs, missing tests, and risky config
argument-hint: "[optional path or topic]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash(git status *), Bash(git diff *), Bash(git log *)
model: sonnet
---
Review the working tree. Stay inside $ARGUMENTS when that text names a path or topic.
Otherwise review the full diff.
Read `git status`, `git diff`, and the last five commits for style.
Report only issues you can point at with a file and a reason.
Group findings as blocking, should-fix, and optional.
Do not edit files. Do not propose a commit.
Ejecuta /team:review o /team:review src/billing. El comando /review incluido permanece sin cambios.
Prueba: /test
Archivo: .claude/commands/test.md
---
description: Run the project tests and summarize failures
argument-hint: "[optional test path or name]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash(npm test*), Bash(pytest*)
---
Run the tests. If $ARGUMENTS is non-empty, pass it through as a path or a test name filter.
Prefer the runner this repo already uses. Read the README or package manifest before inventing a command.
When something fails, quote the assertion and name the file.
When everything passes, say so in one line and stop.
/test ejecuta la suite. /test tests/test_auth.py la reduce. Este comando pide a Claude que ejecute pruebas. Un hook que las ejecuta después de cada edición es un mecanismo diferente, cubierto en hooks.
Mensaje de commit: /commit-msg
Archivo: .claude/commands/commit-msg.md
El comando redacta un mensaje. No otorga git commit.
---
description: Draft a commit message from the current diff
argument-hint: "[optional scope hint]"
disable-model-invocation: true
allowed-tools: Bash(git status *), Bash(git diff *), Bash(git log *)
model: haiku
---
Look at status, the unstaged and staged diff, and recent commit subjects.
Write one commit message.
Subject: imperative, 72 characters or fewer.
Body: only if the diff needs a reason that the subject cannot carry.
Use this scope hint when it is present: $ARGUMENTS
Print the message in a single fenced block.
Do not stage files. Do not create a commit.
/commit-msg auth impulsa el tema hacia esa área. Copia el bloque en git commit tú mismo, o pregunta en un mensaje de seguimiento si quieres que Claude haga commit después de que hayas leído el mensaje.
Explicar: /explain
Archivo: .claude/commands/explain.md
---
description: Explain a file, symbol, or diff in plain language
argument-hint: "[path or symbol]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
model: haiku
---
Explain $ARGUMENTS.
Start with what it does in two sentences.
Then the inputs and outputs, then one sharp edge a caller can hit.
Quote short snippets. Link symbols to the file you read.
If $ARGUMENTS is empty, ask which file to open.
/explain @src/worker.py sigue funcionando porque @ es la mención de archivo usual de la chuleta. $ARGUMENTS recibe el texto que escribiste después de /explain.
Refactorizar: /refactor
Archivo: .claude/commands/refactor.md
---
description: Refactor a named file or symbol without changing behavior
argument-hint: "[path or symbol]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Write, Bash(npm test*), Bash(pytest*)
model: sonnet
---
Refactor $ARGUMENTS. Keep behavior the same.
Before editing, state the change in three lines: what moves, what stays, how you will check.
Touch only the files required for that change.
After editing, run the smallest test command that covers the change.
If you cannot find a test, say so and stop before a wide rewrite.
allowed-tools otorga dura el turno que comenzó con /refactor. El siguiente mensaje pide permiso de nuevo bajo tus reglas normales.
Documentos: /docs
Archivo: .claude/commands/docs.md
---
description: Update the docs that match a code change
argument-hint: "[path or topic]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Write
model: haiku
---
Update documentation so it matches the current code for $ARGUMENTS.
Prefer an existing doc file over a new one.
Describe the behavior a caller can observe.
Do not add a changelog entry unless the repo already keeps one next to this feature.
If code and docs disagree, trust the code and say which line you used.
Una línea ! dentro del archivo
El modo shell interactivo, el ! que escribes en el prompt, es separado de esto. Una línea en un archivo de comando que comienza con ! seguida de un comando entre backticks se ejecuta mientras se expande el comando. Claude ve la salida del comando, no el texto del comando.
Current status:
!`git status --short`
Esa inyección se ejecuta a través de la herramienta de shell, y tus reglas de permiso siguen aplicándose. Establece disableSkillShellExecution en verdadero en configuración cuando la política debe reemplazar esas líneas con un aviso deshabilitado. Las habilidades sincronizadas desde una cuenta claude.ai no ejecutan estos comandos en tu máquina.
Usa inyección cuando el prompt es inútil sin datos en vivo, como git diff. Usa allowed-tools más instrucciones cuando Claude debe elegir el comando.
Cuándo un comando es la herramienta equivocada
Un comando carga su cuerpo en la conversación principal y lo deja allí. Eso es lo que quieres para una lista de verificación que seguirás discutiendo.
Mueve el trabajo a un subagente cuando la exploración inundaría el chat con resultados de búsqueda. Muévelo a un hook cuando debe ejecutarse en cada edición tanto si alguien recuerda el comando slash como si no. Los hechos duraderos que pertenecen en cada sesión se quedan en CLAUDE.md, que la chuleta expone. Un comando es un procedimiento reutilizable dentro de una sesión agentiva más larga, no un segundo archivo de memoria.
Después de añadir los archivos, abre un nuevo prompt y escribe / luego team para confirmar que /team:review está en la lista. Si un comando falta, la sesión fue comenzada en modo descubierto o con la configuración del proyecto desactivada, o el nombre del archivo choca con un comando incorporado reservado. Renómbralo o ponlo en una subcarpeta.
Preguntas frecuentes
¿Dónde van los comandos slash personalizados de Claude Code?
Pon un archivo Markdown en .claude/commands/ para compartirlo con el repo, o en ~/.claude/commands/ para usarlo en cada proyecto en tu máquina. El nombre del archivo se convierte en el comando. En Windows, ~/.claude es %USERPROFILE%\.claude. Un directorio de habilidades en .claude/skills/<nombre>/SKILL.md crea el mismo tipo de comando /nombre y gana si existen ambos.
¿Cómo paso argumentos a un comando slash de Claude Code?
El texto después del nombre del comando es la cadena de argumento. En el archivo, $ARGUMENTS se expande a toda la cadena. $0 o $ARGUMENTS[0] es la primera palabra, y $1 es la segunda. Envuelve un valor de varias palabras entre comillas cuando invokes el comando. argument-hint en la portada es la pista de autocompletado, como [path].
¿Cuál es la diferencia entre un comando de proyecto y un comando de usuario?
Un archivo bajo el repositorio .claude/commands/ es alcance de proyecto e intenta comprometerse. Un archivo bajo ~/.claude/commands/ es personal y se carga en todos tus proyectos locales. Los comandos usan el mismo mecanismo que las habilidades: una definición personal supera una definición de proyecto cuando el nombre del comando coincide, y una habilidad supera un archivo de comando con el mismo nombre.
¿Por qué mi comando /review sigue ejecutando la revisión incorporada?
/review es el alias de la habilidad /code-review incluida. Una habilidad personalizada llamada code-review reemplaza /code-review y no reemplaza ese alias. Nombra tu lista de verificación de otra forma, o ponla en una subcarpeta para que el comando sea /team:review.
¿Qué claves de portada acepta un archivo de comando?
Los archivos de comando aceptan campos de habilidad excepto nombre y rutas, que se ignoran. Los útiles son descripción, argument-hint, allowed-tools, modelo y disable-model-invocation. Invocas el archivo por su ruta bajo commands/, no por una clave nombre.
Cómo se verificó esta guía
Escrita a mano a partir de la documentación oficial, con cada comando comprobado de nuevo y una segunda revisión antes de publicar. Última revisión: .
Fuentes oficiales consultadas para este artículo