Crear Skills: extender Claude Code con instrucciones reutilizables

Descripción

Los Skills son la forma en que extiendes Claude Code con capacidades reutilizables. Son directorios con un archivo SKILL.md (más archivos de soporte opcionales) que viven en .claude/skills/. Claude Code los detecta automáticamente — y puede invocarlos de dos maneras: tú con un slash command (/nombre-skill), o Claude mismo cuando detecta que el skill es relevante para lo que le pediste.

Esta cápsula cubre el formato actual de Skills: la estructura de directorio, el YAML frontmatter que configura el comportamiento, la diferencia entre invocación manual y automática, cómo Skills se relacionan con CLAUDE.md, y los Skills bundled que vienen con Claude Code. El formato de Skills sigue el estándar abierto Agent Skills, que funciona en múltiples herramientas de AI.

La diferencia entre un usuario que repite instrucciones en cada prompt y uno que tiene Skills configurados es la diferencia entre escribir código a mano y usar snippets — con la capacidad adicional de que Claude puede invocar el Skill por sí mismo cuando lo considere apropiado.

Qué son los Skills

Un Skill es un directorio en .claude/skills/ con al menos un archivo SKILL.md. Cuando tú o Claude invocan un Skill, Claude:

1. Lee el archivo SKILL.md
2. Incorpora las instrucciones como contexto adicional
3. Ejecuta la tarea siguiendo esas instrucciones
4. Opcionalmente accede a archivos de soporte dentro del directorio del skill (templates, scripts, ejemplos)

El SKILL.md tiene dos partes: YAML frontmatter entre --- que configura el skill, y contenido markdown con las instrucciones que Claude sigue.

Nota sobre el cambio de formato

Los comandos personalizados (.claude/commands/name.md) se fusionaron en Skills. El formato antiguo sigue funcionando, pero Skills son el recomendado. Skills agregan: un directorio para archivos de soporte, frontmatter YAML para controlar invocación, y la capacidad de que Claude los cargue automáticamente cuando son relevantes.

Dónde viven los Skills (4 scope levels)

Dónde guardas un Skill determina quién puede usarlo:

Prioridad cuando hay conflictos de nombre: enterprise > personal > project. Los plugins usan un namespace plugin-name:skill-name, por lo que no chocan.

Cuándo usar cada nivel

Personal (~/.claude/skills/):
  → Skills que usas en todos tus proyectos
  → Ejemplo: /commit (tu workflow de commits)
  → Ejemplo: /review (tu estilo de code review)

Project (.claude/skills/):
  → Skills específicos de un proyecto
  → Commiteable al repo — tu equipo los comparte
  → Ejemplo: /deploy-staging (deploy a tu infra)
  → Ejemplo: /new-component (tu patrón de React components)

Plugin:
  → Skills distribuidos via plugin marketplace
  → No los creas tú — los instalas

Enterprise:
  → Configurados por administradores
  → Aplican a toda la organización

Anatomía de un Skill

Un Skill es un directorio, no un archivo. El SKILL.md es el entrypoint, pero puedes incluir archivos adicionales:

my-skill/
├── SKILL.md           # Instrucciones principales (obligatorio)
├── template.md        # Template para que Claude llene
├── examples/
│   └── sample.md      # Ejemplo del output esperado
└── scripts/
    └── validate.sh    # Script que Claude puede ejecutar

SKILL.md es obligatorio. Los demás archivos son opcionales y dan más poder: templates, ejemplos, scripts ejecutables, documentación de referencia detallada. Haz referencia a estos archivos desde SKILL.md para que Claude sepa qué contienen y cuándo cargarlos.

Regla clave: Mantén SKILL.md bajo 500 líneas. Mueve material de referencia detallado a archivos separados.

YAML Frontmatter: configurar el comportamiento del Skill

El frontmatter YAML al inicio de SKILL.md controla cómo funciona el Skill:

---
name: my-skill
description: Qué hace este skill y cuándo usarlo
disable-model-invocation: true
allowed-tools: Read Grep
---

Aquí van las instrucciones en markdown...

Todos los campos son opcionales. Solo description es recomendado para que Claude sepa cuándo usar el skill.

Campos del frontmatter

Control de invocación: quién puede invocar un Skill

Cuándo usar cada uno:

