Una skill es una carpeta. skills.sh solo la coloca.

Pego la misma lista en cada ventana de chat. Cómo debe verse un pull request aquí. Cuándo el agente tiene que parar en vez de decir «listo». Cómo se monta un post en este sitio. AGENTS.md ya es largo — y crece con cada excepción.

Para eso están las skills. Y skills.sh es la parte que las encuentra y las coloca.

La respuesta corta

Una skill es una carpeta con un archivo llamado SKILL.md. Ahí dice qué debe hacer el agente y cuándo. Al lado pueden ir scripts, textos de referencia y plantillas. El agente primero ve solo el nombre y la descripción. El resto lo carga cuando la tarea encaja.

skills.sh es el directorio público y la CLI que va con él, operado por Vercel. El formato viene de Anthropic y está abierto en agentskills.io. El sitio no es la especificación. La CLI no es el agente.

Instalar:

npx skills add vercel-labs/agent-skills

La CLI detecta qué agentes tienes en local y deja las carpetas donde ellos las buscan: .claude/skills/ en Claude Code, .agents/skills/ en Cursor, y así. El valor por defecto es el proyecto actual. Con -g la skill aterriza en tu directorio home y vale en todas partes.

La documentación oficial es skills.sh/docs, la CLI está en GitHub. Lo que sigue es la versión que me habría gustado tener: en qué se diferencia una skill de MCP y de AGENTS.md, cómo encontrar una sin creerte el leaderboard — y los sitios en los que falla en silencio.

Tres nombres, un lío

Agent Skills es la carpeta. Frontmatter YAML con name y description, Markdown debajo. Esa es la especificación. Un agente que la habla puede leer la misma carpeta — Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI y docenas más. La lista actual está en el README de la CLI.

skills.sh es npm para esas carpetas. El sitio muestra lo que la gente instala. La CLI (npx skills) copia o enlaza al path que conoce tu agente. Puedes dejar la misma carpeta a mano, sin CLI. Puedes usar la CLI sin el sitio. Ninguno de los dos es el formato.

El path local es donde mira tu agente. Una skill en ~/.claude/skills/ no la ve Cursor. Una que solo está en .agents/skills/ no la ve Claude Code. La CLI te hace el cableado — si le dices para qué agente.

Quien busca «skills» cae en Anthropic, o en Vercel, o en un ranking de instalaciones. Tres capas. Solo la primera es la capacidad. Las otras dos la transportan.

Skill, MCP o AGENTS.md

Tres mecanismos que la gente tira al mismo saco:

AGENTS.md y CLAUDE.md están siempre puestos. Hechos del repo, convenciones, cosas que tienen que ser verdad en cada sesión. Cuando el archivo se vuelve un procedimiento — una lista, un flujo de varios pasos, «lee primero X, luego Y» — eso va a una skill. La descripción cuesta unos cuantos tokens. El resto carga solo cuando la tarea encaja.

Una skill es saber procedimental. Cuándo actuar, en qué orden, cómo sabes que has terminado, qué trampas hay. Puede traer scripts que el agente ejecuta en vez de reescribirlos cada vez.

MCP engancha herramientas: APIs, bases de datos, el navegador. El agente puede entonces llamar a algo. Una skill le dice cuándo y cómo. Se complementan. Un MCP de navegador sin skill hace clic en algún sitio. Una skill sin herramienta describe pasos que el agente no puede dar.

Regla: si vale en cada sesión, va a AGENTS.md. Si repites el mismo procedimiento, se vuelve una skill. Si el agente necesita una interfaz externa, eso es MCP.

Instalar una skill

Necesitas Node para que exista npx, y al menos un agente que la CLI conozca. Entonces basta la forma corta owner/repo:

npx skills add vercel-labs/agent-skills

Es el ejemplo de la documentación oficial. Clona el repo, busca SKILL.md y pregunta qué skills y qué agentes. Para CI, o si no quieres las preguntas:

npx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code -y

--skill toma un nombre, o '*' para todas. -a apunta a un agente (claude-code, cursor, codex, …). -g escribe en ~/ en vez de en el proyecto. --copy copia en vez de enlazar; los symlinks son la recomendación, porque entonces una actualización tiene una sola fuente.

No tiene que ser el atajo de GitHub. URL completa de GitHub, GitLab, cualquier URL git, un path local, incluso un SKILL.md directo o un archivo. Los repos privados usan la autenticación que Git ya tiene — ningún token extra, salvo que pongas GITHUB_TOKEN a propósito.

Después de ejecutarlo:

npx skills list

En Claude Code la carpeta debería estar en .claude/skills/<name>/, en Cursor en .agents/skills/. Escribe / y busca el nombre, o haz una pregunta que encaje con la description. Si no pasa nada: mira el YAML, mira el path, reinicia el agente. La CLI registra el path de destino; no adivines.

Usar una skill sin instalarla:

