Skills: instrucciones especializadas
Imagina que cada vez que el equipo audita un componente, el agente lo hace de una forma distinta. Una skill es la solución: un archivo de instrucciones que define exactamente cómo ejecutar esa tarea — siempre igual, siempre con el contexto correcto.
Qué es una skill
Una skill es un archivo markdown en .claude/skills/ que contiene un proceso completo: qué leer antes de empezar, qué pasos seguir, qué formato tiene el resultado y qué no hacer. El agente la carga solo cuando la tarea encaja con su descripción.
Definición clave
No es un prompt guardado. No es documentación. Es un protocolo de trabajo que el agente sigue de forma consistente cada vez que ejecuta esa tarea.
Sin skill
Usuario: “Audita el componente ArticleCard.”
Agente: “Aquí va mi análisis...” (cada vez diferente, sin estructura, sin consultar el DS)
Con skill component-audit
Usuario: “Audita el componente ArticleCard.”
Agente: “Leyendo components.md y tokens.md...” (proceso definido, mismo output siempre)
Cuándo crear una skill
Cuatro señales claras de que necesitas convertir un proceso en una skill.
Repites el mismo proceso
Si describes los mismos pasos en el prompt más de dos veces, eso es una skill esperando ser escrita.
El resultado es inconsistente
Si dos sesiones con el mismo pedido producen resultados distintos, una skill estandariza el proceso.
El output tiene un formato fijo
Si el equipo espera siempre una tabla, un documento markdown o una estructura específica, eso va en una skill.
La tarea requiere leer docs concretos
Si antes de actuar el agente siempre debe consultar los mismos archivos del proyecto, una skill lo hace automático.
Cómo se activa una skill
El proceso de activación es automático en 4 pasos.
Tarea
Paso 01El agente recibe una tarea del usuario.
Lectura
Paso 02Lee el campo
descriptionde cada skill disponible en.claude/skills/.Matching
Paso 03Si la descripción encaja, carga la skill completa y sigue su proceso.
Ejecución
Paso 04Ejecuta los pasos, lee los docs indicados y genera el output en el formato definido.
Qué tiene una skill que no tiene el CLAUDE.md
Las columnas muestran la diferencia clave entre el contexto permanente (CLAUDE.md) y las instrucciones especializadas (skill).
| Aspecto | Hacer | Evitar |
|---|---|---|
| Cuándo se carga | Skill: solo cuando la tarea la requiere | CLAUDE.md: siempre, en cada sesión |
| Qué contiene | Skill: proceso paso a paso para una tarea concreta | CLAUDE.md: contexto permanente del proyecto |
| Formato de salida | Skill: define exactamente qué generar y cómo | CLAUDE.md: no define formato |
| Qué leer antes | Skill: lista explícita de docs a consultar | CLAUDE.md: no especifica |
| Longitud típica | Skill: 50-150 líneas por skill | CLAUDE.md: ~200 líneas máx. |
Anatomía de una skill
Una skill tiene 6 bloques fundamentales. Cada uno cumple un rol específico en el proceso del agente.
1---2name: component-audit3description: Audita componentes contra4 el design system. Úsalo cuando5 se pida revisar o validar UI.6allowed-tools: Read, Grep, Glob7---89# Cuándo aplicar esta skill1011Cuando el usuario pida:12- "audita este componente"13- "revisa si esto sigue el DS"14- "compara con nuestros componentes"15- "¿este componente ya existe?"1617# Proceso18191. Leer /design-system/components.md20 — inventario de componentes21222. Leer /design-system/tokens.md23 — valores de color y espaciado24253. Identificar si el componente26 existe o es una variante27284. Revisar:29 - Naming (¿PascalCase?)30 - Tokens (¿hardcoded o del DS?)31 - Estados: default · hover ·32 focus · disabled · error33 - Accesibilidad: contraste, ARIA3435# Formato de salida3637Tabla markdown:38| Aspecto | Estado | Nota | Prioridad |3940Estados: ✅ Correcto · ⚠️ Ajuste41 · ❌ Problema4243Terminar con resumen en 2-3 líneas.4445# Restricciones4647- No proponer cambios fuera48 del design system existente49- No sugerir librerías externas50- Si un componente no existe,51 marcarlo como candidato —52 no crearlo por cuenta propiaFrontmatter
Bloque 1El encabezado YAML le dice a Claude Code el nombre de la skill, cuándo usarla (description) y qué herramientas puede usar. El campo description es el más importante: Claude lo lee para decidir si esta skill es relevante.
Tip: Read, Grep y Glob son suficientes para skills de diseño. Solo añade Write o Bash si la skill necesita modificar archivos.
Cuándo activar
Bloque 2Lista de frases o situaciones que deben activar esta skill. Ayuda al agente a reconocer el patrón incluso cuando el usuario no usa exactamente esas palabras.
Tip: Incluye tanto la forma directa (“audita este componente”) como la indirecta (“¿esto sigue el design system?”).
Qué leer antes
Bloque 3Indicar explícitamente qué documentos leer antes de actuar es lo que convierte una skill genérica en una skill del proyecto. Especifica la ruta exacta y para qué sirve cada archivo.
Tip: El orden importa. Si hay dependencia entre documentos, especifícalo. El agente sigue el orden que le des.
Qué revisar
Bloque 4La parte central de la skill: qué hace el agente, en qué orden, con qué criterios. Cuanto más concreto, menos espacio para la improvisación. No describas el resultado — describe el proceso.
Tip: Si el proceso tiene bifurcaciones (“si X, entonces Y”), exprésalas explícitamente. El agente no asume — sigue instrucciones.
Formato de salida
Bloque 5El formato de salida es lo que hace reproducible el trabajo del agente. Dos personas que usen la misma skill deben obtener el mismo tipo de resultado. Especifica: tipo de documento, columnas o secciones, y cómo cerrar la respuesta.
Tip: “Terminar siempre con un resumen de 2-3 líneas” es una instrucción de cierre que el agente sigue consistentemente.
Restricciones
Bloque 6Las restricciones de una skill son su parte más valiosa. Definen qué no debe hacer el agente aunque tenga la capacidad. Son más específicas que las del CLAUDE.md — aplican solo a esta tarea concreta.
Tip: Cada restricción suele venir de un error que ya ocurrió. La primera vez que el agente proponga algo fuera de scope, añade la restricción.
Qué skills crear primero en un equipo de diseño
Cinco skills fundamentales que cubren las tareas más repetidas de un equipo de diseño.
component-audit
Audita un componente contra el design system. Revisa naming, tokens, estados y accesibilidad básica. Output: tabla con prioridades.
trigger: “audita”, “revisa si sigue el DS”, “¿ya existe?”
handoff-spec
Genera una especificación de entrega completa: variantes, props, estados, tokens y notas de accesibilidad. Output: documento markdown listo para desarrollo.
trigger: “genera la spec”, “prepara el handoff”, “documenta este componente”
ux-review
Evalúa un flujo o pantalla contra los arquetipos de usuario y los principios de diseño del proyecto. Identifica fricciones y oportunidades. Output: lista priorizada.
trigger: “revisa este flujo”, “¿qué mejorarías?”, “evalúa desde el usuario”
token-check
Analiza código o especificaciones y detecta valores hardcoded que deberían ser tokens del sistema. Propone el token correcto para cada caso.
trigger: “¿usa los tokens bien?”, “busca hardcoded”, “revisa los valores”
new-user-story
Genera user stories a partir de una descripción de feature. Las cruza con los arquetipos del proyecto y añade criterios de aceptación en formato Gherkin.
trigger: “escribe las user stories”, “crea los criterios de aceptación”
Tu próxima skill
Las mejores skills emergen del trabajo real. Cuando repitas el mismo proceso más de tres veces, es señal de que hay una skill esperando ser escrita.
regla: si lo haces 3 veces, escríbela
Dónde viven las skills en el proyecto
Las skills se organizan en carpetas dentro de .claude/skills/. Cada skill es una carpeta con al menos un SKILL.md.
Estructura del proyecto
Cada skill, su propia carpeta
Una skill es una carpeta con al menos un SKILL.md. La carpeta puede incluir recursos adicionales: checklists, templates, scripts. Claude los carga cuando la skill los referencia.
El nombre de la carpeta = el comando
Una skill en .claude/skills/component-audit/ crea automáticamente el comando /component-audit. Puedes invocarlo directamente o dejar que Claude la active cuando detecte que encaja.
Se versiona con el proyecto
Toda la carpeta .claude/ va en el repositorio. El equipo comparte las mismas skills desde el primer git clone. No hay configuración adicional.
Compatible con commands/
Si ya tienes archivos en .claude/commands/, siguen funcionando exactamente igual. Las skills son una evolución del mismo sistema, no un reemplazo.
Recursos para ir más lejos
Documentación oficial, repositorios y marketplaces de skills.
Extend Claude with Skills
Documentación oficialcode.claude.com
Guía oficial de Anthropic. Cómo crear, invocar y distribuir skills. Incluye frontmatter, bundled skills y límites de contexto.
anthropics/skills
Repo oficialgithub.com
Repositorio oficial de Anthropic con skills de producción: documentos (docx, pdf, pptx), arte generativo, testing web, MCP y más.
awesome-agent-skills
Comunidadgithub.com
La colección comunitaria más completa. Skills oficiales de Vercel, Stripe, Cloudflare, Sentry, WordPress y cientos de contribuidores.
SkillsMP
Marketplaceskillsmp.com
Marketplace con buscador inteligente sobre 350.000+ skills compatibles con Claude Code. Filtros por categoría, popularidad y autor.
AgentSkills.io
Estándaragentskills.io
Especificación canónica del formato SKILL.md. Checklist de validación antes de publicar y guía de authoring oficial.
awesome-claude-skills
Comunidadgithub.com
Lista curada con changelog de adopción, tutoriales de la comunidad en DEV.to y Medium, y skills por categoría.
Conclusión
Cuando el agente trabaja sin instrucciones, improvisa. Una skill elimina esa improvisación: define exactamente qué hacer, en qué orden y con qué resultado. El equipo sabe qué esperar. Siempre.