• Default: Skills con efectos seguros que pueden ser útiles proactivamente
• disable-model-invocation: true: Workflows con efectos secundarios o timing crítico (/commit, /deploy, /send-slack-message). No quieres que Claude decida deployar porque el código parezca listo.
• user-invocable: false: Conocimiento de fondo que no es accionable como comando. Un skill legacy-system-context explica cómo funciona un sistema viejo — útil para Claude, no accionable para ti.

Skill vs CLAUDE.md

Esta distinción es fundamental:

Regla práctica: Si la instrucción aplica a TODO lo que Claude hace en tu proyecto → CLAUDE.md. Si aplica solo a una tarea específica o es material de referencia largo → Skill.

Ejemplo de la distinción

CLAUDE.md:

## Convenciones de código
- TypeScript estricto
- CSS Modules para estilos
- Tests con Vitest

.claude/skills/create-component/SKILL.md:

---
name: create-component
description: Crear un nuevo componente React siguiendo las convenciones del proyecto. Usar cuando el usuario pida crear un componente nuevo.
---

Al crear un componente:
1. Crea el archivo en src/components/[Name]/[Name].tsx
2. Usa TypeScript con interface para props
3. Crea [Name].module.css
4. Crea __tests__/[Name].test.tsx
5. Crea index.ts con barrel export

CLAUDE.md dice "usamos CSS Modules". El skill dice "cuando crees un componente, aquí están los pasos exactos".

Crear tu primer Skill paso a paso

Vamos a crear un skill simple: explain-code que explica cómo funciona el código con analogías y diagramas ASCII.

Paso 1: Crea el directorio del skill

mkdir -p ~/.claude/skills/explain-code

Usamos ~/.claude/skills/ (personal) para que esté disponible en todos los proyectos. Si quieres que sea solo del proyecto actual, usa .claude/skills/explain-code dentro del proyecto.

Paso 2: Crea el archivo SKILL.md

touch ~/.claude/skills/explain-code/SKILL.md

Paso 3: Escribe el frontmatter y las instrucciones

Abre SKILL.md y escribe:

---
name: explain-code
description: Explica cómo funciona código con diagramas visuales y analogías. Usar cuando alguien pregunte "cómo funciona esto?", cuando esté aprendiendo un codebase, o al enseñar conceptos técnicos.
---

Al explicar código, siempre incluye:

1. **Empieza con una analogía:** Compara el código con algo de la vida diaria
2. **Dibuja un diagrama:** Usa ASCII art para mostrar flujo, estructura o relaciones
3. **Walk-through paso a paso:** Explica qué pasa en cada línea importante
4. **Un gotcha común:** Un error o malentendido frecuente

Mantén las explicaciones conversacionales. Para conceptos complejos, usa múltiples analogías.

Paso 4: Prueba el Skill de dos formas

Invocación manual con el slash command:

> /explain-code src/auth/login.ts

Invocación automática — Claude detecta que es relevante por la description:

> ¿cómo funciona este código?

En ambos casos, Claude incluye una analogía y un diagrama ASCII en su explicación.

Paso 5: Verifica que funciona

Al ejecutar, Claude debería:

1. Cargar el contenido del SKILL.md
2. Aplicar las instrucciones (analogía, diagrama, walk-through, gotcha)
3. Responder siguiendo ese patrón

Arguments: pasar parámetros al Skill

Tanto tú como Claude pueden pasar argumentos al invocar un Skill. Los argumentos están disponibles via $ARGUMENTS o por índice con $0, $1, $2.

Ejemplo: skill que arregla un issue de GitHub

---
name: fix-issue
description: Arregla un issue de GitHub
disable-model-invocation: true
---

Arregla el issue de GitHub $ARGUMENTS siguiendo nuestros coding standards.

1. Lee la descripción del issue
2. Entiende los requirements
3. Implementa el fix
4. Escribe tests
5. Crea un commit

Al ejecutar /fix-issue 123, Claude recibe: "Arregla el issue de GitHub 123 siguiendo nuestros coding standards..."

Argumentos posicionales con $0, $1, $2

---
name: migrate-component
description: Migra un componente de un framework a otro
---

Migra el componente $0 de $1 a $2.
Preserva todo el comportamiento y tests existentes.

Ejecutando /migrate-component SearchBar React Vue:

