Skills de Claude: qué son y cómo crear la tuya, con las 49 que usamos

Una skill de Claude es una carpeta con un fichero SKILL.md: unas líneas de cabecera que dicen qué hace y cuándo usarla, y debajo las instrucciones. Claude solo tiene a la vista la cabecera de cada skill y carga el resto cuando tu petición encaja, así que puedes tener decenas sin llenar el contexto. Aquí vas a crear una que revisa y publica un artículo con checklist, aprender a escribir la descripción para que se active cuando toca y ver cómo mantenemos las 49 que usa a diario nuestro asistente.

Todo lo técnico está comprobado el 16 de octubre de 2026 en la documentación oficial de Anthropic y en la especificación abierta de Agent Skills, y lo hemos usado con Claude Code 2.1.283 en una VPS con Windows Server 2022.

Qué es una skill y qué tiene dentro#

Anthropic presentó las Agent Skills el 16 de octubre de 2025 y el 18 de diciembre de 2025 las publicó como estándar abierto (la especificación está en agentskills.io). Por eso el mismo formato vale en Claude Code, en claude.ai y en la API, y lo pueden leer otros agentes que adopten el estándar.

La estructura mínima es esta:

revisar-articulo/
├── SKILL.md        # obligatorio: cabecera + instrucciones
├── CHECKLIST.md    # opcional: material de consulta
└── scripts/        # opcional: código que Claude ejecuta

La cabecera (frontmatter YAML) tiene dos campos que importan siempre:

Claude Code admite además campos propios: argument-hint, disable-model-invocation, user-invocable, model, context: fork (ejecutarla en un subagente), paths y otros. Funcionan en Claude Code, pero la documentación avisa de que fuera de él (subirla a claude.ai o a la API) solo se aceptan name, description, license, compatibility, metadata y allowed-tools, y un campo de más hace fallar la subida. Si piensas compartirla, quédate en esos seis.

Cómo carga Claude una skill sin llenarte el contexto#

El truco se llama divulgación progresiva (progressive disclosure): la información entra por niveles y solo cuando hace falta.

Desliza para ver la figura completa

Según la documentación oficial, el nivel 1 cuesta unos 100 tokens por skill y se carga al empezar la sesión. El cuerpo se recomienda por debajo de 5.000 tokens y de 500 líneas. Los ficheros de apoyo no cuestan nada hasta que Claude los lee, y de un script solo entra en contexto lo que imprime, no su código.

Dos detalles de Claude Code que conviene saber. Una skill se puede lanzar a mano escribiendo /nombre al principio del mensaje. Y, según la documentación, si editas un SKILL.md Claude Code detecta el cambio en la sesión abierta; solo si creas la carpeta .claude/skills/ cuando la sesión ya estaba en marcha tienes que ejecutar /reload-skills.

Skill, CLAUDE.md, MCP, subagente o comando: cuál usar#

Es la duda más habitual, porque las cinco cosas «le dan instrucciones a Claude». Se diferencian en cuándo cargan y en para qué sirven:

La regla que seguimos sale casi literal de la documentación: si Claude debe saberlo siempre, va al CLAUDE.md; si solo lo necesita para una tarea concreta, es una skill. Y skill y MCP no compiten: el MCP le da a Claude las herramientas del correo, y la skill correo-empresa le explica cuál usar para cada petición y cómo contestar.

Un último matiz: una instrucción en una skill es una petición, no una garantía. Si algo debe cumplirse siempre (bloquear un comando peligroso), la documentación recomienda un hook.

Crear tu primera skill paso a paso#

Vamos a montar revisar-articulo: revisa un artículo del blog contra la guía de estilo, corrige lo que puede, comprueba que compila y no publica sin un sí. Es la versión reducida del proceso que seguimos con este mismo blog.

