📁 Estructura del repo para publicar
Para que una skill sea instalable e indexable, el repo debe seguir la convención: una carpeta skills/ en la raíz, y dentro de ella cada skill con su SKILL.md más los resources opcionales. Fuera de esta estructura, el CLI y skills.sh no encuentran nada.
estructura de un repo publicable:
meu-repo-de-skills/
├── README.md
└── skills/
├── react-component-scaffold/
│ ├── SKILL.md # frontmatter + corpo (<500 linhas)
│ ├── scripts/ # scripts executáveis sob demanda
│ │ └── scaffold.sh
│ ├── references/ # docs longas carregadas só quando preciso
│ │ └── patterns.md
│ └── assets/ # templates, imagens
│ └── component.tpl
└── git-commit-style/
└── SKILL.md
Progressive disclosure en 3 niveles
Metadata (name + description)
~100 palabras, siempre en el contexto. Es el activador. Costo permanente: mantenlo conciso.
Cuerpo de SKILL.md (<500 líneas)
Se carga solo cuando se activa la skill. Las instrucciones propiamente dichas.
Recursos agrupados
scripts/, references/, assets/ — se leen bajo demanda, cuando el cuerpo los señala.
💡 Consejo sobre el repo
Un único repo puede alojar varias skills atómicas: así es como vercel-labs/skills e anthropics/skills funcionan. Quien instala elige el repo (owner/repo) y el CLI obtiene las skills de la carpeta skills/.
🔀 Versionar con git
Las skills viven en git y se instalan como symlinks, no copias. Esto lo cambia todo: cuando tú das git push y el usuario ejecuta npx skills update, tu nueva versión se propaga a todos. No controlas solo tu repo: controlas el comportamiento de quienes la instalaron.
Commit + push
La fuente de la verdad es git. Edita el SKILL.md, haz commit con un mensaje claro y haz push. Listo: la versión publicada cambió.
Symlink del lado del usuario
De forma predeterminada, la skill se enlaza simbólicamente desde el repo clonado. No hay una copia congelada: la instalación apunta a la fuente.
npx skills update
Un comando trae las últimas versiones de todas las skills instaladas. Eso es lo que mantiene vivo el ecosistema y lo que exige cuidado de tu parte.
✗ Versionado descuidado
- ✗Push directo a main sin probar el activador
- ✗Cambiar la description y perjudicar a quienes dependían de ella
- ✗Sin changelog, nadie sabe qué cambió
✓ Control de versiones responsable
- ✓Ejecutar evals antes del push
- ✓Cambios de activador documentados
- ✓CHANGELOG.md con cada release
💡 El poder del symlink
El symlink es la razón por la que las skills se actualizan gratis, pero también por la que un push defectuoso afecta a todo el mundo de inmediato. Trata la main del repo de skills como producción.
🌐 Aparecer en skills.sh
O skills.sh indexa repos públicos y muestra el install count como métrica social — la señal de descubrimiento y confianza. Pero las cuentas son duras: de las 39.366 skills del catálogo (5.075 repositorios fuente, 53,9M instalaciones en total), la distribución sigue una ley de potencia brutal.
Las 100 principales = 43,7% de todas las instalaciones
La concentración es extrema. find-skills por sí sola tiene 1.802.925 installs (vercel-labs). frontend-design 488.299 (anthropics), vercel-react-best-practices 443.261. Estar en la cima es raro — pero el install count sigue siendo tu mejor señal de descubrimiento.
La lección: no persigas el leaderboard. Resuelve bien un problema real, con naming y description claros, y la gente te encontrará dentro de tu nicho.
📊 Medir el triggering
La pregunta que distingue una skill amateur de una profesional: ¿la description se activa en los casos correctos? No adivinas: mides con evals de activación. Enumera consultas que deberían activarse, consultas que no deberían, y los casi aciertos engañosos.
eval de activación (ejemplo):
skill: react-component-scaffold should_trigger: - "cria um componente de card" - "preciso de uma nova tela de login em React" - "refatora esse JSX em componentes" should_not_trigger: - "qual a sintaxe de um for em Python?" - "explica o que é o virtual DOM" # near-miss: fala de React mas não pede componente # meça: % de acerto em cada lista
✓ Debería activarse
Los casos en los que la skill debe aparecer. Si no aparece aquí, tu description es demasiado vaga o tímida.
Fallar aquí = activación insuficiente (recall bajo).
✗ No debería activarse
Los casos en los que debe quedarse en silencio. Los near-misses (que tocan el tema, pero no cumplen el trigger) son los más reveladores.
Fallar aquí = activación incorrecta (precisión baja).
💡 El ciclo para afinar el disparador
Ejecuta los evals → observa dónde falló → ajusta solo la description (no el cuerpo) → vuelve a ejecutarlos. Los near-misses te indican exactamente qué palabras agregar o quitar. El triggering es el KPI que casi nadie mide y el que más determina si la skill es útil.
🛡️ Principio de no sorprender
Las skills se ejecutan con la confianza del usuario. El principio de oro: la skill no debe hacer nada que el usuario no esperaría al leer la description. Nada de borrar archivos, enviar datos al exterior o ejecutar comandos destructivos como efecto secundario silencioso.
✗ Sorpresa (rompe la confianza)
- ✗"da formato al código" y de paso hace
git push --force - ✗Script en scripts/ que envía telemetría oculta
- ✗
rm -rfoculto en un paso de «limpieza» - ✗Accede a secretos sin que el usuario lo pida
✓ Sin sorpresas (confiable)
- ✓Hace exactamente lo que promete la description
- ✓Las acciones destructivas requieren confirmación explícita
- ✓Principio de mínimo privilegio: solo accede a lo que necesita
- ✓Scripts auditables y transparentes
Por qué esto es existencial para el ecosistema
Como las skills se instalan mediante symlink y se actualizan con un comando, un repo malicioso o descuidado puede afectar a muchas personas de una sola vez. La reputación de todo skills.sh depende de que cada autor respete el principio de no sorprender. Audita tus propios resources como si fueras un usuario desconfiado que los está instalando.
♻️ El ciclo de vida
Publicar no es el final: es el comienzo del ciclo. La skill es un producto vivo: tú publica → observa instalaciones y comentarios → itera en la description y en el cuerpo → vuelve a publicar. Y repite. El catálogo de 53,9M instalaciones está formado por skills que iteraron.
Publicar
Repo con carpeta skills/, push a GitHub, indexación en skills.sh. La v1 ya está disponible.
Observar
Sigue el install count, los issues y cómo se comporta la skill en el uso real. Los datos te indican dónde falla el disparador y dónde el contenido confunde.
Iterar
Ajusta la description basándote en los near-misses reales, reduce el contenido y extrae los scripts repetidos. Haz commit, push y el ciclo vuelve a empezar.
💡 Dónde aprender más
Completaste las 5 rutas: panorama, calidad, anatomía, el ciclo de creación y los modelos mentales. El siguiente paso es publicar tu primera skill de verdad y seguir mejorándola. Encuentra más cursos, ejemplos y la comunidad en INEMA.CLUB.
✅ Resumen del módulo · Fin del curso
¡Terminaste el curso! 🎉
Cinco rutas, desde la visión del ecosistema hasta la publicación y la medición. Ahora te toca a ti: elige un workflow repetible de tu día a día, escribe tu primera skill, publícala e itera. Sigue aprendiendo en el portal.