- En Claude Code, Skills es uno de los puntos de extensión más usados, y Anthropic comparte know-how práctico acumulado al operar cientos de skills internamente
- Un skill no es solo un archivo Markdown, sino una estructura de carpetas que incluye scripts, assets y datos, en una forma que el agente puede explorar y aprovechar
- Se clasifican en 9 categorías de skills como referencias de librerías, validación de producto, análisis de datos, scaffolding de código y CI/CD, y un buen skill debe encajar claramente en una sola categoría
- Al escribir skills, las claves son consejos prácticos como la sección de Gotchas, el uso del sistema de archivos, la divulgación progresiva (Progressive Disclosure) y el almacenamiento de datos
- Al escalar en una organización, se recomienda una estructura para distribuir skills mediante un marketplace interno de plugins y seguir su efectividad con hooks de medición de uso
Qué son Skills
- Un malentendido común sobre Skills es que “son solo archivos Markdown”, pero en realidad son una estructura de carpetas que incluye scripts, assets, datos y más
- El agente puede explorar esta carpeta, descubrir su contenido y manipularlo
- En Claude Code, Skills ofrece diversas opciones de configuración, y también permite registrar hooks dinámicos (dynamic hooks)
- Los skills más interesantes son los que aprovechan creativamente estas opciones de configuración y la estructura de carpetas
Las 9 categorías de skills
- Al clasificar todos los skills que usan internamente, estos se agrupan en varias categorías que aparecen de forma recurrente
- Un buen skill encaja limpiamente en una sola categoría, mientras que un skill confuso abarca varias categorías
-
1. Library & API Reference
- Skills que explican cómo usar correctamente librerías, CLI y SDK
- No solo cubren librerías internas, sino también librerías comunes con las que Claude Code suele equivocarse
- A menudo incluyen carpetas con snippets de código de referencia y una lista de advertencias (gotchas)
- Ejemplos: billing-lib (casos límite de una librería interna de pagos), internal-platform-cli (todos los subcomandos y ejemplos de uso de un wrapper CLI interno), frontend-design (mejoras para aplicar el sistema de diseño)
-
2. Product Verification
- Skills que describen cómo probar y validar que el código funciona correctamente
- A menudo se usan en combinación con herramientas externas como Playwright y tmux
- Son muy útiles para garantizar la precisión de la salida de Claude, y vale la pena que un ingeniero invierta incluso una semana en hacer excelente un skill de validación
- Se recomienda hacer que Claude grabe en video su salida o forzar assertions programáticos sobre el estado en cada paso
- Ejemplos: signup-flow-driver (realiza registro → verificación por email → onboarding en un navegador headless), checkout-verifier (ejecuta la UI de pago con tarjetas de prueba de Stripe y luego valida el estado de la factura), tmux-cli-driver (para probar CLIs interactivos que requieren TTY)
-
3. Data Fetching & Analysis
- Skills que conectan con stacks de datos y monitoreo
- Incluyen librerías para traer datos con credenciales, IDs de dashboards específicos y guías de flujos de trabajo comunes
- Ejemplos: funnel-query (tablas con los eventos necesarios y el canonical user_id para el funnel de registro → activación → pago), cohort-compare (compara retención/tasa de conversión de dos cohortes y marca significancia estadística), grafana (UIDs de data sources, nombres de clústeres y tabla de búsqueda problema → dashboard)
-
4. Business Process & Team Automation
- Skills que automatizan flujos de trabajo repetitivos con un solo comando
- Suelen ser instrucciones relativamente simples, pero pueden tener dependencias complejas de otros skills o MCP
- Guardar resultados de ejecuciones anteriores en un archivo de log ayuda al modelo a mantener consistencia y reflejar ejecuciones previas
- Ejemplos: standup-post (standup con formato a partir del ticket tracker, actividad en GitHub y Slack), create-ticket (flujo de trabajo con esquema forzado y pasos posteriores a la creación), weekly-recap (redacta un post resumen con PRs mergeados + tickets cerrados + despliegues)
-
5. Code Scaffolding & Templates
- Skills que generan boilerplate de frameworks para funciones específicas dentro del codebase
- Pueden combinarse con scripts componibles, y son especialmente útiles cuando hay requisitos en lenguaje natural que no se pueden cubrir por completo solo con código
- Ejemplos: new-framework-workflow (scaffolding de un nuevo servicio/workflow/handler con anotaciones), new-migration (plantilla de archivo de migración y advertencias), create-app (nueva app interna con autenticación, logging y configuración de despliegue ya conectados)
-
6. Code Quality & Review
- Skills que hacen cumplir la calidad de código en la organización y ayudan con code review
- Pueden incluir scripts o herramientas deterministas para máxima robustez
- También pueden ejecutarse automáticamente como parte de hooks o de una GitHub Action
- Ejemplos: adversarial-review (un subagente con una nueva perspectiva critica → corrige → repite hasta que las observaciones bajan a nivel de nitpick), code-style (hace cumplir estilos de código que Claude no maneja bien por defecto), testing-practices (cómo escribir tests y qué probar)
-
7. CI/CD & Deployment
- Skills para traer, hacer push y desplegar código dentro del codebase
- Pueden consultar otros skills para reunir datos
- Ejemplos: babysit-pr (monitorea PR → reintenta CI flaky → resuelve conflictos de merge → activa automerge), deploy-service (build → smoke test → rollout gradual de tráfico → compara tasa de errores → rollback automático si hay regresión), cherry-pick-prod (worktree aislado → cherry-pick → resuelve conflictos → crea PR con plantilla)
-
8. Runbooks
- Skills que reciben síntomas (hilos de Slack, alertas, firmas de error, etc.) y realizan investigaciones con múltiples herramientas para generar un reporte estructurado
- Ejemplos: service-debugging (mapeo de síntoma → herramienta → patrón de query), oncall-runner (trae alertas → revisa causas comunes → da formato a los resultados), log-correlator (reúne logs relacionados de todos los sistemas usando un request ID)
-
9. Infrastructure Operations
- Skills que ejecutan procedimientos cotidianos de mantenimiento y operación, incluyendo guardrails para acciones destructivas
- Ayudan a que los ingenieros sigan buenas prácticas en operaciones críticas
- Ejemplos: resource-orphans (detecta Pods/volúmenes huérfanos → alerta en Slack → período de espera → confirmación del usuario → limpieza en cascada), dependency-management (flujo de aprobación de dependencias de la organización), cost-investigation (buckets y patrones de query para investigar aumentos repentinos en costos de storage/egress)
Consejos para escribir skills
-
No escribas lo obvio
- Claude Code ya sabe bastante sobre el codebase y también tiene opiniones básicas sobre programación
- Si creas un skill centrado en conocimiento, debes enfocarte en información que lo saque de la forma general en que suele razonar Claude
- El skill frontend-design es un buen ejemplo: fue creado por ingenieros de Anthropic iterando con clientes para mejorar el criterio de diseño de Claude, evitando patrones típicos como la tipografía Inter y gradientes morados
-
Construye una sección de Gotchas
- En todos los skills, el contenido con mayor valor de señal es la sección de Gotchas
- Debe construirse a partir de los puntos de fallo que Claude encuentra con frecuencia al usar el skill
- Lo ideal es seguir actualizando esos gotchas con el tiempo
-
Usa el sistema de archivos y la divulgación progresiva
- Como un skill es una carpeta, se debe usar todo el sistema de archivos como medio de ingeniería de contexto y divulgación progresiva
- Si le dices a Claude qué archivos hay en el skill, los leerá en el momento adecuado
- La forma más simple: separar firmas detalladas de funciones y ejemplos de uso en Markdown aparte, como references/api.md
- Si la salida final es Markdown, también puedes incluir archivos de plantilla en la carpeta assets/
- Carpetas con referencias, scripts y ejemplos mejoran la eficiencia de trabajo de Claude
-
No restrinjas demasiado a Claude
- Claude intenta seguir instrucciones, pero los skills tienen alta reutilización, así que hay que tener cuidado con instrucciones demasiado específicas
- Debes darle la información necesaria, pero también dejar margen para que se adapte con flexibilidad a la situación
-
Diseña el proceso de configuración (Setup)
- Algunos skills necesitan una etapa de configuración para recopilar contexto del usuario
- Por ejemplo: si un skill publica un standup en Slack, debe preguntar en qué canal publicarlo
- Un buen patrón: guardar la información de configuración en un archivo config.json dentro del directorio del skill, y si no está configurado, el agente le pregunta al usuario
- Si quieres presentar preguntas estructuradas de opción múltiple, puedes indicar el uso de la herramienta AskUserQuestion
-
El campo Description es para el modelo
- Cuando Claude Code inicia una sesión, construye una lista de descriptions de todos los skills disponibles
- Claude revisa esta lista para decidir: “¿hay un skill que encaje con esta solicitud?”
- Por eso, el campo description no es un resumen, sino una explicación de cuándo debe activarse ese skill
-
Memoria y almacenamiento de datos
- Un skill puede incluir memoria en forma de datos almacenados
- Puede ser desde un simple archivo de log en texto o JSON hasta una base de datos SQLite
- Ejemplo: si el skill standup-post guarda todo el historial de publicaciones en standups.log, en la siguiente ejecución Claude puede leer su historial y detectar cambios desde ayer
- Los datos guardados en el directorio del skill pueden borrarse al actualizar el skill, así que deben guardarse en una carpeta estable llamada
${CLAUDE_PLUGIN_DATA}
-
Guardar scripts y generar código
- Una de las herramientas más poderosas que puedes darle a Claude es el propio código
- Si le das scripts y librerías, Claude puede enfocarse en composición en lugar de reconstruir boilerplate
- Ejemplo: incluir en un skill de ciencia de datos una librería de funciones helper para traer datos desde una fuente de eventos
- Claude puede combinar esas funciones y generar scripts al vuelo para análisis complejos como “¿qué pasó el martes?”
-
On Demand Hooks
- Un skill puede incluir hooks que se activan solo cuando se invoca y persisten solo durante la sesión
- Son ideales para hooks con opiniones fuertes que serían costosos de ejecutar siempre, pero muy útiles en situaciones concretas
- Ejemplos:
/careful — bloquea rm -rf, DROP TABLE, force-push y kubectl delete con un matcher de PreToolUse, activado solo al trabajar en producción/freeze — bloquea todo Edit/Write fuera de un directorio específico, útil para evitar cambios accidentales durante debugging
Distribución de skills
- Una de las grandes ventajas de los skills es que se pueden compartir con todo el equipo
- Hay dos formas de compartirlos:
- Hacer check-in del skill en el repo (debajo de
./.claude/skills)
- Convertirlo en un plugin y subirlo al marketplace de Claude Code Plugin, para que los usuarios lo instalen
-
Gestión del marketplace
- Cuando un equipo pequeño trabaja en pocos repos, conviene hacer check-in en el repo
- Como los skills versionados así se agregan poco a poco al contexto del modelo, cuando la escala crece conviene más un marketplace interno de plugins
- No existe un equipo central que decida qué skills entran al marketplace; los más útiles se descubren de forma natural
- Si hay un skill que quieras probar, súbelo a la carpeta sandbox de GitHub y anúncialo en Slack o canales similares
- Cuando consigue suficiente tracción, el owner del skill abre un PR para moverlo al marketplace
- Como es fácil crear skills malos o duplicados, es importante contar con un mecanismo de curaduría antes del release
-
Composición de skills (Composing Skills)
- Puede haber necesidad de dependencias entre skills (por ejemplo, un skill de subida de archivos + un skill que genera y sube CSV)
- Aunque el marketplace o los skills no tienen gestión de dependencias nativa, si se hace referencia a otro skill por nombre, el modelo lo invoca si está instalado
-
Medición de skills
- Para entender el rendimiento de los skills, usan un hook PreToolUse para registrar el uso de skills dentro de la empresa
- Esto sirve para identificar skills populares o skills que se activan menos de lo esperado
Conclusión
- Skills es una herramienta muy poderosa y flexible para agentes, pero todavía está en una etapa temprana y todos siguen descubriendo la mejor forma de usarla
- Este texto no es una guía definitiva, sino una colección de consejos que funcionaron en la práctica
- La mayoría de los skills empezaron con unas pocas líneas y un gotcha, y la gente los fue ampliando y mejorando continuamente cada vez que Claude encontraba nuevos casos límite
1 comentarios
Lo que siento últimamente al ver a Anthropic es que sus responsables de desarrollo comparten al máximo lo que han aprendido de su experiencia para impulsar a la gente a usar mejor sus productos.
Parece un caso que muestra en la práctica: "así es como se va construyendo el ecosistema de desarrollo en la era de la IA".