Cómo crear una skill de Claude: SKILL.md en 10 min

Probamos skills de Claude a diario, cientos hasta ahora, y el patrón es deprimente: la mayoría de las skills que fallan en nuestra revisión no fallaron porque el autor no supiera escribir instrucciones. Fallaron porque la skill nunca se cargó, o se cargó cuando no debía, o eran tres skills disfrazadas con una gabardina. Todo se puede arreglar en el momento de escribirla, nada se puede arreglar después con un README más bonito.

Este es el tutorial que desearíamos que hubiera leído cada persona que envía una skill. Al final tendrás una skill funcional: una checklist de revisión de código que empuja a Claude más allá de "se ve bien, quizá renombra esta variable" hacia comprobar condiciones límite, rutas de error y código muerto. Es un ejemplo real a propósito. La mejor skill comunitaria de nuestra categoría de programación, Code Review Checklist, hace exactamente esto y saca 8/10 en resultado. La tuya no la superará el primer día, pero entenderás cada decisión que tomó el autor de esa skill.

La promesa de los 10 minutos es honesta con un asterisco. Escribir la primera versión funcional lleva unos 10 minutos. Probarla como es debido lleva otros 30. Sáltate la segunda parte y te unirás a la mitad de las skills publicadas que no sobreviven al contacto con una sesión nueva. Hicimos la autopsia en por qué la mitad de las skills de Claude no funcionan, y preferiríamos no añadir la tuya al conjunto de datos.

Si nunca has instalado una skill y no sabes qué es una, lee primero qué son las skills de Claude y cómo instalarlas. Este artículo asume que ya usaste al menos una.

Paso 1: acótala a un solo trabajo

Antes de escribir una línea, decide qué hace tu skill. Luego recorta eso a la mitad.

El fallo más grande que vemos en las pruebas son skills que intentan hacerlo todo. "Ayuda con la calidad del código" suena a un alcance razonable. No lo es. Una skill así quiere activarse en revisiones, refactors, escritura de tests y debates de arquitectura, lo que en la práctica significa que Claude no puede saber cuándo cargarla, así que se carga de forma impredecible o nunca. Los problemas de activación son la razón número uno por la que una skill puntúa bajo en nuestra metodología, por delante de instrucciones malas e instalaciones rotas. No porque activarse bien sea la parte más difícil de escribir una skill, sino porque el alcance descontrolado aguas arriba lo vuelve irresoluble aguas abajo.

Una skill, un trabajo. Aquí está la prueba: ¿puedes terminar la frase "usa esta skill cuando el usuario pida ___" con una sola frase verbal concreta? "Revisar un pull request o diff" pasa. "Mejorar su código" falla. Si tu frase tiene un "y" o un "o" uniendo actividades sin relación, estás escribiendo dos skills. Escribe dos skills. Las carpetas son gratis.

Para nuestro ejemplo, el alcance es: revisar un diff o PR en busca de bugs de corrección, usando una checklist fija, suprimiendo quejas de estilo. No "ayudar con revisiones". No "revisar y arreglar". Revisar, informar, parar.

Paso 2: la plantilla de SKILL.md

Una skill es una carpeta con un archivo obligatorio. La nuestra va en ~/.claude/skills/ para uso personal, o en .claude/skills/ dentro de un repo si todo el equipo debe tenerla:

review-checklist/
  SKILL.md          ← obligatorio, y a menudo todo lo que necesitas
  reference/        ← opcional, se carga solo cuando Claude decide leerlo
  templates/        ← opcional, archivos a los que apuntan tus instrucciones

Aquí está el SKILL.md completo que vamos a construir, anotado. Cópialo, luego lee las anotaciones, porque dos de estas líneas importan mucho más que el resto:

---
# 'name' es un identificador: minúsculas, guiones, sin espacios.
# Claude lo ve, pero NO determina la activación.
name: review-checklist

# 'description' es lo ÚNICO que Claude lee al decidir si carga
# esta skill. Todo lo que está debajo del frontmatter es invisible
# hasta después de esa decisión. Escríbela como una condición de
# activación, no como copy de marketing.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

Esa es toda la skill. Sin paso de build, sin manifiesto, sin registro. Reinicia tu sesión de Claude y ya está activa.