1. Elige dónde vive. En Claude Code hay tres sitios principales:

   Alcance	Ruta	Quién la ve
   Personal	~/.claude/skills/revisar-articulo/SKILL.md	Tú, en todos tus proyectos
   Proyecto	.claude/skills/revisar-articulo/SKILL.md	Quien trabaje en ese repositorio
   Plugin	<plugin>/skills/revisar-articulo/SKILL.md	Quien instale el plugin; se llama como /plugin:revisar-articulo

   Si dos skills se llaman igual, gana la de empresa, luego la personal y luego la de proyecto. Para un proceso de un repositorio concreto, mejor de proyecto: viaja con el código.

2. Crea la carpeta. En Windows con PowerShell, desde la raíz del proyecto:

   New-Item -ItemType Directory -Force ".claude\skills\revisar-articulo"

   En macOS o Linux: mkdir -p .claude/skills/revisar-articulo. El nombre de la carpeta debe ser el mismo que el campo name.

3. Escribe el SKILL.md. Este es el fichero completo, listo para copiar:

   ---
   name: revisar-articulo
   description: Revisa un artículo del blog (fichero .mdx) contra la guía de estilo y la checklist de publicación, corrige lo que falla, comprueba que el sitio compila y lo deja listo para publicar. Úsala cuando pidan revisar, repasar, corregir o publicar un artículo o un borrador del blog, o antes de dar un artículo por terminado.
   argument-hint: "[ruta-del-articulo.mdx]"
   allowed-tools: Read Grep Bash(npx astro *)
   ---
   
   # Revisar y publicar un artículo
   
   Artículo: $ARGUMENTS (si no te han dicho cuál, pregúntalo antes de empezar).
   
   Copia esta lista en tu respuesta y ve marcándola:
   
   ```
   - [ ] 1. Leer el artículo y la guía de estilo
   - [ ] 2. Pasar la checklist
   - [ ] 3. Corregir y repetir la checklist
   - [ ] 4. Compilar
   - [ ] 5. Pedir el sí y publicar
   ```
   
   ## Pasos
   
   1. **Lee** el artículo entero y `contenido/guia-de-estilo.md`.
   2. **Pasa la checklist** de [CHECKLIST.md](CHECKLIST.md) punto por punto. Apunta cada fallo con su línea.
   3. **Corrige** lo que sea de forma (formato, frases prohibidas, enlaces, longitud de la entradilla). Lo que sea de contenido (una cifra sin fuente, un dato dudoso) no lo arregles inventando: márcalo como pendiente. Vuelve al paso 2 hasta que no quede nada que puedas corregir.
   4. **Compila** desde la carpeta `web` con `npx astro build`. Si falla por este artículo, arréglalo y repite. Si falla por otro fichero, dilo y no lo toques.
   5. **Publicar necesita un sí explícito.** Resume en tres líneas qué has cambiado y qué queda pendiente, y pregunta: "¿Lo publico?". Sin un sí, no cambies `draft: true` a `draft: false`.
   
   ## Al terminar
   
   Una frase: qué artículo, cuántos fallos había, cuántos quedan pendientes y si compila.
   
   <!-- aprendido:inicio -->
   ## Aprendido (manda sobre lo de arriba)
   <!-- aprendido:fin -->

   Tres decisiones que no son de adorno. $ARGUMENTS recoge lo que escribas tras /revisar-articulo. allowed-tools preaprueba esas herramientas solo durante ese turno, sin pedirte permiso cada vez; no restringe las demás. Y la checklist copiada en la respuesta, más el bucle «revisa, corrige, repite», es el patrón que la guía de buenas prácticas de Anthropic propone para tareas de varios pasos.

