Claude Code skills: cómo crear las tuyas

Sin skills, repites las mismas instrucciones en cada sesión: "revisa el código buscando bugs", "genera tests para esta función", "crea documentación del endpoint". Con skills, escribes /review, /test o /docs y listo. Es la diferencia entre escribir un script o ejecutar comandos manualmente cada vez.

Si ya usas Claude Code a diario, los skills te ahorran minutos en cada sesión. Multiplicado por semanas y meses, es un ahorro enorme en tiempo y en tokens (instrucciones más cortas = menos coste).

Anatomía de un skill

Un skill es un archivo Markdown. Eso es todo a nivel técnico. Pero un skill bien diseñado tiene componentes específicos que lo hacen efectivo:

# Nombre del Skill (título = propósito en una línea)

## Descripción (opcional pero recomendado)
Qué hace este skill en 1-2 frases.

## Instrucciones
Pasos que Claude Code debe seguir, en orden.

## Formato de salida
Cómo debe presentar el resultado.

## Reglas
Qué NO hacer, límites, prioridades.

## Trigger (opcional)
Condiciones para activar el skill automáticamente.

Cada componente tiene un propósito:

• Título: Claude Code lo usa para entender el propósito general del skill
• Instrucciones: los pasos concretos. Cuanto más precisos, mejor resultado
• Formato de salida: garantiza consistencia. Sin esto, cada ejecución tiene un formato diferente
• Reglas: evita comportamientos no deseados. Los "NUNCA" son tan importantes como los pasos
• Trigger: permite activación automática cuando se detecta cierto patrón

Cómo crear tu primer skill desde cero

Un skill es un archivo Markdown en la carpeta correcta. Tres pasos:

# Paso 1: Crear la carpeta de skills (si no existe)
mkdir -p .claude/skills

# Paso 2: Crear el archivo del skill
touch .claude/skills/review.md

# Paso 3: Escribir las instrucciones (con tu editor favorito)

Contenido de .claude/skills/review.md:

# Code Review

Revisa el código cambiado (git diff) buscando:

1. **Bugs potenciales**: null checks, race conditions, off-by-one
2. **Seguridad**: inputs sin validar, SQL injection, XSS
3. **Performance**: N+1 queries, loops innecesarios, memoria
4. **Estilo**: naming inconsistente, funciones > 30 líneas
5. **Tests**: cobertura de los cambios

## Formato de salida
Para cada hallazgo:
- Archivo y línea
- Severidad (CRITICAL / WARNING / INFO)
- Descripción del problema
- Sugerencia de fix (código)

## Reglas
- Solo reporta problemas reales, no opiniones de estilo
- Si no hay problemas, di "LGTM" y por qué
- Máximo 10 hallazgos, priorizados por severidad

Ahora, en Claude Code, escribe /review y se ejecuta automáticamente. Claude Code lee el archivo, sigue las instrucciones, y te devuelve el resultado en el formato especificado.

Skills globales vs skills de proyecto:

• .claude/skills/review.md — Skill del proyecto. Solo disponible en este repo. Se commitea en git.
• ~/.claude/skills/review.md — Skill global. Disponible en todos los proyectos. Personal.

Recomendación: pon en global los skills genéricos (code review, commit). Pon en el proyecto los skills específicos (deploy a tu infra, tests con tu framework).

Estructura de un skill efectivo

Los mejores skills tienen esta estructura:

1. Título claro: Qué hace el skill en una línea.
2. Instrucciones paso a paso: Qué debe hacer Claude Code, en orden.
3. Formato de salida: Cómo debe presentar el resultado.
4. Reglas y restricciones: Qué NO hacer, límites, prioridades.
5. Trigger (opcional): Condiciones para activar el skill automáticamente.

Triggers: activación automática

Los triggers permiten que un skill se active automáticamente cuando se detecta cierto contexto o patrón. Se definen en la sección "Trigger" del skill o mediante hooks en settings.json.

Trigger por patrón de texto:

# En el skill:
## Trigger
Activar cuando el usuario mencione "review", "code review",
"revisa el código" o "busca bugs".

Trigger por hook (settings.json):

// .claude/settings.json
{
  "hooks": {
    "pre-commit": {
      "command": "/review"
    },
    "post-edit": {
      "command": "/test",
      "pattern": "src/api/**/*.ts"
    }
  }
}

Con hooks, puedes hacer que /review se ejecute automáticamente antes de cada commit, o que /test se lance cada vez que se modifica un archivo de la API. Es automatización dentro de automatización.

Parámetros y argumentos

Los skills pueden recibir argumentos que modifican su comportamiento. Cuando escribes /review src/api/, el texto después del comando se pasa como contexto al skill.