• $0 → SearchBar
• $1 → React
• $2 → Vue

Nota: Usa comillas para valores con espacios: /migrate-component "Search Bar" React Vue hace que $0 sea Search Bar.

Otras substituciones disponibles

Archivos de soporte

Los Skills pueden incluir múltiples archivos en su directorio. Esto mantiene SKILL.md enfocado en lo esencial mientras Claude accede a material de referencia detallado solo cuando lo necesita.

api-patterns/
├── SKILL.md           # Overview y navegación
├── reference.md       # API docs detallada
├── examples.md        # Ejemplos de uso
└── scripts/
    └── helper.py      # Script ejecutable

Haz referencia a los archivos de soporte desde SKILL.md:

## Recursos adicionales

- Para detalles completos de la API, ver [reference.md](reference.md)
- Para ejemplos de uso, ver [examples.md](examples.md)
- Para validar configuración, ejecutar [scripts/helper.py](scripts/helper.py)

Tip: Mantén SKILL.md bajo 500 líneas. Mueve material extenso a archivos separados.

Bundled Skills: los que vienen con Claude Code

Claude Code incluye Skills pre-configurados disponibles en toda sesión:

Se invocan como cualquier otro skill: / + nombre. Puedes ver la lista completa en los commands reference.

Pre-aprobar tools con allowed-tools

El campo allowed-tools del frontmatter otorga permiso a las tools listadas mientras el skill esté activo — Claude puede usarlas sin pedir aprobación por cada uso.

---
name: commit
description: Stage y commit de los cambios actuales
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Con este skill activo, Claude ejecuta git add, git commit, y git status sin pedir aprobación. No restringe qué tools están disponibles — solo pre-aprueba las listadas.

Live change detection

Claude Code monitorea los directorios de skills para cambios en vivo. Agregar, editar o eliminar un skill en ~/.claude/skills/ o .claude/skills/ aplica en la sesión actual sin reiniciar.

Excepción: Crear un directorio .claude/skills/ nuevo que no existía al inicio de la sesión requiere reiniciar Claude Code para que empiece a monitorearlo.

Troubleshooting

Skill no se activa automáticamente

Si Claude no usa tu skill cuando esperas:

1. Revisa la description: Debe incluir keywords que los usuarios naturalmente dirían
2. Verifica que aparece en la lista: Pregunta a Claude "¿qué skills tienes disponibles?"
3. Rephrasea tu request: Hazlo coincidir más con la description
4. Invócalo manualmente: /nombre-skill para forzar la invocación

Skill se activa demasiadas veces

Si Claude invoca el skill cuando no quieres:

1. Haz la description más específica: Menos keywords genéricos
2. Agrega disable-model-invocation: true si solo quieres invocación manual

Descriptions se cortan

Las descriptions de skills se cargan en contexto con un budget de caracteres. Si tienes muchos skills, las descriptions se acortan. La solución:

• Pon la clave al inicio de la description (front-loaded)
• Reduce texto innecesario
• Sube el budget con la variable SLASH_COMMAND_TOOL_CHAR_BUDGET

Skill no aparece después de crearlo

Si acabas de crear un skill y no aparece:

1. Verifica la ruta: .claude/skills/<nombre>/SKILL.md (con el directorio intermedio)
2. Verifica el frontmatter: Los --- al inicio y fin son necesarios
3. Restart Claude Code: Si creaste un directorio .claude/skills/ que no existía

Ejercicios

Ejercicio 1: Tu primer skill personal

Crea un skill personal (~/.claude/skills/) llamado commit que hace:

1. Stage todos los cambios
2. Genera un commit message siguiendo Conventional Commits
3. Ejecuta el commit
4. Incluye disable-model-invocation: true (no quieres que Claude commitee solo)

---
name: commit
description: Stage y commit de los cambios con un mensaje siguiendo Conventional Commits
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) Bash(git diff *)
---

Crea un commit de los cambios actuales:

1. Ejecuta `git status` para ver qué cambió
2. Ejecuta `git diff --staged` y `git diff` para entender los cambios
3. Stage los archivos relevantes con `git add`
4. Genera un commit message siguiendo Conventional Commits:
   - `feat:` nueva funcionalidad
   - `fix:` bug fix
   - `refactor:` cambio de código sin cambio de comportamiento
   - `docs:` solo documentación
   - `test:` tests
   - `chore:` mantenimiento