4. Añade el fichero de apoyo. CHECKLIST.md, en la misma carpeta. Solo se lee en el paso 2, así que puede crecer sin coste:

   # Checklist de publicación
   
   ## Frontmatter
   - [ ] `title` de 50 a 70 caracteres, con la palabra clave al principio si suena natural
   - [ ] `description` de 120 a 160 caracteres, sin repetir el título
   - [ ] `category`, `tipo` y `tags` rellenos
   - [ ] Cada cifra del texto (precio, límite, versión) tiene su entrada en `fuentes`, con fecha de consulta
   
   ## Texto
   - [ ] El primer párrafo responde a la búsqueda en 2 o 3 frases
   - [ ] Ninguna frase prohibida por la guía ("en conclusión", "potente", "crucial"...)
   - [ ] Párrafos de 2 a 4 frases; títulos que dicen algo
   - [ ] Al menos una figura propia y una tabla si se compara algo
   
   ## Enlaces, código y datos
   - [ ] Enlaces internos con barra final (`/que-es-mcp/`)
   - [ ] Bloques de código con su lenguaje
   - [ ] Ni contraseñas, ni tokens, ni IPs, ni correos personales

   Enlázalo desde SKILL.md con ruta relativa y barras normales (CHECKLIST.md, scripts/validar.py), aunque estés en Windows: lo pide la propia guía. Y no encadenes un fichero que enlaza a otro que enlaza a otro: Claude puede leer solo un trozo de los anidados.

5. Compruébala. Abre una sesión nueva de Claude Code en el proyecto y escribe /: debe aparecer revisar-articulo con su pista [ruta-del-articulo.mdx]. Después pruébala de las dos maneras: a mano (/revisar-articulo src/content/articulos/que-es-mcp.mdx) y sin nombrarla («repasa el artículo de MCP antes de publicarlo»). Si la segunda no la activa, el problema casi siempre está en la descripción.

Esta skill la creamos en nuestra VPS y comprobamos su formato contra las reglas del estándar: nombre válido e igual a la carpeta, descripción de 317 caracteres. Ojo con un detalle: argument-hint es propio de Claude Code. Si la quieres subir a claude.ai, quítalo.

La descripción decide si la skill se activa#

Claude elige qué skill usar comparando tu petición con las descripciones. El cuerpo puede ser perfecto, pero si la descripción no dice cuándo usarla, no se carga. La documentación pide dos cosas: qué hace y cuándo usarla, en tercera persona y con las palabras que usaría quien la pide.

Así queda una descripción mala, del tipo que sale cuando escribes deprisa:

description: Ayuda con el correo.

No dice qué correo, ni qué acciones, ni con qué palabras se pide. Esta es la de nuestra skill correo-empresa (recortada para no publicar direcciones):

description: "Lee, busca, responde y envía el correo de la empresa (el buzón de contacto y los del equipo). Úsala SIEMPRE que el dueño diga 'el correo', 'los correos', 'correos nuevos', 'el correo de contacto', qué dice un correo, o pida contestar o mandar un email."

Funciona por tres cosas: enumera los verbos (leer, buscar, responder, enviar), recoge las frases exactas con las que Ferran lo pide y no deja margen para dudar. Cuando dos skills se pisan, añadimos la frontera dentro de la descripción. La de stripe-cobros termina así: «Para cifras de ganancias usa mejor ganancias-gamzyhost». Así, «¿cuánto llevamos este mes?» tiene un destino claro (ganancias) y «¿por qué ha fallado este cobro?», otro (Stripe).

Tres reglas que aplicamos a las 49:

• Lo importante, delante. En Claude Code el listado corta la descripción a 1.536 caracteres, y el estándar abierto la limita a 1.024. Las nuestras rondan los 200-400.
• Las palabras del usuario, no las tuyas. Si tu equipo dice «el host», pon «el host».
• Si tiene efectos que no quieres por sorpresa, añade disable-model-invocation: true: así solo se lanza con /nombre y su descripción ni siquiera ocupa contexto.

El patrón «Aprendido»: la skill se corrige sola#

Una skill escrita una vez se queda vieja en semanas. La solución que usamos en nuestro asistente, Jarvis, es una sección al final de la skill donde el propio agente apunta cada corrección que le hacemos. De las 49 skills instaladas, 35 son nuestras y 14 de terceros (sobre todo de diseño y animación); 19 de las nuestras ya tienen entradas en su «Aprendido».

Desliza para ver la figura completa