# Invocaciones con parámetros:
/review                     → Revisa todo el diff (git diff)
/review src/api/users.ts    → Revisa solo ese archivo
/review --security          → Revisa solo seguridad
/test src/services/auth.ts  → Genera tests para ese archivo
/deploy staging             → Deploy a staging (no producción)

Para que un skill use parámetros efectivamente, inclúyelo en las instrucciones:

# Deploy

## Instrucciones
1. Si se específica un entorno (staging/production), usa ese.
   Si no, usa staging por defecto.
2. Si el entorno es "production":
   - Ejecuta tests primero
   - Pide confirmación antes de deployar
   - Verifica que estás en branch main
3. Si el entorno es "staging":
   - Deploy directo sin confirmación
   - Cualquier branch es válida

8 skills que deberías crear

1. /review — Code review automático

Ya lo vimos arriba. Revisa los cambios buscando bugs, seguridad y estilo. Es el skill más usado.

2. /test — Generar tests

# Generar Tests
Lee el archivo especificado y genera tests unitarios.
- Framework: [pytest / vitest / jest] según el proyecto
- Cobertura: happy path + edge cases + error handling
- Naming: test_[función]_[escenario]_[resultado_esperado]
- Ejecuta los tests después de crearlos y reporta el resultado
- Si algún test falla, corrígelo antes de terminar

3. /docs — Documentar endpoint

# Documentar Endpoint
Lee el endpoint especificado y genera documentación:
- Método y ruta
- Descripción (1-2 frases)
- Parámetros (nombre, tipo, obligatorio, descripción)
- Respuestas (código HTTP, body de ejemplo)
- Ejemplo de curl
Formato: Markdown compatible con MkDocs

4. /commit — Commit con mensaje inteligente

# Smart Commit
1. Lee git diff --staged
2. Genera un commit message en conventional commits:
   - feat: nueva funcionalidad
   - fix: corrección de bug
   - docs: documentación
   - refactor: restructuración sin cambio funcional
3. El subject tiene máximo 50 caracteres
4. El body explica el "por qué" (no el "qué")
5. Crea el commit

5. /simplify — Simplificar código

# Simplificar Código
Lee el archivo o función especificado y busca:
- Código duplicado que se puede extraer
- Condicionales que se pueden simplificar
- Funciones que se pueden dividir
- Variables con nombres mejorables
Aplica los cambios y muestra un diff antes/después.

6. /security — Auditoría de seguridad

# Security Audit
Revisa el código buscando vulnerabilidades:
- SQL injection (parámetros sin sanitizar)
- XSS (output sin escapar)
- CSRF (endpoints sin protección)
- Secrets hardcoded (API keys, passwords en código)
- Dependencias con CVEs conocidas
Severidad: CRITICAL > HIGH > MEDIUM > LOW
Solo reporta hallazgos verificables, no teóricos.

7. /migrate — Migración de dependencias

# Migrate Dependency
1. Identifica todos los imports del paquete antiguo
2. Reemplaza por equivalentes del paquete nuevo
3. Ajusta la API si hay breaking changes
4. Ejecuta tests para verificar que nada se rompe
5. Actualiza package.json / requirements.txt
Reporta: archivos modificados, imports cambiados, tests pass/fail

8. /deploy — Deploy inteligente

# Deploy
1. Verifica que no hay cambios sin commitear
2. Ejecuta tests (npm test / pytest)
3. Si tests pasan:
   - staging: deploy directo
   - production: pide confirmación, verifica branch main
4. Ejecuta el comando de deploy según entorno
5. Verifica health check post-deploy
6. Reporta: URL, status, tiempo de deploy

Instalar skills de terceros

Puedes instalar skills creados por la comunidad con npx:

# Instalar skills de Supabase (queries, migraciones, RLS)
npx skills add supabase/agent-skills

# Instalar skills de seguridad (Trail of Bits)
npx skills add trail-of-bits/security-skills

# Instalar skills de documentación
npx skills add anthropic/docs-skills

Los skills de terceros se guardan en .claude/skills/ y funcionan igual que los tuyos. Revisa el contenido antes de usarlos para entender qué hacen y verificar que no contienen instrucciones maliciosas.

Dónde encontrar skills:

• GitHub: busca repositorios con tag "claude-code-skills"
• Anthropic docs: skills oficiales recomendados
• Comunidades: Discord de Claude Code, Reddit r/ClaudeAI

Gestión de tu librería de skills

Cuándo tienes 10+ skills, la organización importa. Estas prácticas mantienen tu librería manejable:

Naming consistente:

.claude/skills/
├── review.md          # Code review
├── test.md            # Generar tests
├── commit.md          # Smart commit
├── docs.md            # Documentación
├── security.md        # Auditoría seguridad
├── deploy.md          # Deploy
├── migrate.md         # Migración deps
└── simplify.md        # Simplificar código

Prefijos para categorías (si tienes muchos):

.claude/skills/
├── code-review.md
├── code-simplify.md
├── test-unit.md
├── test-integration.md
├── deploy-staging.md
├── deploy-production.md
├── docs-endpoint.md
└── docs-readme.md

Mantenimiento periódico:

• Revisa tus skills cada mes. Elimina los que no uses.
• Actualiza instrucciones cuando cambias de stack o convenciones.
• Si un skill da resultados inconsistentes, ajusta las reglas y el formato de salida.
• Versiona cambios significativos en commits dedicados.

Compartir skills con tu equipo

Los skills del proyecto (.claude/skills/) se suben a git. Todo el equipo los usa automáticamente.

Workflow recomendado:

1. Creas un skill nuevo en una feature branch
2. Lo pruebas en tu sesión de Claude Code
3. Ajustas instrucciones según los resultados
4. Abres PR con el skill para review del equipo
5. Se mergea y todo el equipo lo tiene disponible

Convenciones de equipo para skills:

• Documenta cada skill con un comentario al inicio explicando cuándo usarlo
• Usa el mismo formato de salida en skills similares (consistencia entre /review y /security, por ejemplo)
• Incluye ejemplos de invocación en un README dentro de .claude/skills/
• Designa un owner por skill para mantenerlo actualizado

Skills personales vs compartidos:

# Personal (NO en git): ~/.claude/skills/
# Tus preferencias de formato, atajos personales,
# skills experimentales que aún no están listos

# Compartido (en git): .claude/skills/
# Skills validados por el equipo, con formato consistente,
# alineados con las convenciones del proyecto

Buenas prácticas

• Un skill, una tarea: No crees un skill que haga review + tests + docs. Crea tres skills separados. Son más reutilizables y más fáciles de mantener.
• Instrucciones precisas: "Revisa el código" es vago. "Busca bugs de null pointer, SQL injection y N+1 queries" es preciso. La precisión del skill determina la calidad del resultado.
• Formato de salida siempre: Define cómo quieres el output. Consistencia es clave para poder comparar resultados entre ejecuciones.
• Incluye reglas negativas: "No reportes opiniones de estilo" es tan importante como "Busca bugs". Las reglas negativas evitan ruido en el output.
• Comparte via git: Los skills del proyecto (.claude/skills/) se suben a git. Todo el equipo los usa con las mismas reglas.
• Itera: Tu primer /review no será perfecto. Ajusta las instrucciones según los resultados que obtengas. Cada ejecución es feedback para mejorar el skill.
• Limita el scope: Un skill que intenta hacer demasiado da resultados mediocres en todo. Mejor 5 skills excelentes que 1 skill mediocre que "hace de todo".

Preguntas frecuentes

Cuál es la diferencia entre un skill y una instrucción en CLAUDE.md?

CLAUDE.md se carga siempre al inicio de cada sesión (consume contexto permanente). Un skill se carga solo cuando lo invocas (consume contexto solo cuando lo usas). Pon en CLAUDE.md las reglas que aplican siempre. Pon en skills las tareas que ejecutas a demanda.

Puedo encadenar skills?

No directamente con sintaxis de pipe. Pero puedes pedirle a Claude Code que ejecute varios: "/review y luego /test para los archivos que cambié". O crear un skill compuesto que internamente pida ejecutar otros pasos.

Los skills funcionan con subagents?

Sí. Un skill puede incluir instrucciones que implícitamente activan subagents. Por ejemplo, un skill que dice "analiza seguridad, rendimiento y calidad en paralelo" hará que Claude Code lance subagents internamente.

Qué pasa si tengo un skill global y uno de proyecto con el mismo nombre?

El skill de proyecto tiene prioridad sobre el global. Esto permite que un equipo tenga su propia versión de /review que sobreescriba tu /review personal cuando trabajas en ese proyecto.

Puedo desactivar un skill temporalmente?

Renombra el archivo añadiendo un prefijo (ej: _review.md o review.md.disabled). Claude Code no lo reconocerá como skill activo pero lo puedes reactivar renombrándolo de vuelta.

Siguiente paso

Crea tus primeros 3 skills: /review, /test y /commit. Son los que más impacto tienen en productividad diaria. Después, combínalos con hooks en settings.json para que se ejecuten automáticamente (ej: /review antes de cada commit).

Si quieres ir un paso más allá, explora los subagents para crear skills que lancen tareas en paralelo, y la memoria de Claude Code para que tus skills interactúen con el contexto persistente del proyecto.