Tu librería de Claude Skills: de prompts sueltos a sistema

TL;DR: Una Skill aislada ahorra tokens en una tarea concreta. Una librería de Claude Skills bien organizada (con convenciones de nombrado, estructura predecible y versionado) deja de ser una colección de prompts y se convierte en un sistema reutilizable entre proyectos. Esta guía explica cómo estructurarla, qué meter en cada SKILL.md y cómo versionarla sin que se pudra.

El problema: 30 skills sueltas no son un sistema

Llevo meses creando Skills para Claude Code: una para revisar PRs, otra para escribir migraciones SQL, otra para generar tests con pytest. Funcionaban bien individualmente. El problema apareció al tener veintitantas: nombres inconsistentes, descripciones que no activaban el matching, archivos con la mitad del contexto duplicado entre skills.

El síntoma más claro: abría una tarea, sabía que tenía una skill para eso, y aún así reescribía el prompt porque era más rápido que buscar cuál de mis archivos era el correcto. Cuando reusar cuesta más que repetir, la librería ha fallado.

El cambio no está en escribir skills mejores. Está en tratarlas como código compartido: con estructura, convenciones y mantenimiento.

¿Qué es una Claude Skill?

Una Claude Skill es un archivo Markdown (SKILL.md) con frontmatter YAML que Claude Code carga bajo demanda cuando su descripción coincide con la tarea actual. A diferencia de un prompt pegado en chat, vive en disco, se versiona en git y se activa por matching semántico.

El estándar abierto define dos campos obligatorios en el frontmatter: name y description. La descripción es lo que decide si la skill se activa o no, así que es la pieza más importante del archivo.

De colección a librería: las 3 piezas que faltan

Una colección de skills se vuelve librería cuando añades tres cosas:

• Convención de nombrado: nombres predecibles que dejan claro el dominio y la acción.
• Estructura de carpetas estable: dónde vive cada skill según su alcance (global, equipo, proyecto).
• Versionado y mantenimiento: git, changelog y revisión periódica de descripciones que ya no activan.

Convención de nombrado: dominio + acción

El patrón que me funciona en producción es dominio-accion, en kebab-case, sin verbos genéricos como helper o tool. Ejemplos:

• sql-migrations, no db-helper
• pr-review-backend, no code-review
• fastapi-endpoint-scaffold, no api-builder

El nombre debe responder a qué hace y en qué dominio. Si no puedes nombrarla así, probablemente es una skill demasiado amplia y conviene partirla.

Estructura de archivos: tres niveles de alcance

Claude Code lee skills desde varias rutas. Yo las organizo por alcance, de menos a más específico:

Nivel	Ruta típica	Qué meto aquí
Global (usuario)	~/.claude/skills/	Skills de proceso (review, debug, escribir commits)
Equipo	repo compartido + symlink	Convenciones del equipo (estilo de PR, plantillas)
Proyecto	./.claude/skills/	Específicas del repo (modelos de datos, endpoints)

Una skill global como commit-conventional no debe duplicarse en cada proyecto. Una skill como vitaly-rag-pipeline no tiene sentido fuera del repo donde vive.

Anatomía de un SKILL.md mantenible

Cada skill vive en su propia carpeta con SKILL.md dentro. Mi plantilla:

---
name: sql-migrations
description: Genera migraciones SQL idempotentes para PostgreSQL siguiendo el patrón de cambios reversibles. Activa cuando el usuario pide alterar tablas, añadir columnas o crear índices.
version: 1.2.0
---

# SQL Migrations

## Cuándo usar esta skill
Cuando el usuario pide modificar el esquema de PostgreSQL en proyectos con Alembic.

## Reglas
- Toda migración debe tener `upgrade()` y `downgrade()` simétricos.
- Índices siempre con `CONCURRENTLY` en producción.
- Nombres de constraints explícitos, nunca autogenerados.

## Plantilla
[ejemplo de migración aquí]

Lo crítico: la descripción en el frontmatter. Si dice solo "Helper para SQL", Claude no la activará cuando toque. Si dice cuándo activar y qué hace, sí.

Versionado: git y un CHANGELOG por skill

Mi librería global vive en un repo privado con esta estructura:

~/.claude/skills/
├── README.md           # índice y convenciones
├── CHANGELOG.md        # cambios globales
├── sql-migrations/
│   ├── SKILL.md
│   └── examples/
├── pr-review-backend/
│   └── SKILL.md
└── commit-conventional/
    └── SKILL.md

El campo version en el frontmatter no es decorativo: cuando una skill cambia su comportamiento (no solo correcciones de typo), bumpeas. Si la activación deja de funcionar bien tras un cambio, sabes en qué versión empezó.

Para gestionar este flujo, herramientas como la integración de GitHub CLI con skills de Claude Code ayudan a mantener varias librerías sincronizadas entre máquinas.

Implementación paso a paso