Así funciona en la práctica. Cada skill nuestra termina con un bloque entre dos comentarios HTML, aprendido:inicio y aprendido:fin. Cuando corregimos a Jarvis mientras usa una skill, el sistema añade dentro una línea con la fecha y la regla, y la copia en un APRENDIDO.md de la misma carpeta. El título del bloque deja clara la jerarquía: «manda sobre lo de arriba». Este es un extracto real de revisar-orden, la skill que mantiene la VPS ordenada (rutas generalizadas):

<!-- aprendido:inicio -->
## Aprendido (lo ha ido corrigiendo el asistente solo; manda sobre lo de arriba)
- 2026-10-07: Comprobar también %TEMP% y las carpetas de bundle que deja Remotion al
  generar vídeos: pueden acumularse y llenar el disco C: hasta el 99%. Limpiarlas
  junto con el resto de temporales.
- 2026-10-13: Busca también ficheros de 0 bytes con nombres de comandos rotos (restos
  de bash mal escapado); hoy se encontraron 57 repartidos en la carpeta de proyectos.
<!-- aprendido:fin -->

No necesitas nuestro sistema para copiarlo. Basta con añadir al cuerpo de tu skill una instrucción así:

Si el usuario te corrige mientras usas esta skill, añade al final de la sección
"Aprendido" una línea con la fecha (AAAA-MM-DD) y la regla en una frase, escrita
para que se entienda sin conocer la conversación. Díselo al usuario.

La última frase importa: la regla tiene que entenderse sin la conversación delante. En nuestras skills hay alguna línea que solo tenía sentido el día que se escribió, y una regla que no se entiende no sirve.

Errores típicos al crear skills#

• Descripción sin «cuándo». Sin él, la skill no se activa cuando debe. Pon las frases con las que la pedirías.
• Dos skills que se solapan. Claude puede cargar la que no es. Separa los terrenos y escribe la frontera en las dos descripciones.
• Meterlo todo en SKILL.md. Por encima de 500 líneas, pasa el material de consulta a ficheros aparte y enlázalos un nivel por debajo, sin cadenas.
• Explicarle a Claude lo que ya sabe. La guía oficial lo resume así: da por hecho que Claude es listo y añade solo el contexto que no tiene (tus rutas, tus pasos, tus excepciones).
• Nombres que no valen. Mayúsculas, espacios, tildes o la palabra «claude» en name. Usa minúsculas y guiones, igual que la carpeta.
• Rutas con barra invertida. scripts\validar.py falla en Linux. Usa siempre scripts/validar.py.
• Instalar skills de cualquiera. Una skill puede ordenar a Claude ejecutar código. Anthropic recomienda usar solo las tuyas o las de fuentes de confianza y revisar todos sus ficheros antes. Nosotros leemos el SKILL.md y los scripts de cada una antes de instalarla.
• Esperar que una skill sea una barrera. Si algo no puede fallar nunca, es un hook o un permiso, no una frase en una skill.

Skills en claude.ai y en la API#

El formato es el mismo, pero cada superficie va por su lado y no se sincronizan entre sí:

En la API, las skills corren sin acceso a la red y sin poder instalar paquetes; en Claude Code tienen la misma red que cualquier programa de tu equipo. Si quieres ver skills bien hechas, Anthropic publica ejemplos y una plantilla en su repositorio anthropics/skills, que en Claude Code se añade como marketplace con /plugin marketplace add anthropics/skills.

Qué hacer ahora#

1. Piensa en lo que le has explicado a Claude tres veces este mes. Esa es tu primera skill.
2. Copia revisar-articulo, cambia los pasos por los tuyos y reescribe la descripción con tus palabras.
3. Añádele la sección «Aprendido» desde el primer día y revísala cada pocas semanas: lo que se repite, súbelo al cuerpo.

Si todavía no usas Claude Code, empieza por la guía de Claude Code. Para lo que debe saber siempre, mira cómo escribir un buen CLAUDE.md, y para ver cómo encajan las skills en un asistente completo, lee cómo montamos nuestro asistente de IA propio y los ejemplos reales de agentes de IA que usamos en GamzyHost.