# Cómo crear Skills para Claude Code: arquitectura, mejores prácticas y pruebas
> Guía técnica completa para crear Skills personalizados en Claude Code: estructura de carpetas y SKILL.md, carga progresiva (progressive disclosure), diferencias con hooks y desarrollo guiado por evaluación.
## 1. Qué es una Skill y por qué constituye un artefacto de software
Una **Skill (habilidad)** en Claude Code es un paquete modular estandarizado que agrupa flujos de trabajo (workflows), reglas de dominio, guías de referencia y scripts ejecutables que un agente de IA carga dinámicamente para resolver una categoría concreta de tareas. En lugar de que el desarrollador copie y pegue manualmente instrucciones extensas en cada sesión, el agente reconoce la intención del usuario y activa la Skill adecuada de forma autónoma.
La diferencia clave entre una Skill y el código tradicional radica en su mecanismo de activación: el modelo de lenguaje decide si invoca una Skill mediante el emparejamiento semántico entre la descripción de la habilidad y la solicitud del usuario. Esta decisión es **probabilística**: al no existir un compilador que garantice la selección, la precisión en la redacción de los metadatos determina directamente si la habilidad se ejecutará cuando se necesite.
```mermaid
flowchart TD
subgraph Invocation ["Activación de la habilidad"]
Prompt["Solicitud del usuario"] --> Matcher{"Emparejamiento semántico (LLM)"}
Meta["Frontmatter name + description
(~100 tokens al iniciar)"] --> Matcher
Matcher -->|Coincidencia de intención| Load["Carga de SKILL.md en contexto"]
Matcher -->|Sin coincidencia| Normal["Ejecución estándar sin Skill"]
end
subgraph Execution ["Flujo de ejecución"]
Load --> Steps["Ejecución de instrucciones paso a paso"]
Steps --> Scripts["Ejecución de scripts (bash/python)"]
Steps --> Refs["Lectura de archivos de referencia"]
Scripts & Refs --> Result["Artefacto final / Código"]
end
```
### Por qué una Skill es un artefacto de software y no mero texto
1. **Control de versiones y modularidad:** La habilidad se compone de archivos del repositorio, se versiona mediante Git y evoluciona con las mismas prácticas del código fuente.
2. **Separación de interfaz e implementación:** El campo `description` en el frontmatter actúa como interfaz pública, mientras que el cuerpo de `SKILL.md` y los scripts son la implementación interna.
3. **Composabilidad:** Una Skill puede invocar herramientas externas mediante MCP, ejecutar utilidades de terminal y delegar subtareas a otras habilidades o subagentes.
4. **Vulnerabilidad a regresiones:** Modificar incorrectamente una descripción puede provocar fallos silenciosos (la habilidad deja de activarse) o desviaciones en las respuestas del agente.
> [!NOTE]
> La especificación **Agent Skills**, promovida por Anthropic, es un estándar abierto. Las habilidades desarrolladas bajo este formato son compatibles tanto con Claude Code como con otros entornos avanzados de agentes de IA.
---
## 2. Estructura de archivos y directorios: SKILL.md, scripts y recursos
Una Skill se organiza como un directorio estructurado en el sistema de archivos, cuyo núcleo obligatorio es el archivo `SKILL.md`. En función de la complejidad del flujo, puede incorporar scripts auxiliares, manuales de estilo y plantillas.
### Ámbitos de almacenamiento en Claude Code
- **Skills globales personales (`~/.claude/skills/`):** Disponibles en todos los proyectos de la máquina del desarrollador. Idóneas para utilidades personales, formatos de commits o scripts de análisis.
- **Skills del proyecto (`.claude/skills/`):** Almacenadas en el repositorio del proyecto y versionadas en Git. Compartidas con todo el equipo para asegurar estándares homogéneos.
### Estructura recomendada para una Skill avanzada
```text
.claude/skills/release-notes/
├── SKILL.md # Obligatorio: metadatos e instrucciones paso a paso
├── changelog-style.md # Recurso: guía de estilo para el changelog
└── scripts/
└── gather-prs.py # Script ejecutable: extracción de PRs fusionados
```
Una Skill mínima puede consistir únicamente en un archivo `SKILL.md`. Los flujos de trabajo más complejos empaquetan scripts y guías de referencia dentro de su carpeta, manteniendo las instrucciones principales breves y concisas.
---
## 3. Normas de formato para Frontmatter: name y description
Todo archivo `SKILL.md` comienza obligatoriamente con un bloque de metadatos YAML Frontmatter. Es la única sección que Claude procesa al iniciar la sesión para catalogar las capacidades disponibles.
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release or updating the changelog.
---
```
### Restricciones formales para el nombre (name)
- Longitud máxima de **64 caracteres**.
- Solo letras minúsculas en inglés, dígitos y guiones (`[a-z0-9-]`).
- Prohibido el uso de etiquetas XML/HTML y espacios.
- Palabras reservadas prohibidas: `claude` y `anthropic`.
### Restricciones formales para la descripción (description)
- Campo obligatorio no vacío.
- Longitud máxima de **1024 caracteres**.
- Prohibido el uso de etiquetas XML.
- Debe detallar con claridad la función de la habilidad y los disparadores de activación.
| Campo | Ejemplo válido | Ejemplo no válido | Causa del rechazo |
| :--- | :--- | :--- | :--- |
| `name` | `db-migrate-helper` | `Claude-DB-Helper!` | Mayúsculas, caracteres especiales y palabra reservada `claude` |
| `name` | `deploy-staging` | `deploy_` | Guiones bajos y paréntesis angulares no permitidos |
| `description` | `Generates API documentation from Express routes. Use when updating docs.` | `A tool for API` | Descripción excesivamente vaga sin condiciones de activación |
> [!WARNING]
> Si una Skill debe ejecutarse exclusivamente por petición explícita y nunca por decisión autónoma del modelo, desactive la invocación automática en su frontmatter para transformarla en un comando slash determinista.
---
## 4. Carga progresiva (Progressive Disclosure) y gestión de contexto
Las Skills no saturan la ventana de contexto al iniciar la sesión. Claude Code implementa el principio de **carga progresiva (Progressive Disclosure)** estructurado en tres niveles.
```mermaid
flowchart LR
L1["Nivel 1: Metadatos
(~100 tokens, siempre cargado)"] -->|Coincidencia| L2["Nivel 2: Cuerpo SKILL.md
(~1-3k tokens, bajo demanda)"]
L2 -->|Referencia en pasos| L3["Nivel 3: Recursos y scripts
(0 tokens hasta su lectura o ejecución)"]
```
### Los tres niveles de carga
1. **Nivel 1 — Metadatos (Metadata):** El nombre y la descripción de cada Skill se cargan en el contexto del sistema (~100 tokens por habilidad). Esto permite conectar decenas de habilidades sin agotar la memoria disponible.
2. **Nivel 2 — Cuerpo del archivo (Body):** Cuando el modelo determina que una solicitud coincide con la descripción, lee `SKILL.md`. Se recomienda que el cuerpo no supere las 500 líneas para no desplazar la conversación en curso.
3. **Nivel 3 — Recursos y scripts enlazados (Resources):** Los archivos de referencia solo se leen cuando un paso específico los solicita. Los scripts se ejecutan en la terminal sin volcar su código en el contexto, devolviendo únicamente la salida del proceso.
---
## 5. Redacción del description: creación de disparadores fiables
Dado que el campo `description` constituye el disparador principal de selección probabilística, su redacción exige la máxima precisión.
### Reglas para redactar descripciones de alta eficacia
- **Tercera persona exclusiva:** Redacte siempre en tercera persona (`Drafts`, `Audits`, `Generates`). El modelo interpreta la descripción como la firma de una herramienta; pronombres en primera o segunda persona reducen la precisión.
- **La fórmula «Qué + Cuándo»:** Indique claramente qué operación técnica ejecuta la habilidad y en qué momentos o circunstancias debe invocarse.
- **Términos técnicos reales:** Incluya palabras clave, nombres de archivos y comandos habituales que el desarrollador utilizará en sus peticiones.
:::tabs
@tab Descripción ambigua
```yaml
---
name: release-notes
description: Handles project releases and writes updates.
---
```
*Problema: Carece de disparadores concretos. El modelo no sabe qué datos procesar ni cuándo invocarla.*
@tab Descripción precisa
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release, updating the changelog, or summarizing what changed in a version.
---
```
*Ventaja: Especifica las entidades de entrada (git tags, pull requests) y los contextos de activación (cutting a release, updating changelog).*
:::
---
## 6. Anatomía de una Skill de producción: el flujo release-notes
Analicemos la estructura de la habilidad de automatización de notas de versión `release-notes`.
### Componentes clave del flujo
- **Parámetros de entrada:** Argumentos de usuario (rango de etiquetas `v1.2.0..v1.3.0`), manual de estilo `changelog-style.md`, script de extracción `gather-prs.py`.
- **Secuencia paso a paso en `SKILL.md`:**
1. Identificar el rango de etiquetas en Git.
2. Ejecutar `python scripts/gather-prs.py` para obtener los PR fusionados.
3. Agrupar cambios por categoría (Features, Fixes, Performance, Breaking Changes).
4. Redactar el borrador siguiendo las pautas de `changelog-style.md`.
5. Incorporar las notas en `CHANGELOG.md` y presentar un resumen.
- **Artefactos generados:** Archivo `CHANGELOG.md` actualizado y resumen conciso en la consola.
### Pautas para el cuerpo de la Skill
1. **Evite explicar conceptos básicos:** Asuma que Claude es un ingeniero competente; concéntrese en las singularidades del proyecto y las restricciones obligatorias.
2. **Profundidad de referencias limitada a un nivel:** Los archivos de apoyo no deben enlazar sucesivamente con otros documentos. Todos los recursos deben depender directamente de `SKILL.md`.
3. **Rutas multiplataforma:** Utilice siempre barras inclinadas (`/`) en las rutas de archivos.
---
## 7. El mapa de personalizaciones: Skills, CLAUDE.md, Comandos, MCP, Hooks y Plugins
Claude Code ofrece siete mecanismos de personalización. Escoger el mecanismo incorrecto es la causa principal de comportamientos erráticos.
| Mecanismo | Autoridad de activación | Fuerza de ejecución | Escenario idóneo |
| :--- | :--- | :--- | :--- |
| **CLAUDE.md (Memory)** | Entorno de ejecución (siempre cargado) | Consultiva | Convenciones generales del proyecto, comandos de build |
| **Skill** | Modelo (semántico) o usuario | Consultiva | Flujos de trabajo de dominio, procedimientos con scripts |
| **Comando Slash** | Usuario (`/comando`) | Consultiva | Plantillas interactivas ejecutadas a demanda |
| **Subagente** | Modelo o usuario | Aislada | Delegación de tareas pesadas en ventanas de contexto separadas |
| **Herramienta MCP** | Modelo (llamada a herramienta) | Ejecutiva | Conexión con servicios externos, bases de datos y APIs |
| **Hook** | Entorno de ejecución (determinista) | **Bloqueante** | Políticas estrictas de seguridad y linters antes de commits |
| **Plugin** | Usuario (instalación) | Integral | Distribución de paquetes con habilidades, servidores MCP y hooks |
> [!IMPORTANT]
> Solo los mecanismos gestionados directamente por el entorno de ejecución (como los **Hooks**) ofrecen garantías deterministas de ejecución y capacidad de bloqueo. Las instrucciones de una Skill son de carácter consultivo y el modelo las aplica de forma probabilística.
---
## 8. Skills frente a Hooks: asesoramiento vs. garantías deterministas
Un error habitual es utilizar Skills para aplicar políticas de seguridad o formateos obligatorios. Una Skill orienta al modelo, pero no puede bloquear una acción. Para garantías absolutas, configure Hooks.
### Eventos clave del ciclo de vida
- **SessionStart (Hook):** Se ejecuta al iniciar la sesión para verificar ramas de Git o variables de entorno.
- **Razonamiento del modelo (Carga de Skill):** El modelo evalúa la solicitud y lee `SKILL.md` bajo demanda.
- **PreToolUse (Hook, bloqueante):** Se activa antes de cualquier acción. Puede auditar comandos y cancelar su ejecución (código de salida 2) si incumplen normativas de seguridad.
- **PostToolUse (Hook):** Se ejecuta tras finalizar una acción (por ejemplo, formatear con Prettier tras guardar un archivo).
- **Stop (Hook):** Se dispara cuando el modelo concluye su respuesta.
```text
Regla de decisión arquitectónica:
- Requiere criterio de ingeniería y adaptación contextual ──► Desarrolle una SKILL
- Debe ejecutarse de manera obligatoria y sin excepciones ──► Configure un HOOK
```
---
## 9. Desarrollo guiado por evaluación (Evaluation-Driven Development)
El diseño de Skills fiables requiere un ciclo iterativo de validación práctica antes de dar por cerrado el texto de las instrucciones.
### Las cuatro etapas de diseño
1. **Definición de la línea base (Baseline):** Ejecute solicitudes habituales en Claude Code sin la Skill y documente los errores u omisiones.
2. **Diseño de la suite de pruebas (Eval Suite):** Convierta los fallos identificados en una batería de pruebas con resultados esperados verificables.
3. **Redacción de la versión mínima (MVP):** Redacte en `SKILL.md` únicamente las instrucciones necesarias para superar las pruebas.
4. **Refinamiento progresivo:** Incorpore nuevas reglas solo cuando falle una prueba, evitando sobrecargar el contexto.
### Flujo de trabajo con dos instancias del modelo
- **Instancia editora:** Sesión colaborativa con Claude para estructurar y pulir las instrucciones.
- **Instancia de pruebas:** Sesión limpia en la que se comprueba si la habilidad se activa correctamente ante consultas reales.
---
## 10. Patrones de diseño y antipatrones al crear Skills
La experiencia práctica ha consolidado patrones de diseño recomendados y errores frecuentes que conviene evitar.
### Patrones recomendados
- **Flujos deterministas numerados:** Describa los procesos complejos mediante listas secuenciales ordenadas (`1. ...`, `2. ...`, `3. ...`).
- **Listas de comprobación integradas:** Incluya checklists en Markdown para que el modelo confirme cada etapa durante la ejecución.
- **Ciclos de verificación y corrección:** Instruya al modelo: «Ejecutar pruebas -> corregir incidencias -> repetir hasta obtener cero errores».
- **Planificación previa para operaciones destructivas:** Exija la generación de una tabla con los cambios previstos antes de modificar archivos en lote.
### Antipatrones que deben evitarse
- **Parálisis por elección:** Describir múltiples bibliotecas alternativas sin establecer una opción predeterminada clara.
- **Dependencias no declaradas:** Emplear comandos o paquetes sin verificar previamente su disponibilidad en el sistema.
- **Barras invertidas en rutas:** Usar sintaxis de Windows (`\`), lo que rompe la compatibilidad en Linux y macOS.
- **Constantes sin justificación:** Emplear valores numéricos o tiempos de espera sin explicar su motivo técnico.
---
## 11. Seguridad y auditoría de Skills de terceros antes de instalarlas
Una Skill ajena constituye código ejecutable en su entorno. Dado que Claude Code dispone de acceso a la terminal, al sistema de archivos y a la red, las Skills no verificadas plantean riesgos de seguridad significativos.
### Lista de comprobación de seguridad antes de la instalación
- [ ] **Auditoría de `SKILL.md`:** Compruebe que no incluya inyecciones de prompts ni intentos de acceder a archivos `.env` o credenciales.
- [ ] **Revisión de scripts en `scripts/`:** Inspeccione los archivos Python y bash para asegurarse de que no transmitan datos a servidores externos no autorizados.
- [ ] **Validación de URLs externas:** Examine todos los enlaces que descarguen binarios o configuraciones remotas.
- [ ] **Pruebas en entorno aislado:** Ejecute inicialmente la habilidad en un repositorio de pruebas sin acceso a claves de producción.