5. Ejecuta el commit

El mensaje debe ser claro, en español, y explicar el "por qué" del cambio cuando aplique.

Ejercicio 2: Skill de proyecto con argumentos

Crea un skill de proyecto (.claude/skills/) llamado new-component que:

1. Toma un nombre de componente como argumento
2. Crea la estructura completa del componente
3. Se invoca con /new-component UserProfile

---
name: new-component
description: Crear un nuevo componente React con estructura estándar del proyecto
argument-hint: [ComponentName]
---

Crea un nuevo componente React llamado $0 con esta estructura:

1. Crea el directorio: `src/components/$0/`
2. Crea `src/components/$0/$0.tsx`:
   - Componente funcional con TypeScript
   - Interface `$0Props` con las props
   - Export default
3. Crea `src/components/$0/$0.module.css` con una clase base `.container`
4. Crea `src/components/$0/__tests__/$0.test.tsx` con:
   - Test de render básico
   - Test de props
5. Crea `src/components/$0/index.ts` con barrel export

No uses `any`, no uses `React.FC`. Usa `function` declaration, no arrow function.

Ejercicio 3: Skill con archivos de soporte

Crea un skill pr-review que:

1. Tiene un SKILL.md ligero con overview
2. Tiene un checklist.md con la checklist detallada de review
3. Referencia checklist.md desde SKILL.md

---
name: pr-review
description: Review sistemático de un Pull Request siguiendo la checklist del equipo
---

Review este Pull Request siguiendo la checklist completa en [checklist.md](checklist.md).

Formato del review:
- Empieza con un summary de 2-3 líneas
- Organiza feedback por categoría (según la checklist)
- Separa "must fix" de "nice to have"
- Al final, da una recomendación: approve / request changes / comment

# Checklist de PR Review

## Funcionalidad
- [ ] El código hace lo que dice el PR
- [ ] Edge cases considerados
- [ ] Error handling apropiado

## Calidad de código
- [ ] Nombres claros
- [ ] Sin código muerto
- [ ] Complejidad razonable

## Tests
- [ ] Tests nuevos para nueva funcionalidad
- [ ] Tests existentes pasan
- [ ] Coverage de edge cases

## Documentación
- [ ] README actualizado si aplica
- [ ] Comentarios donde el "por qué" no es obvio

Ejercicio 4: Decidir qué va en Skill vs CLAUDE.md

Para cada item, decide si va en CLAUDE.md o en un Skill:

1. "Usamos TypeScript estricto en todo el proyecto"
2. "Cuando crees un endpoint, valida inputs con Zod"
3. "El backend vive en apps/api, el frontend en apps/web"
4. "Para hacer deploy, ejecuta ./scripts/deploy.sh y espera confirmación"
5. "Tests con Vitest, no Jest"

Resumen

• Los Skills son directorios con SKILL.md + YAML frontmatter (formato actual, reemplaza los commands planos)
• 4 scope levels: enterprise > personal (~/.claude/skills/) > project (.claude/skills/) > plugin
• description en frontmatter permite que Claude invoque el skill automáticamente cuando es relevante
• disable-model-invocation: true → solo tú invocas (deploy, commit, acciones con efectos)
• user-invocable: false → solo Claude invoca (conocimiento de fondo)
• allowed-tools pre-aprueba tools cuando el skill está activo
• Argumentos: $ARGUMENTS, $0, $1, etc.
• Bundled skills: /simplify, /batch, /debug, /loop, /claude-api
• Skills vs CLAUDE.md: CLAUDE.md es contexto permanente; Skills son instrucciones cargadas bajo demanda
• Mantén SKILL.md bajo 500 líneas — mueve detalle a archivos de soporte
• Live change detection: agregar/editar skills aplica sin reiniciar

Recursos Adicionales

1. Claude Code Skills — Documentación oficial — Referencia completa y actualizada
2. Agent Skills Standard — Estándar abierto que Claude Code implementa
3. Claude Code Commands Reference — Lista de bundled skills y commands built-in
4. Subagents — Delegar skills a agentes especializados (context: fork)
5. Plugins — Empaquetar y distribuir skills con plugins
6. Hooks — Automatizar workflows alrededor de eventos de tools