npx skills use vercel-labs/agent-skills@web-design-guidelines | claude

Escribe los archivos en un directorio temporal e imprime un prompt. Con --agent la CLI arranca el agente. Vale para probar. Si quieres conservarla, mejor add.

Los equipos pueden armar un pack en skills.sh: varias skills, también privadas, una URL de instalación de la forma npx skills add https://skills.sh/p/<id>. Los packs son unlisted, no tienen control de acceso. Quien tenga la URL puede instalar. No metas secretos.

Buscar sin creerte el leaderboard

El sitio tiene All Time, Trending (24h) y Hot. Los números salen de telemetría anónima de la CLI — activa por defecto, deduplicada cada hora: qué skill, en qué agente. Sin contenido, sin personas. Se apaga con DISABLE_TELEMETRY=1 o DO_NOT_TRACK=1.

El leaderboard cuenta instalaciones, no calidad. Una meta-skill que ayuda a buscar acumula installs porque la CLI la ofrece — no porque resuelva tu problema concreto. Packs de Azure, kits de diseño, pipelines de vídeo: un número alto significa «mucha gente ejecutó npx skills add», a menudo para un repo entero de una vez.

Mejor:

npx skills find

Sin argumento es una búsqueda interactiva, con argumento un keyword (npx skills find typescript). --owner vercel lo limita a los repos de esa org. Y entonces lee el SKILL.md antes de instalar. skills.sh muestra por entrada la fuente, auditorías de seguridad de los partners y en qué agentes aterriza. Las skills que fallan en todos los partners salen del directorio. Eso no es carta blanca. Anthropic dice lo mismo en su propia documentación: una skill puede traer instrucciones y código. Trátala como software que instalas.

Estar en el leaderboard significa que la gente ejecutó npx skills add owner/repo. No hay una revisión que te admita. Tampoco hay una que baje una skill mala, mientras las auditorías no fallen.

Escribir la tuya

La tercera vez que vuelcas las mismas instrucciones en una ventana de chat es el momento.

npx skills init my-skill

crea un SKILL.md. Los dos campos obligatorios:

---
name: my-skill
description: What this skill does and when to use it
---

name va en minúsculas, con guiones, máximo 64 caracteres, igual que el nombre de la carpeta. description dice las dos cosas: qué hace y cuándo debe cargarla el agente. «Helps with PDFs» se queda corto. «Extracts text and tables from PDF files, fills forms, merges files. Use when handling PDFs.» da en el clavo, porque el agente contrapone la descripción a tu mensaje.

El resto es Markdown. Pasos, ejemplos, bordes. La especificación recomienda mantener SKILL.md por debajo de 500 líneas y mover el detalle a references/. Los scripts a scripts/. Las plantillas a assets/. El agente carga esos extras solo cuando las instrucciones apuntan a ellos.

Una buena skill es aburrida de leer. Dice qué hacer, cómo se nota que ha quedado y cuándo parar. No explica por qué las skills son el futuro. El agente no se entera, y no quieres gastar los tokens en eso.

Para distribuir basta un repo público de GitHub donde la CLI encuentre un SKILL.md — en la raíz, bajo skills/, o en los paths que usa el propio agente (.claude/skills/, .agents/skills/, …). En cuanto alguien ejecuta npx skills add contra él, aparece en la telemetría.

Cuando no dispara

La lista de siempre, en el orden en que miro:

1. ¿Está la carpeta donde este agente busca? Claude Code no mira en ~/.cursor/skills/.
2. ¿Son name y description YAML válido? Sin los dos campos la CLI no encuentra la skill.
3. ¿La descripción encaja con la tarea? Si solo dice «utility for developers», el agente no la carga nunca. La descripción es el índice.
4. ¿Has instalado en global y la esperas en el proyecto — o al revés?
5. ¿Alguien puso disable-model-invocation? Entonces tienes que llamarla tú con /name. Es un campo de Claude Code, no parte de la especificación abierta.

npx skills list muestra lo que la CLI cree instalado. El agente tiene su propia vista. Contrasta las dos contra el path, no entre sí.

Y: una skill que arranca un script corre con los mismos permisos que el agente. Lee SKILL.md y todo lo que hay bajo scripts/ antes de pulsar -y.

Lo que de verdad dejo correr

En este sitio hay skills para la portada de un post, para infografías y para texto que suena a chatbot. Son carpetas. No las saqué del leaderboard. Las escribí porque explicaba el mismo flujo cada vez.

No instalo cuarenta «por si acaso». Cada descripción ocupa contexto desde el arranque. Veinte skills vagas salen más caras y fallan más que tres precisas. Las que me quedo tienen un borde claro: ese procedimiento que si no volvería a teclear.

Si una skill no te dispara y no quieres pasarte la noche en YAML, escríbeme. A veces solo falta la frase «Use when…» en la descripción.