# Guía Completa: Crea tus propios Claude Skills

> Todo lo que necesitas para crear, organizar y distribuir Skills de Claude Code.

---

## Qué es un Skill

Un Skill es una carpeta con instrucciones que Claude carga automáticamente cuando detecta que son relevantes para la tarea actual. Funciona en Claude Code, la API de Anthropic, claude.ai y el Agent SDK.

En su forma más simple, un Skill es un archivo `SKILL.md` con metadata YAML y un bloque de instrucciones en lenguaje natural.

---

## Template base de SKILL.md

```yaml
---
name: nombre-del-skill          # identificador único, en kebab-case
description: >
  Descripción en tercera persona de qué hace este skill.
  Claude usa esta descripción para decidir si activarlo.
version: 1.0.0                  # versionado semántico
---

# Título del Skill

## Cuándo activar
- Condición 1 para activar este skill
- Condición 2

## Instrucciones
1. Paso uno
2. Paso dos
3. Paso tres

## Formato de salida
- Describe cómo debe verse la respuesta
```

---

## Estructura de carpeta

```
mi-skill/
├── SKILL.md          # obligatorio — instrucciones principales
├── REFERENCE.md      # opcional — contexto extra, guías de estilo, specs
└── scripts/          # opcional — scripts auxiliares
    ├── lint.sh
    └── validate.py
```

- **SKILL.md**: el archivo principal. Claude lo lee cuando decide que el skill es relevante.
- **REFERENCE.md**: contexto adicional que Claude carga solo si necesita más información.
- **scripts/**: archivos ejecutables que el skill puede invocar durante su ejecución.

---

## Dónde colocar tus Skills

### Personal (global)
```
~/.claude/skills/mi-skill/SKILL.md
```
Disponible en todos tus proyectos. Ideal para skills personales.

### Por proyecto
```
.claude/skills/mi-skill/SKILL.md
```
Solo aplica a este repositorio. Se comparte con el equipo vía git.

---

## Los 3 niveles de carga progresiva

Claude no carga todo de golpe. Usa carga progresiva:

1. **Metadata** — Lee solo `name` y `description` del YAML frontmatter. Decide si el skill es relevante.
2. **Instrucciones** — Si es relevante, carga el cuerpo completo del SKILL.md.
3. **Recursos** — Solo si necesita más contexto, lee REFERENCE.md y archivos auxiliares.

Esto mantiene el contexto limpio y eficiente.

---

## Ejemplos de Skills

### Code Reviewer

```yaml
---
name: code-reviewer
description: Revisa código buscando bugs, seguridad y mejoras de rendimiento
version: 1.0.0
---

# Code Reviewer

Cuando el usuario pida una revisión de código:

1. Lee los archivos indicados o los cambios staged en git
2. Analiza en este orden:
   - Bugs potenciales y errores lógicos
   - Vulnerabilidades de seguridad (OWASP top 10)
   - Problemas de rendimiento
   - Legibilidad y mantenibilidad
3. Presenta hallazgos agrupados por severidad:
   - 🔴 Crítico — debe corregirse antes de merge
   - 🟡 Advertencia — recomendado corregir
   - 🟢 Sugerencia — mejora opcional
4. Para cada hallazgo incluye:
   - Archivo y línea
   - Descripción del problema
   - Código sugerido de corrección
```

### API Documenter

```yaml
---
name: api-documenter
description: Genera documentación OpenAPI/Swagger a partir de rutas de API existentes
version: 1.0.0
---

# API Documenter

Cuando el usuario pida documentar una API:

1. Escanea los archivos de rutas en el proyecto
2. Para cada endpoint, extrae:
   - Método HTTP y path
   - Parámetros (query, body, path)
   - Respuestas posibles con códigos de estado
3. Genera un archivo OpenAPI 3.0 en YAML
4. Incluye descripciones claras y ejemplos de request/response
```

### Testing Skill

```yaml
---
name: test-generator
description: Genera tests unitarios siguiendo las convenciones del proyecto
version: 1.0.0
---

# Test Generator

Cuando el usuario pida crear tests:

1. Identifica el framework de testing del proyecto (Jest, Vitest, pytest, etc.)
2. Lee el archivo a testear y sus dependencias
3. Genera tests que cubran:
   - Happy path
   - Edge cases
   - Manejo de errores
4. Sigue las convenciones de naming del proyecto
5. Usa mocks solo cuando sea necesario
```

---

## Integración con la API

Para usar skills vía la API de Anthropic, pasa el contenido del skill en la request:

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: interleaved-thinking-2025-05-14,code-execution-2025-05-22" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "system": "Contenido de tu SKILL.md aquí",
    "messages": [
      {"role": "user", "content": "Revisa este código..."}
    ]
  }'
```

---

## Buenas prácticas

- **Mantén SKILL.md por debajo de 500 líneas** — si crece demasiado, divide en skills más pequeños
- **Escribe descripciones en tercera persona** — "Genera tests unitarios..." no "Genero tests..."
- **Usa nombres descriptivos en kebab-case** — `code-reviewer`, `api-documenter`
- **Incluye condiciones de activación** — ayuda a Claude a decidir cuándo usar el skill
- **Prueba en diferentes modelos** — Opus, Sonnet y Haiku pueden interpretar instrucciones diferente
- **Itera** — empieza simple, prueba, y mejora basándote en resultados reales
- **Pide confirmación** — para acciones destructivas, incluye un paso de confirmación con el usuario

---

## Qué NO hacer

- ❌ Nombres vagos como `helper`, `utils` o `misc`
- ❌ Rutas hardcodeadas de Windows (`C:\Users\...`) — usa rutas relativas
- ❌ Un skill que hace todo — divide responsabilidades
- ❌ Referencias circulares entre skills
- ❌ Archivos de referencia gigantes — solo incluye lo necesario
- ❌ Instrucciones ambiguas como "haz lo mejor posible"
- ❌ Saltarte el frontmatter YAML — Claude lo necesita para la carga progresiva

---

## Troubleshooting

### El skill no se activa
- Verifica que el archivo se llame exactamente `SKILL.md` (mayúsculas)
- Revisa que el frontmatter YAML sea válido (sin tabs, solo espacios)
- Asegúrate de que la descripción sea clara y relevante para la tarea

### Conflictos de nombre
- Cada skill debe tener un `name` único en su scope (global o proyecto)
- Si tienes un skill global y uno de proyecto con el mismo nombre, el de proyecto tiene prioridad

### El skill carga contenido incorrecto
- Revisa que REFERENCE.md no tenga información contradictoria
- Verifica que las instrucciones sean específicas y no ambiguas
- Prueba con un prompt simple para aislar el problema

---

## Links oficiales

- [Skills Overview](https://docs.anthropic.com/en/docs/claude-code/skills)
- [Skills Quickstart](https://docs.anthropic.com/en/docs/claude-code/skills-quickstart)
- [Best Practices](https://docs.anthropic.com/en/docs/claude-code/skills-best-practices)
- [Enterprise Skills](https://docs.anthropic.com/en/docs/claude-code/skills-enterprise)
- [API Skills Guide](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills-api)