Escribir tu primer comando de barra diagonal personalizado con frontmatter de Markdown
Un comando de barra diagonal personalizado es un prompt guardado que invocas por nombre en lugar de volver a escribirlo.
Se almacena como un archivo markdown plano con una cabecera de frontmatter y un cuerpo de prompt debajo.
Resumen
Un archivo de comando tiene exactamente dos partes: frontmatter YAML entre marcadores ---, y un cuerpo de prompt debajo.
El frontmatter contiene metadatos: una descripción corta y, opcionalmente, qué herramientas puede usar el comando.
El cuerpo es el texto literal que se envía a la conversación en el momento en que alguien escribe /nombre-del-comando.
Los comandos tienen ámbito de proyecto, en .claude/commands/, o de usuario, por lo que están disponibles en todos los proyectos que ese usuario abra.
Dado que un comando es solo un archivo, crearlo y compartirlo se reduce a operaciones normales de git, no existe un paso de registro separado.
Receta
---
description: Resumen de una línea que se muestra en el autocompletado de comandos
---
El texto del prompt que se envía cuando se invoca este comando. Escríbelo exactamente
como escribirías tú mismo la solicitud.Guarda esto en .claude/commands/<nombre-del-comando>.md y estará disponible como /<nombre-del-comando> en el siguiente prompt, sin necesidad de reiniciar.
Cuándo usar esto:
- Una solicitud que te encuentras escribiendo más de dos o tres veces.
- Una instrucción de varios pasos de la que es fácil olvidar un paso si se escribe de memoria.
- Una convención de equipo que deseas que todos los colaboradores formulen de la misma manera (una lista de verificación de revisión de PR, un formato de mensaje de commit).
- Un prompt que debe aceptar un objetivo (un archivo, un número de PR, un nombre de característica) a través de
$ARGUMENTS.
Ejemplo de trabajo
---
description: Revisa un pull request en busca de problemas comunes antes de solicitar un revisor humano
allowed-tools: Bash(git diff:*), Bash(git log:*), Read, Grep
---
Revisa los cambios de la rama actual contra main antes de solicitar un revisor humano.
1. Ejecuta `git diff main...HEAD` para ver todo lo que ha cambiado.
2. Comprueba: manejo de errores faltante, registros de depuración sobrantes y cualquier comentario TODO
que deba resolverse antes de fusionar.
3. Confirma que los cambios coinciden con lo que implican el nombre de la rama o el último mensaje de commit.
4. Informa los hallazgos como una lista corta de viñetas, clasificada por gravedad. Si nada destaca,
dilo claramente en lugar de inventar pequeñas críticas.Guarda esto como .claude/commands/pre-review.md. Escribir /pre-review ejecuta la lista de verificación contra la rama que esté actualmente en checkout.
Lo que esto demuestra:
- El frontmatter
descriptionaparece en el autocompletado para que los compañeros de equipo puedan descubrir el comando sin abrir el archivo. allowed-toolslimita lo que el comando puede hacer, aquí restringiendo el acceso a git a operaciones de solo lectura de diff y log, además de la lectura de archivos.- El cuerpo se lee como una lista de verificación numerada porque eso es exactamente lo que se ejecuta, en orden, cuando se ejecuta el comando.
- Aquí no se usa
$ARGUMENTS; el comando siempre opera sobre "la rama que esté actualmente en checkout", que es una forma de comando válida y sin argumentos.
Profundización
Cómo funciona
- Claude Code escanea el directorio de comandos (con ámbito de proyecto o de usuario) y lista cada archivo markdown que encuentra como un
/nombre-del-comandodisponible. - Escribir el comando inserta el cuerpo del archivo en la conversación exactamente como está escrito, en ese punto del turno.
- El frontmatter nunca se envía como parte del prompt; configura cómo se comporta y aparece el comando, no lo que se dice.
- Si tanto un comando con ámbito de proyecto como uno con ámbito de usuario comparten el mismo nombre de archivo, el comando con ámbito de proyecto tiene prioridad para ese proyecto.
- Editar el archivo cambia el comportamiento del comando la próxima vez que se ejecute; no hay caché que borrar ni proceso que reiniciar.
Campos de Frontmatter de un vistazo
| Campo | Requerido | Propósito |
|---|---|---|
description | Recomendado | Resumen de una línea que se muestra en el autocompletado y listados de comandos. |
allowed-tools | Opcional | Restringe qué herramientas tiene permiso de usar el prompt de este comando, más limitado que el valor predeterminado de la sesión. |
argument-hint | Opcional | Una pista corta que se muestra en el autocompletado describiendo lo que espera $ARGUMENTS, por ejemplo, <ruta-de-archivo>. |
model | Opcional | Fija este comando a un modelo específico en lugar de heredar el modelo actual de la sesión. |
Pasar argumentos
---
description: Explica qué hace un archivo específico y quién depende de él
argument-hint: <ruta-de-archivo>
---
Lee $ARGUMENTS y explica su propósito, sus exportaciones públicas y cualquier archivo
en este repositorio que importe de él. Mantén la respuesta por debajo de 150 palabras.$ARGUMENTSse reemplaza con todo lo escrito después del nombre del comando, por lo que/explain-file lib/auth.tsenvíalib/auth.tsen lugar de$ARGUMENTS.- Si el comando se invoca sin texto adicional,
$ARGUMENTSse resuelve como una cadena vacía, así que redacta el prompt para que siga teniendo sentido (o indica explícitamente que se requiere un objetivo). argument-hintes puramente cosmético. Muestra al lector qué escribir, pero no valida ni impone nada en el momento de la invocación.
Notas de Markdown
---
description: Mantén el frontmatter mínimo: solo los campos que el comando usa realmente
---
Prefiere un cuerpo corto y directo en lugar de uno largo. El cuerpo del prompt se lee cada
vez que se ejecuta el comando, por lo que la verbosidad aquí es un costo recurrente, no un
costo único.- El frontmatter es YAML estándar entre marcadores
---; los campos desconocidos generalmente se ignoran en lugar de causar un error, pero cíñete a los campos documentados para evitar sorpresas. - El cuerpo puede ser tan largo como cualquier otro prompt, incluyendo formato markdown, bloques de código y listas numeradas; se envía como texto plano, no se renderiza.
Trampas
- Olvidar el campo
description: el comando todavía funciona, pero se vuelve mucho más difícil para los compañeros de equipo descubrir qué hace solo con el autocompletado. Solución: incluye siempre unadescriptionde una línea, incluso para los comandos que escribiste solo para ti. - Tratar
$ARGUMENTScomo requerido: si el cuerpo del prompt asume que siempre se pasó un objetivo y no se pasó ninguno, el comando se ejecuta con una cadena vacía y produce un resultado confuso. Solución: instruye explícitamente al prompt para que pida un objetivo, o establece un comportamiento predeterminado, cuando$ARGUMENTSesté vacío. - Colisiones de nombres entre comandos de proyecto y de usuario: un comando con ámbito de proyecto oculta silenciosamente un comando con ámbito de usuario del mismo nombre, lo que puede sorprender a alguien que tenga ambos. Solución: usa nombres de archivo distintos y descriptivos, y comprueba
.claude/commands/en busca de nombres existentes antes de añadir uno personal. allowed-toolsdemasiado amplios: dejar esto sin configurar significa que el comando hereda todo el acceso a herramientas de la sesión, incluso para un comando que solo necesita leer archivos. Solución: limitaallowed-toolsexactamente a lo que requieren los pasos del comando.- Confirmar un comando con secretos integrados en el prompt: un archivo de comando confirmado en git es visible para todos los que tengan acceso al repositorio, por lo que incrustar una clave API o una URL interna como "conveniencia" la expone. Solución: haz referencia a variables de entorno o a configuración externa desde el prompt en lugar de codificar valores confidenciales.
- Esperar que el comando valide sus propios argumentos: un comando no tiene esquema ni sistema de tipos para
$ARGUMENTS; es una sustitución de cadena en bruto. Solución: escribe el prompt de forma defensiva, indicando a Claude qué hacer si el argumento parece mal formado o falta.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Escribir la solicitud desde cero cada vez | La solicitud es verdaderamente única y es poco probable que se repita. | Te encuentras escribiendo un prompt casi idéntico más de dos veces. |
| Un hook PostToolUse o PreToolUse | La acción debe ocurrir automáticamente y de forma determinista, sin juicio involucrado. | La tarea requiere razonamiento, recopilación de contexto o una decisión, ya que los hooks no pueden razonar. |
| Un subagente generado ad hoc | La tarea es un trabajo de investigación o exploración único y aislado. | El mismo patrón de delegación se necesitará repetidamente, lo cual se captura mejor como un comando que genera un subagente. |
Preguntas frecuentes
¿Necesito registrar un comando en algún lugar además de crear el archivo?
No. Claude Code descubre comandos escaneando el directorio de comandos; crear el archivo markdown es todo el paso de configuración.
¿Cuál es la diferencia entre comandos con ámbito de proyecto y de usuario?
- Los comandos con ámbito de proyecto viven en
.claude/commands/dentro de un repositorio y se comparten con cualquiera que obtenga ese repositorio. - Los comandos con ámbito de usuario están disponibles en todos los proyectos que un usuario determinado abra, independientemente del repositorio.
- Un comando con ámbito de proyecto con el mismo nombre de archivo tiene prioridad sobre un comando con ámbito de usuario del mismo nombre.
¿Puede el prompt de un comando incluir bloques de código o pasos numerados?
Sí. El cuerpo es texto plano enviado a la conversación, por lo que cualquier formato markdown, incluyendo bloques de código y listas numeradas, se conserva e interpreta normalmente.
¿Qué sucede si invoco un comando sin argumentos pero el prompt usa $ARGUMENTS?
$ARGUMENTS se resuelve como una cadena vacía. El prompt todavía se ejecuta, por lo que debe redactarse para manejar ese caso con gracia en lugar de asumir que un valor siempre está presente.
¿Puede un comando restringir qué herramientas Claude tiene permiso de usar mientras lo ejecuta?
Sí, a través del campo de frontmatter allowed-tools, que limita el acceso a herramientas para la ejecución de ese comando, independientemente de los permisos generales de la sesión.
¿Hay un límite en la longitud del cuerpo del prompt de un comando?
No hay un límite duro documentado, pero un cuerpo largo se envía completo cada vez que se ejecuta el comando, por lo que los prompts concisos son más baratos y fáciles de mantener que los extensos.
¿Puede un comando llamar a otro comando?
El cuerpo del prompt de un comando puede instruir a Claude para que realice los mismos pasos que haría otro comando, pero los comandos no se invocan directamente entre sí como una función llama a una función; el cuerpo es solo texto.
¿Editar el archivo markdown de un comando requiere reiniciar Claude Code?
No. El archivo se lee en el momento de la invocación, por lo que las ediciones surten efecto la próxima vez que se llama al comando.
¿Cómo hago que el propósito de un comando sea descubrible para mi equipo?
Establece el campo de frontmatter description con un resumen claro de una línea; es lo que aparece en el autocompletado cuando un compañero de equipo está explorando los comandos disponibles.
¿Puedo fijar un comando a un modelo específico?
Sí, usando el campo de frontmatter model, que anula el modelo actual de la sesión solo para la invocación de ese comando.
¿Se valida o se comprueba el tipo de $ARGUMENTS de alguna manera?
No. Es una sustitución de cadena en bruto sin esquema, por lo que cualquier validación de la forma o contenido del argumento debe escribirse en el propio prompt.
¿Debería cada solicitud repetida convertirse en un comando personalizado?
No necesariamente. Un comando vale la pena una vez que una solicitud se repite con la frecuencia suficiente como para que guardarla y nombrarla se pague por sí misma; una solicitud verdaderamente única es más simple escrita desde cero.
Relacionados
- Comandos, Hooks y Subagentes Personalizados: Para qué sirve cada uno - cómo encajan los comandos junto con los hooks y subagentes.
- Conceptos básicos de comandos y subagentes personalizados - un primer comando y un primer subagente, uno al lado del otro.
- Ejecutar un comando de shell en PostToolUse con Hooks - la contraparte automática de un comando que un usuario tiene que escribir.
- Mejores prácticas para comandos, hooks y subagentes personalizados - convenciones de nomenclatura y ámbito para comandos.
Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.