1. Inventario: lista los 5 prompts que más repites en una semana. Esos son tus primeros candidatos a skill.
2. Crea la carpeta global: mkdir -p ~/.claude/skills e inicializa git.
3. Plantilla base: guarda un SKILL.template.md con frontmatter y secciones estándar (Cuándo usar, Reglas, Plantilla).
4. Migra una skill: elige la más usada, extrae el prompt completo y reformúlalo con descripción accionable.
5. Prueba el matching: abre una sesión nueva, lanza una tarea que debería activarla y verifica que Claude la carga. Si no, reescribe la description.
6. Itera: cada vez que repitas un prompt manualmente, anótalo. A las dos repeticiones, conviértelo en skill.

En Producción

Cuando una librería de skills empieza a tener tamaño real, aparecen consideraciones que no salen en tutoriales:

• Coste de carga: Claude Code lee el frontmatter de todas las skills disponibles para decidir matching. Si tienes 200 skills mal descritas, el modelo gasta tokens evaluando cuál activar. Mantén la librería pequeña y curada antes que enorme.
• Conflictos de activación: dos skills con descripciones solapadas se pelean. Si tienes sql-migrations y db-schema-changes, una de las dos sobra. Prefiere fusionar a duplicar.
• Drift entre máquinas: si trabajas en varias (laptop, VPS, CI), la librería debe estar en git con un script de sincronización. Sin eso, la versión de tu portátil y la del servidor divergen en una semana.
• Revisión periódica: cada trimestre reviso qué skills no se han activado. Si una lleva tres meses sin uso, o la borro o reescribo su descripción.
• Coste real: en mi experiencia, una skill bien diseñada ahorra entre 2.000 y 5.000 tokens por sesión recurrente. Con uso diario, el ahorro mensual ronda el 15-20% del consumo total. No es la diferencia entre 10€ y 50€ al mes, pero sí entre quedarse sin cuota un viernes y no.

Para entender por qué el contexto bien gestionado importa tanto, revisa cómo memoria, MCPs y mapa de repo reducen consumo de tokens en Claude Code.

Errores comunes y depuración

• Error: la skill no se activa nunca. Causa: descripción genérica o demasiado corta. Solución: reescribe la description incluyendo cuándo activarla con verbos concretos ("genera", "revisa", "convierte").
• Error: se activan dos skills a la vez y se pisan. Causa: descripciones que cubren el mismo dominio sin distinción de acción. Solución: fusiona ambas o limita una con "solo cuando X".
• Error: la skill funcionaba y ahora no. Causa: cambio reciente en la descripción o en el cuerpo. Solución: git log SKILL.md, compara versiones y revierte la última edición que rompe el matching.
• Error: la librería crece sin control. Causa: convertir cada prompt en skill sin filtro. Solución: regla de las dos repeticiones (no creas skill hasta haber repetido un prompt al menos dos veces).

Aplicación práctica: librería mínima viable

Si empiezas hoy, esta sería una librería global de arranque razonable para un backend dev:

• commit-conventional: genera mensajes en formato Conventional Commits desde el diff.
• pr-review-backend: revisa PRs con foco en seguridad, manejo de errores y tests.
• test-pytest-fixture: scaffold de tests con fixtures reutilizables.
• debug-stack-trace: parsea un stack trace, identifica el origen y propone fix.
• refactor-extract-function: extrae lógica repetida siguiendo el principio de separación de responsabilidades.

Cinco skills cubren el 70% del trabajo diario. A partir de ahí, añades específicas por proyecto.

Preguntas frecuentes

¿Cuántas skills es razonable tener en la librería global?

Entre 10 y 25 para uso personal intensivo. Más de 50 suele indicar que estás creando skills para tareas únicas que no se repiten, o que hay solapamiento. La calidad del matching cae cuando hay muchas descripciones similares compitiendo.

¿Skills o subagentes para tareas largas?

Skills cuando el conocimiento es estable y reutilizable (convenciones, plantillas, reglas). Subagentes cuando necesitas dividir una tarea concreta en pasos con contexto aislado. No son alternativas: una skill puede orquestar un subagente.

¿Cómo comparto la librería con mi equipo sin imponerla?

Repo separado con las skills del equipo, montado vía symlink en ~/.claude/skills/team/. Cada miembro decide qué activar. Las skills muy opinadas (estilo de código personal) se quedan en la librería individual; las del equipo solo cubren convenciones acordadas.

Cierre

Pasar de prompts sueltos a librería de Claude Skills no es un cambio de herramienta, es un cambio de cómo tratas el contexto que reutilizas a diario. La diferencia real está en las convenciones de nombrado, en una estructura de carpetas que respetas, y en versionar como versionas código. Con eso, la librería deja de pudrirse a los dos meses y empieza a componer valor.

Lo siguiente que merece la pena explorar: cómo combinar skills con subagentes para tareas multi-paso sin reventar el contexto. ¿Tienes ya tu librería montada o sigues con prompts sueltos? Cuéntamelo en Twitter @sergiomarquezp_.