Comandos de barra personalizados de Claude Code

Las Skills (habilidades) son el mecanismo de extensión de Claude Code, a través de comandos de barra personalizados (como/deploy、/explain-code) para potenciar las capacidades de Claude.

Cada comando personalizado es esencialmente un archivo de Skill independiente que puede encapsular flujos de trabajo complejos, estándares de proyecto y operaciones frecuentes, para que puedas invocarlo rápidamente en cualquier sesión.

Los comandos personalizados ya están integrados en el sistema de Skills: los archivos de comandos ubicados en.claude/commands/deploy.mdy los archivos de habilidades ubicados en.claude/skills/deploy/SKILL.mdcrearán comandos/deployque funcionan de la misma manera.

En esencia,.claude/commands/es una forma abreviada de Skills, y ambas estructuras de directorios son completamente equivalentes.


¿Por qué usar comandos de barra personalizados?

El valor central de los comandos de barra personalizados radica enEstandarización + Reutilización:

  • Consolidar flujos de trabajo: encapsular operaciones comunes de varios pasos (como "desplegar a producción") en un solo comando
  • Garantizar la consistencia del equipo: consolidar los estándares del proyecto (como la "lista de verificación de revisión de código") en comandos, garantizando que los miembros del equipo sigan los mismos estándares
  • Reducir la carga cognitiva: no es necesario recordar combinaciones complejas de comandos; una sola frase puede activar un flujo de trabajo completo
  • Reducir entradas repetidas: las tareas frecuentes pasan de operaciones de varios pasos a una sola invocación

La experiencia del equipo interno de Anthropic es: las tareas que se realizan más de dos veces al día deberían convertirse en Skills. Hazlo bien una vez y seguirá siendo efectivo.


Estructura de archivos

Cada Skill es un directorio que contiene un archivo obligatorioSKILL.md:

my-skill/
├── SKILL.md           # 主指令文件(必需)
├── template.md        # Claude 填充的模板
├── examples/
│   └── sample.md      # 展示预期格式的示例
└── scripts/
    └── validate.sh    # Claude 可以执行的脚本

El formato del archivo se divide en dos partes:

  • YAML frontmatter(ubicado entre---los delimitadores): se usa para configurar metadatos
  • Cuerpo de Markdown: las instrucciones que Claude sigue al invocarlo

Crea tu primer comando de barra personalizado

1. Crea el directorio de la habilidad

Crea el directorio de la habilidad en una ubicación adecuada. La ubicación determina el alcance del comando:

mkdir -p ~/.claude/skills/explain-code
# 或者在项目中创建
mkdir -p .claude/skills/explain-code

2. Escribe el archivo SKILL.md

Crea en el directorioSKILL.md, que incluye YAML frontmatter e instrucciones:

Ejemplo

---
name
: explain-code
description
: Explica código con diagramas visuales y analogías. Cuando expliques cómo funciona el código,
expliques la base de código o el usuario pregunte"¿Cómo funciona esto?"úsalo.
---

Al explicar código, incluye siempre lo siguiente:
1. **Comienza con una analogía**: compara el código con objetos de la vida cotidiana
2. **Dibuja un diagrama**: usa arte ASCII para mostrar flujos, estructuras o relaciones
3. **Explica el código paso a paso**: explica lo que sucede paso a paso
4. **Señala un error común**: ¿cuál es el error o malentendido frecuente?

3. Usa el comando personalizado

Invócalo directamente en Claude Code:

/explain-code src/auth/login.ts

Claude emparejará automáticamente la habilidad que coincida con la descripción, o puedes invocarla explícitamente.


Explicación detallada de los campos de configuración

Campo Descripción
name Nombre para mostrar; se convertirá en el comando de barra (formato: letras minúsculas, números, guiones, máximo 64 caracteres)
description Función de la habilidad y cuándo usarla (recomendado; la invocación automática de Claude depende de este campo)
argument-hint Sugerencia que se muestra al autocompletar (por ejemplo,[filename] [format])
disable-model-invocation si se establece entrue, impide que Claude lo invoque automáticamente; solo se activa cuando lo invocas explícitamente
user-invocable si se establece enfalse, se oculta del/menú; solo Claude puede invocarlo
allowed-tools Lista de herramientas que Claude puede usar sin preguntar
context si se establece enfork, se ejecuta en un subagente de rama
agent Establececontext: forkel tipo de subagente que se usa
paths Lista de patrones Glob para limitar el alcance de archivos en los que la habilidad puede activarse

Control de invocación

Controla quién puede invocar la habilidad mediante frontmatter:

Configuración Tú puedes invocar Claude puede invocar
(predeterminado) Sí Sí
disable-model-invocation: true Sí no
user-invocable: false no Sí

Reemplazo de variables

Usa variables en el contenido de la habilidad y Claude las reemplazará automáticamente:

Variable Descripción
$ARGUMENTS Todos los argumentos pasados al invocar
$ARGUMENTS[N] Accede a un argumento específico por índice basado en 0
$N $ARGUMENTS[N]la abreviatura de
${CLAUDE_SESSION_ID} ID de la sesión actual
${CLAUDE_SKILL_DIR} Directorio donde se encuentra el archivo SKILL.md de la habilidad

Ubicación de las habilidades

Las habilidades pueden almacenarse en varias ubicaciones, con diferentes alcances:

Ubicación Ruta Alcance
Nivel empresarial Determinado por la configuración de alojamiento Todos los usuarios de la organización
Personal ~/.claude/skills/<skill-name>/SKILL.md Todos los proyectos
Proyecto .claude/skills/<skill-name>/SKILL.md Solo el proyecto actual
Plugin <plugin>/skills/<skill-name>/SKILL.md Dentro del alcance de habilitación del plugin

.claude/commands/Los archivos en siguen siendo válidos y admiten el mismo frontmatter. Si una habilidad y un comando tienen el mismo nombre, la habilidad tiene prioridad.


Ejemplos avanzados

Ejemplo 1: Comando de despliegue (solo invocación manual)

Ejemplo

---
name
: deploy
description
: Desplegar la aplicación en producción
disable-model-invocation
: true
---

Desplegar $ARGUMENTS en producción:
1. Ejecuta la suite de pruebas
2. Compila la aplicación
3. Empuja al destino de despliegue

Ejemplo 2: Comando de migración de componentes con parámetros

Ejemplo

---
name
: migrate-component
description
: Migrar componentes de un framework a otro
---

Migra el componente $0 de $1 a $2.
Conserva todo el comportamiento y las pruebas existentes.

Uso: /migrate-component SearchBar React Vue

Ejemplo 3: Comando de resumen de PR con contexto dinámico

Ejemplo

---
name
: pr-summary
description
: Resumir los cambios de un Pull Request
context
: fork
agent
: Explore
allowed-tools
: Bash(gh *)
---

## Contexto del Pull Request
- PR diff
: !`gh pr diff`
- Comentarios del PR
: !`gh pr view --comments`
- Archivos cambiados
: !`gh pr diff --name-only`

## Tu tarea
Resume este Pull Request...

Comandos de barra integrados

Claude Code incluye algunos comandos integrados listos para usar:

Comando Función
/batch <instruction> Orquestar cambios a gran escala en todo el repositorio
/claude-api Cargar materiales de referencia de la API
/debug [description] Habilitar registros de depuración
/loop [interval] <prompt> Ejecutar un prompt repetidamente a intervalos
/simplify [focus] Revisar problemas de calidad del código

Mejores prácticas

1. Cómo escribir la descripción

La descripción es la base para que Claude invoque automáticamente; asegúrate de que sea clara:

  • Especifica el momento de activación:Se invoca cuando el usuario solicita revisar / analizar / inspeccionar la calidad del código.
  • Indica las condiciones previas:Se utiliza después de confirmar el documento de especificaciones.
  • Define claramente los límites: en qué casos no debería invocarse

2. Principio de responsabilidad única

Cada habilidad debe hacer una sola cosa, con entradas/salidas claras:

  • /deploy: solo se encarga del despliegue
  • /test: solo se encarga de ejecutar pruebas
  • /review: solo se encarga de la revisión de código

3. Configura los permisos de invocación según sea necesario

  • Operaciones peligrosas (despliegue, eliminación): configuracióndisable-model-invocation: true
  • Tareas auxiliares de Claude: configuraciónuser-invocable: false
  • Flujo general: usar configuración predeterminada

4. Usa allowed-tools para limitar permisos

Establecer privilegios mínimos para operaciones críticas de seguridad:

Ejemplo

---
name
: read-only-analyzer
description
: Análisis de código de solo lectura, para revisar y comprender el código
allowed-tools
: Read, Grep, Glob, Bash(gh *)  # Solo permitir estas herramientas
---

Ejecutar análisis de código de solo lectura...

Estrategia de uso compartido en equipo

Enviar las habilidades a nivel de proyecto a git para que el equipo las comparta:

my-project/
├── .claude/
│   ├── skills/
│   │   ├── deploy/
│   │   │   └── SKILL.md
│   │   ├── test/
│   │   │   └── SKILL.md
│   │   └── review/
│   │       └── SKILL.md
│   └── commands/  # 也可以用 commands/ 目录
└── CLAUDE.md

Hacer referencia y explicar las habilidades específicas del proyecto en CLAUDE.md:

## 自定义斜杠命令

本项目提供以下自定义斜杠命令:

- `/deploy [env]` — 部署到指定环境(dev/staging/prod)
- `/test [module]` — 运行测试套件或指定模块
- `/review` — 执行标准代码审查

详细使用说明请参考 @.claude/skills/README.md

Preguntas frecuentes

P: ¿Cuál es la diferencia entre habilidades y directorio de comandos?

En esencia, no hay diferencia..claude/commands/Sí.claude/skills/Es la forma abreviada de, ambas escrituras funcionan correctamente. Si tienen el mismo nombre, la habilidad tiene prioridad.

P: ¿Cómo pasar múltiples parámetros al llamar?

Envuelva múltiples parámetros con comillas:/migrate SearchBar "from:React to:Vue"y luego use en la habilidad$ARGUMENTSobtener la cadena completa.

P: ¿Se pueden usar las habilidades en subagentes?

Sí. Al establecercontext: forkyagentel campo, se puede permitir que los subagentes ejecuten habilidades en un contexto independiente.

P: ¿Cómo hacer que Claude recuerde las habilidades de uso frecuente?

Enumere todos los comandos personalizados disponibles y sus escenarios de uso en CLAUDE.md; Claude coincidirá automáticamente con la habilidad adecuada según la descripción.

Otras extensiones