THE CLAUDESKILLS HUB
Escribe tu primera skill

Escribe tu primera skill de Claude, de carpeta vacía a instalada

Una skill es una carpeta con un archivo SKILL.md dentro. Esta guía construye una skill real de principio a fin y se detiene en cada punto donde es fácil equivocarse. No asume nada salvo que ya tienes un flujo que has hecho a mano más de una vez.

Los siete pasos

  1. 1. Parte de un flujo que ya has repetido

    No partas de una idea. Parte de algo que hayas hecho a mano al menos tres veces, porque solo así sabes qué pasos son reales y cuáles imaginaste. Si no puedes describir el trabajo sin decir depende, es pronto para codificarlo.

  2. 2. Crea la carpeta y nómbrala con exactitud

    El nombre de la carpeta y el campo name deben coincidir, y el nombre está restringido: solo minúsculas, números y guiones, sin guion inicial ni final, sin guion doble y máximo 64 caracteres. Renombrar después implica renombrar ambos, así que elige un nombre con el que puedas vivir.

    my-skill/
├── SKILL.md          # required
├── references/
│   └── REFERENCE.md  # loaded only when needed
└── scripts/
    └── check.py
    Solo SKILL.md es obligatorio. Lo demás se carga bajo demanda.

  3. 3. Escribe la descripción antes que el cuerpo

    La descripción decide si tu skill llega a cargarse, así que escríbela primero, mientras recuerdas la tarea en las palabras que usaría una persona. Di qué hace y cuándo usarla, e incluye las formas de decirlo que emplearía un compañero, no solo las tuyas.

  4. 4. Escribe el cuerpo como procedimiento, no como ensayo

    El cuerpo se lee solo después de que el agente decidió activar la skill, así que debe contener pasos, puntos de decisión y la forma del resultado. Deja fuera el conocimiento general que el modelo ya tiene: cuesta contexto y no aporta nada.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
---

# Release notes

## Steps
1. List merged pull requests since the previous tag.
2. Group them by user facing change, not by author or by file.
3. Drop internal refactors unless they change behaviour.
4. Write one line per change, in the present tense.

## Output
A Markdown list under a version heading. No emoji. No marketing language.
    Una skill completa y válida. La sección de salida es lo que evita que el formato se desvíe.

  5. 5. Añade campos opcionales solo si se lo ganan

    La mayoría de skills no necesitan nada más que name y description. Añade license al publicar, compatibility solo si el entorno importa de verdad, y metadata para lo que la especificación no define. allowed-tools es experimental, así que da su soporte por incierto.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
license: MIT
compatibility: Requires git and network access to the repository host
metadata:
  author: example-org
  version: "1.2"
---

  6. 6. Divide lo largo en referencias

    El cuerpo se carga entero cada vez que la skill se activa, así que mantenlo por debajo de unas 500 líneas y mueve el detalle a references/. Manten esas referencias a un solo nivel, porque una cadena de archivos que se apuntan entre sí es más lenta y más fácil de perder.

    See [the full grouping rules](references/GROUPING.md).

Run the collector first:
scripts/collect.py --since v1.4.0

  7. 7. Valida y prueba la activación con palabras ajenas

    Ejecuta primero el validador, porque los errores de nombre y frontmatter aparecen como una skill que nunca se carga. Después prueba lo que ningún validador comprueba: pide la tarea como la formularía un compañero y mira si la skill se activa. Si no lo hace, el problema es la descripción, no el cuerpo.

    skills-ref validate ./my-skill

Los cinco errores más caros

Todos producen una skill que parece correcta en revisión y falla en uso, y por eso sobreviven tanto tiempo.

Una descripción escrita con tu propio vocabulario
Coincide con tu forma de decirlo y con la de nadie más. Es la razón más común de que una buena skill nunca se use.
Un ensayo en lugar de un procedimiento
El contexto y la justificación queman tokens cada vez que la skill se activa sin cambiar lo que hace el agente.
Codificar conocimiento que el modelo ya tiene
Explicar qué es un pull request añade tokens y ningún comportamiento. Codifica tus convenciones, no el dominio.
Dos skills que instruyen la misma decisión
El agente recibe instrucciones contradictorias y las resuelve sin que lo veas. Una sola fuente de verdad por trabajo.
No probar nunca la activación
Todo el mundo prueba el cuerpo activando la skill a mano. Casi nadie prueba si se activa sola.

Distribuirla

Una skill es una carpeta, así que distribuirla es publicar esa carpeta en algún sitio instalable, lo más simple un repositorio público que la gente añade con el CLI de skills. Antes de publicar, lee el mapa de compatibilidad: si tu skill instruye sobre una decisión que ya gobierna otra skill popular, dilo en tu propia descripción en vez de dejar que el usuario descubra el conflicto.

npx skills add owner/repo

Referencia de SKILL.mdComprobador de descripcionesConflictos y combinaciones