El frontmatter tiene exactamente dos campos que importan. name es papeleo. description lo decide todo, y aquí está el porqué: Claude mantiene en contexto solo el nombre y la descripción de cada skill instalada. El cuerpo de tu SKILL.md no existe, en lo que al modelo respecta, hasta que lee tu descripción, decide "esto encaja con lo que quiere el usuario" y carga el resto. Una checklist brillante de 200 líneas detrás de una descripción vaga es una checklist brillante de 200 líneas que nadie ejecutará jamás. En nuestra rúbrica de puntuación, la activación pesa tanto como la calidad del resultado exactamente por esta razón. Una skill que se activa el 40% de las veces es una moneda al aire con pasos extra.

Paso 3: escribe la descripción de activación

Ya que la descripción es una condición de activación, escríbela como tal. Nombra las frases que escribiría un usuario real. Incluye el espacio negativo, es decir, las solicitudes cercanas donde la skill debería quedarse callada.

Lado a lado, de envíos reales que hemos probado (ligeramente anonimizados):

Mala:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Buena:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

La mala describe el beneficio. La buena describe el momento. Claude no lee tu descripción para dejarse convencer; está haciendo coincidir patrones con las palabras reales del usuario. "Revisa este PR" no comparte vocabulario con "ayuda a mejorar la calidad del código", así que la skill duerme durante su propio caso de uso. Probamos un envío casi idéntico a ese mal ejemplo: se activó en 1 de 8 prompts con forma de revisión. Después de reescribir la descripción para nombrar frases, con el mismo cuerpo, se activó en 8 de 8.

Otro par, este sobre el espacio negativo:

Mala:

description: Use for anything related to testing.

Buena:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

"Cualquier cosa relacionada con testing" es como acabas secuestrando una sesión de depuración. La sobreactivación es más silenciosa que la infraactivación y igual de dañina: el usuario recibe respuestas con sabor a checklist a preguntas que necesitaban otra cosa, culpa al modelo, desinstala la skill.

Reglas mecánicas que se sostienen en todo lo que hemos probado: nombra de tres a cinco frases concretas de usuario, incluye al menos una cláusula "no uses", mantente por debajo de unos 500 caracteres, y nunca uses las palabras "powerful", "comprehensive" o "helps with". Esas palabras se correlacionan con puntuaciones de activación fallidas en nuestros datos de forma tan consistente que ya nos hacemos notar al verlas.

Paso 4: escribe un cuerpo que Claude realmente siga

Una vez que la skill se carga, el cuerpo es el conjunto de instrucciones. El fallo aquí es más sutil que la activación pero igual de común: instrucciones que inspiran en lugar de restringir. "Escribe una revisión minuciosa y reflexiva" es un póster motivacional. Claude ya quiere ser minucioso y reflexivo; ese es el comportamiento por defecto que intentas moldear, no la forma que le das.

Las skills que encabezan nuestro ranking son listas de restricciones. Test-Driven Development prohíbe implementar antes de que exista un test que falle, sin excepciones. Nuestra skill de ejemplo limita los hallazgos a 10 y prohíbe las quejas de estilo directamente. Fíjate en cuántas de sus líneas empiezan con "no". Es deliberado. Los modelos sobregeneran por defecto, así que las instrucciones de mayor valor suelen ser sustractivas.

Reglas prácticas para el cuerpo:

1. Los procedimientos numerados superan a la prosa. "Trabaja esto en orden" le da a Claude una columna vertebral; los párrafos le dan vibras.
2. Indica la condición de parada. Nuestra skill dice informar hallazgos, no arreglarlos. Sin esa línea, Claude empezará amablemente a reescribir el código, que nadie pidió.
3. Legisla el formato de salida. Cantidades máximas, campos obligatorios, cómo se ve un resultado limpio. "Si el diff está limpio, dilo" evita hallazgos inventados, un fallo que detectamos constantemente en skills de revisión.
4. Pon el detalle poco frecuente en archivos reference/. Si tu skill tiene una guía de estilo de 300 líneas que aplica una vez al mes, no la pegues en SKILL.md donde quema contexto en cada activación. Guárdala como reference/style-guide.md y escribe "cuando el usuario pregunte sobre X, lee primero reference/style-guide.md". Claude lo carga bajo demanda.

