diff --git a/.claude/commands/project/create-skill.md b/.claude/commands/project/create-skill.md new file mode 100644 index 0000000..c168be0 --- /dev/null +++ b/.claude/commands/project/create-skill.md @@ -0,0 +1,252 @@ +--- +version: 1.0.0 +updated: 2026-03-21 +tags: [skills, meta, automation, workflow] +--- + +# Command: create-skill + +Crea un nuevo skill en `.claude/skills/` siguiendo la estructura oficial de Claude Code. Cada skill es una carpeta con un archivo `SKILL.md` obligatorio. + +**Flujo completo:** +1. Solicita inputs del skill +2. Crea la carpeta y archivo `SKILL.md` +3. Muestra el contenido al usuario +4. Pregunta si está bien +5. Si el usuario confirma → ejecuta `/git:push` automáticamente + +## Para el usuario + +### Cuándo usar este comando + +- Cuando quieras crear un nuevo skill personalizado +- Para automatizar tareas repetitivas con instrucciones específicas +- Para crear comandos que Claude pueda invocar automáticamente + +### Sintaxis + +```bash +/project:create-skill [nombre] +``` + +### Ejemplos + +**Ejemplo 1:** +```bash +/project:create-skill code-review +``` +Crea un skill para revisión de código en `.claude/skills/code-review/SKILL.md` + +**Ejemplo 2:** +```bash +/project:create-skill deploy +``` +Crea un skill de despliegue con `disable-model-invocation: true` (solo usuario puede invocarlo) + +## Para Claude + +### Precondiciones + +Verificar antes de ejecutar: + +- [ ] Carpeta `.claude/skills/` existe +- [ ] No existe ya un skill con el mismo nombre +- [ ] El nombre cumple convenciones (minúsculas, guiones) + +### Inputs + +Se necesitan los siguientes datos. Si no se proporcionan, preguntar al usuario: + +- `nombre`: nombre del skill (minúsculas y guiones, sin espacios) +- `descripcion`: qué hace el skill y cuándo usarlo (1-2 frases) +- `tipo_invocacion`: quién puede invocarlo + - `ambos` (default): usuario y Claude pueden invocarlo + - `solo_usuario`: solo el usuario puede invocarlo (`disable-model-invocation: true`) + - `solo_claude`: solo Claude puede invocarlo (`user-invocable: false`) +- `argument_hint` (opcional): pista de argumentos, ej: `[archivo] [formato]` +- `allowed_tools` (opcional): herramientas permitidas sin confirmación +- `instrucciones`: contenido markdown con las instrucciones del skill + +### Flujo obligatorio + +#### 1. Validar nombre del skill + +- Solo minúsculas, números y guiones (no underscores ni espacios) +- No usar nombres reservados (help, clear, exit) +- Máximo 64 caracteres + +```bash +ls -d .claude/skills/*/ 2>/dev/null | xargs -n1 basename | grep -E "^${nombre}$" +``` + +Si existe, **STOP** e informar al usuario. + +#### 2. Crear carpeta del skill + +```bash +mkdir -p .claude/skills/${nombre} +``` + +#### 3. Determinar campos del frontmatter + +Según el `tipo_invocacion`: + +| Tipo | disable-model-invocation | user-invocable | +|------|--------------------------|----------------| +| `ambos` | (omitir) | (omitir) | +| `solo_usuario` | `true` | (omitir) | +| `solo_claude` | (omitir) | `false` | + +#### 4. Generar contenido SKILL.md + +Usar el template en `.claude/templates/skill.md` si existe, o generar: + +```markdown +--- +name: ${nombre} +description: ${descripcion} +argument-hint: ${argument_hint} # solo si se proporciona +disable-model-invocation: true # solo si tipo = solo_usuario +user-invocable: false # solo si tipo = solo_claude +allowed-tools: ${allowed_tools} # solo si se proporciona +--- + +# ${nombre} + +${instrucciones} +``` + +**Reglas de generación:** +- Omitir campos opcionales si no se proporcionan +- El campo `name` puede omitirse si coincide con el nombre de la carpeta +- La descripción debe ser clara para que Claude sepa cuándo invocarlo + +#### 5. Escribir archivo SKILL.md + +```bash +cat > .claude/skills/${nombre}/SKILL.md << 'EOF' +${contenido_generado} +EOF +``` + +#### 6. Mostrar el skill creado y confirmar + +{{include: ask-user-confirm}} + +**Mostrar al usuario:** + +``` +Skill creado: ${nombre} + +Ubicación: .claude/skills/${nombre}/SKILL.md + +Contenido: +--- +${contenido_completo} +--- + +¿Te parece bien el skill? +- Si es correcto: se hará commit y push automáticamente +- Si necesitas ajustes: edítalo manualmente antes +``` + +**Esperar respuesta:** +- Si **SÍ** → continuar al paso 7 +- Si **NO** → STOP y decir: "Edita el archivo y cuando estés listo ejecuta `/git:push`" + +#### 7. Ejecutar git-push automáticamente + +Una vez confirmado, ejecutar `/git:push` para: + +1. Crear rama `quick/project:create-skill-${nombre}` +2. Commitear `.claude/skills/${nombre}/SKILL.md` +3. Mergear a master con `--no-ff` +4. Push a remoto +5. Limpiar rama local + +#### 8. Verificar disponibilidad + +Informar al usuario: + +``` +✓ Skill /${nombre} creado e integrado a master + +Para usar: + /${nombre} [argumentos] + +Tipo de invocación: ${tipo_invocacion} +- ambos: tú y Claude pueden invocarlo +- solo_usuario: solo tú con /${nombre} +- solo_claude: Claude lo invoca automáticamente cuando es relevante +``` + +## Convenciones + +- **Nombres descriptivos**: usar verbos o sustantivos claros (`code-review`, `deploy`, `format-code`) +- **Guiones para separar**: `code-review`, no `code_review` ni `codeReview` +- **Descripciones claras**: Claude usa la descripción para decidir cuándo invocar el skill +- **Un skill por tarea**: mantener skills enfocados en una sola responsabilidad + +## Campos del frontmatter (referencia) + +| Campo | Tipo | Descripción | +|-------|------|-------------| +| `name` | string | Nombre del skill (opcional si = carpeta) | +| `description` | string | Qué hace y cuándo usarlo | +| `argument-hint` | string | Pista: `[archivo]`, `[issue-number]` | +| `disable-model-invocation` | bool | `true` = solo usuario invoca | +| `user-invocable` | bool | `false` = solo Claude invoca | +| `allowed-tools` | string | Tools sin pedir permiso: `Read, Grep` | +| `context` | string | `fork` = ejecutar en subagente | +| `agent` | string | Tipo subagente: `Explore`, `Plan` | +| `model` | string | Modelo específico a usar | +| `effort` | string | `low`, `medium`, `high`, `max` | + +## Variables dinámicas (referencia) + +Dentro del contenido del skill puedes usar: + +| Variable | Descripción | +|----------|-------------| +| `$ARGUMENTS` | Todos los argumentos pasados | +| `$0`, `$1`, `$2`... | Argumentos posicionales | +| `${CLAUDE_SKILL_DIR}` | Ruta absoluta del skill | +| `${CLAUDE_SESSION_ID}` | ID de la sesión actual | +| `` !`comando` `` | Ejecutar comando ANTES de enviar a Claude | + +## Troubleshooting + +### Error: "Skill ya existe" + +**Causa:** Ya hay una carpeta con ese nombre en `.claude/skills/` + +**Solución:** +```bash +ls .claude/skills/ +# Elegir otro nombre o eliminar el existente +``` + +### Error: "Nombre inválido" + +**Causa:** El nombre contiene caracteres no permitidos + +**Solución:** +- Solo usar: letras minúsculas, números, guiones +- No usar: espacios, underscores, mayúsculas, caracteres especiales + +### El skill no se invoca automáticamente + +**Causa:** La descripción no es clara o `disable-model-invocation: true` + +**Solución:** +1. Revisar que la descripción incluya palabras clave relevantes +2. Verificar que no tenga `disable-model-invocation: true` +3. Si quieres invocación manual, usar `/${nombre}` + +## Reglas críticas + +- **Validar nombre antes de crear**: evitar sobrescribir skills existentes +- **SKILL.md es obligatorio**: sin él, el skill no funciona +- **Descripción clara**: es clave para invocación automática de Claude +- **Confirmación obligatoria**: siempre mostrar el skill y esperar aprobación +- **Flujo automático**: una vez aprobado, ejecutar `/git:push` diff --git a/.claude/templates/skill.md b/.claude/templates/skill.md new file mode 100644 index 0000000..73c13c8 --- /dev/null +++ b/.claude/templates/skill.md @@ -0,0 +1,34 @@ +--- +name: {{NOMBRE}} +description: {{DESCRIPCION}} +argument-hint: {{ARGUMENT_HINT}} +disable-model-invocation: {{DISABLE_MODEL_INVOCATION}} +user-invocable: {{USER_INVOCABLE}} +allowed-tools: {{ALLOWED_TOOLS}} +--- + +# {{NOMBRE}} + +{{DESCRIPCION_EXTENDIDA}} + +## Instrucciones + +{{INSTRUCCIONES}} + +## Ejemplos de uso + +**Ejemplo 1:** +```bash +/{{NOMBRE}} {{EJEMPLO_ARGS_1}} +``` +{{DESCRIPCION_EJEMPLO_1}} + +**Ejemplo 2:** +```bash +/{{NOMBRE}} {{EJEMPLO_ARGS_2}} +``` +{{DESCRIPCION_EJEMPLO_2}} + +## Notas + +{{NOTAS_ADICIONALES}}