---
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`