¿Cuándo añades scripts y plantillas? Solo cuando las instrucciones no puedan hacer el trabajo. Una skill que genera un archivo de configuración específico debería incluir un templates/config.yaml y decir "copia esto, luego modifícalo". Una skill que necesita comportamiento determinista, digamos parsear un formato de lockfile, debería incluir un script e indicarle a Claude que lo ejecute en lugar de reimplementarlo de memoria cada vez. Pero la mayoría de las skills no necesitan ninguno de los dos. Nuestro ejemplo no necesita ninguno. Cada archivo en la carpeta es algo que ahora mantienes, así que gánatelo.

Paso 5: pruébala en local

No has terminado cuando funciona una vez. "Me funcionó cuando la probé" es el estándar de prueba de toda skill rota que hemos visto fallar. Aquí está la batería mínima, y se corresponde de cerca con lo que ejecuta nuestra metodología sobre los envíos:

1. Sesión nueva. Reinicia Claude Code por completo. Las skills se cargan al inicio de la sesión; probar en la sesión donde la escribiste no demuestra nada.
2. Prueba de activación, positiva. Prueba tres frases distintas que escribiría un usuario real: "revisa este PR", "¿puedes revisar este diff antes de que haga merge?", "échale un ojo a mis cambios". Las tres deberían activar la skill. Puedes saber que se activó porque el resultado sigue tus reglas (una lista de hallazgos limitada y ordenada por severidad no se parece en nada a una revisión por defecto). Si no estás seguro, pregúntale a Claude directamente si usó la skill.
3. Prueba de activación, negativa. Prueba tres solicitudes cercanas que NO deberían activarla: "arregla este bug", "escribe una función que parsee fechas", "¿por qué falla este test?". Si tu checklist de revisión aparece en una sesión de depuración, tu descripción necesita una cláusula "no uses".
4. Comparación con línea base. Ejecuta el mismo prompt de revisión en una sesión con la skill y otra sin ella. Si no puedes distinguir los resultados, la skill no se está ganando su contexto y deberías afinar las restricciones. Esta es nuestra prueba favorita porque es brutal. Cerca de un tercio de las skills que revisamos la fallan.
5. Prueba de instalación limpia. Si planeas publicarla: copia la carpeta a otra máquina (o bórrala y clónala de nuevo), sigue tu propio README al pie de la letra, y ve si funciona. Las notas de dependencias faltantes mueren aquí.

Toda la batería lleva 30 minutos. Filtra alrededor del 80% de los fallos que vemos, lo cual es un buen retorno por media hora.

Paso 6: pásala por el validador

Antes de publicar, pega tu SKILL.md en nuestro validador de skills gratuito. Puntúa contra la misma rúbrica que usamos en las revisiones: longitud y especificidad de la descripción, presencia de frases de activación concretas, cláusulas de espacio negativo, densidad de restricciones en el cuerpo, legislación de formato, antipatrones obvios como "powerful" y "anything related to".

Es análisis estático, así que trátalo como tal. Detecta los errores que son visibles en el texto, que en nuestra experiencia son la mayoría, pero no puede ejecutar tu skill contra prompts en vivo. Un pase del validador más la batería del Paso 5 es el listón real. Un pase del validador solo es una skill sin errores de lint que aún podría no activarse.

Si prefieres ayuda interactiva en lugar de un verificador, el Skill Creator de Anthropic es la herramienta que recomendamos. Sacó 9.6 en nuestras pruebas, monta la carpeta, y su paso de optimización de descripción mejoró de forma medible la activación en nuestras propias skills internas. Usar una skill para escribir skills suena a broma y funciona igual.

Paso 7: publica y envía

Publicar es un repo normal de GitHub. Convención de estructura:

your-repo/
  README.md           ← qué hace, comando de instalación, un ejemplo
  review-checklist/
    SKILL.md
    reference/

Pon el comando de instalación en el README como bloque para copiar y pegar, el patrón estándar es git clone más cp -r review-checklist ~/.claude/skills/. Luego añade la etiqueta de tema claude-skills al repo. Esto no es decoración: la etiqueta de tema es cómo nuestro rastreador y cualquier otro directorio descubren skills nuevas. Un repo de skill sin etiquetar es invisible en la práctica.

Un README que vale la pena escribir tiene cuatro cosas: una frase sobre qué hace la skill, el bloque de instalación, un ejemplo de antes/después, y cualquier dependencia. El ejemplo de antes/después hace más por la adopción que todo lo demás junto, porque es la única parte que muestra en lugar de afirmar.

Luego envíala a SkillProof. Probar y listar es gratis. Ejecutamos el envío por el mismo proceso que todo lo demás en el catálogo: instalación limpia desde tu README, batería de activación, comparación con línea base, puntuación de resultado. Si pasa, se lista con una puntuación, y puedes incrustar una insignia "SkillProof tested" en tu README. Para un autor desconocido con un repo de dos días, un veredicto de prueba independiente es la diferencia entre "un SKILL.md aleatorio de internet" y algo que un desconocido realmente instalará. Si no pasa, recibes las notas del fallo, lo arreglas y vuelves a enviarlo. Bastantes skills listadas pasaron por dos rondas.

Errores comunes que vemos en los envíos

Después de unos cientos de revisiones, los mismos cinco siguen apareciendo.

Descripciones vagas. Sigue en primer lugar por un margen amplio. Si tu descripción podría describir otras tres skills, no describe ninguna de ellas.

La skill fregadero. Un solo SKILL.md que maneja revisiones, commits, refactors y documentación. Cada trabajo diluye la activación de los demás. Sepáralo.

Repetir los valores por defecto del modelo. Un cuerpo que dice "sé claro, sé preciso, piensa paso a paso" no añade nada. Claude ya hace eso de todos modos. Si borrar una línea no cambiaría el resultado, borra la línea.

Sin restricciones negativas. Skills que solo dicen qué hacer, nunca qué dejar de hacer. Las líneas de "no" son donde vive la mayor parte del cambio de comportamiento.

Instrucciones de instalación sin probar. El README dice copiar una carpeta; la skill depende en silencio de una segunda skill o un paquete de Python. Muere en nuestro paso de instalación limpia siempre, y es el fallo más evitable de esta lista.

Preguntas frecuentes

¿Necesito saber programar para crear una skill de Claude? No. Un SKILL.md es markdown con una cabecera YAML. Si tu skill incluye scripts auxiliares tendrás que escribirlos, pero las skills de solo instrucciones, que son la mayoría, son escritura pura. La skill de este artículo no contiene ni una línea de código.

¿Cuánto debería medir un SKILL.md? Tan corto como pueda mientras siga restringiendo el comportamiento, típicamente entre 30 y 150 líneas. Por debajo de unas 20 líneas normalmente no añade nada más allá de los valores por defecto; pasadas unas cuantas cientas deberías mover el detalle a archivos reference/. La longitud es un coste que pagas por cada activación, no una señal de calidad.

¿Por qué no se activa mi skill? La descripción, casi siempre. Comprueba que nombra frases que un usuario realmente escribiría en lugar de describir beneficios, y confirma que reiniciaste la sesión después de instalar, ya que las skills se cargan al inicio de la sesión. Si se activa con algunas frases y no con otras, añade las que faltan a la descripción explícitamente.

¿Cuál es la diferencia entre una skill y un servidor MCP? Una skill es instrucciones: markdown que moldea cómo se comporta Claude, sin ningún código ejecutándose en ningún lado. Un servidor MCP es un programa que le da a Claude nuevas capacidades, como consultar tu base de datos. Si tu idea es "Claude debería abordar X de otra forma", es una skill. Si es "Claude necesita acceso a Y", es MCP. Versión más larga en Claude Skills vs MCP.

¿Puedo cobrar por una skill de Claude? No hay un mecanismo de pago integrado; las skills son archivos, y el ecosistema público funciona con repos abiertos. Algunos autores venden packs privados de skills a equipos como entregables de consultoría, lo cual funciona porque el valor es la experiencia codificada, no el archivo. Cualquier cosa pensada para el catálogo público debería tener licencia abierta, porque nadie instala una skill que no puede leer.

Acota un solo trabajo, escribe la activación como una expresión regular en prosa, restringe en lugar de inspirar, y prueba en una sesión nueva antes de contárselo a nadie. Ese es todo el oficio. El resto es iteración, y la cola de envíos está abierta.