🧭 La lista de verificación para decidir
Antes de abrir un editor, responde cuatro preguntas. Si la mayoría son "no", no necesitas una skill: necesitas otra herramienta o ninguna. Este es el filtro que separa una skill útil de la contaminación del catálogo.
¿Vale la pena crearla?
- 1.Es un flujo de trabajo repetible, ¿no es un one-off?
- 2.Se carga conocimiento del contexto que el modelo no tiene por defecto?
- 3.El output es verificable (¿se puede saber si quedó bien)?
- 4.Es una tarea multi-step, ¿no es una query de 1 paso?
≥2 sí → vale la pena empaquetar. 0–1 sí → probablemente es sobreingeniería.
CLAUDE.md
Regla/preferencia que siempre aplica en el proyecto. Consume contexto todo el tiempo.
MCP
Conectarse a un servicio externo (API, DB, navegador). Es una conexión, no conocimiento.
Subagente
Trabajo aislado/paralelo con contexto propio. Es delegación.
Skill ✦
Conocimiento/proceso que se activa BAJO DEMANDA mediante el disparador. Este es nuestro caso.
📁 Estructurar el repo
Decidiste que es una skill. Ahora el repo debe seguir la convención que entienden el CLI y skills.sh: una carpeta skills/ en la raíz, y cada skill con su SKILL.md más resources opcionales. Un repo puede alojar varias skills atómicas.
template de estructura de repo:
meu-repo-de-skills/
├── README.md
├── LICENSE
├── CHANGELOG.md
└── skills/
└── minha-primeira-skill/
├── SKILL.md # frontmatter YAML + corpo (<500 linhas)
├── scripts/ # executáveis sob demanda
│ └── run.sh
├── references/ # docs longas, lidas só quando preciso
│ └── deep-dive.md
└── assets/ # templates, imagens
└── template.tpl
SKILL.md — el frontmatter es el activador:
--- name: minha-primeira-skill description: QUÉ hace Y CUÁNDO usarla. Actívala cuando el usuario pida X, mencione Y o necesite Z. Sé un poco insistente: el modelo tiende a activarla menos de lo que debería. --- # Mi primera Skill Cuerpo en Markdown. Explica el PORQUÉ, no solo los pasos. Remite a references/ y scripts/ cuando necesites más detalles.
💡 El frontmatter mínimo
Solo name e description son obligatorios. La description (~100 palabras) permanece siempre en el contexto: es el único nivel que el modelo siempre ve, así que ahí está el disparador. Di qué hace Y cuándo usarlo.
🔀 Versionar con git
Git es la fuente de verdad de la skill. Las skills se instalan como symlinks para el repo clonado, no copias congeladas. Un git push el tuyo, más uno npx skills update de quien la instaló, propaga la nueva versión a todos. Trata la main como producción.
el flujo de git de un release:
git checkout -b ajuste-gatilho # edita skills/minha-primeira-skill/SKILL.md git add skills/minha-primeira-skill/SKILL.md CHANGELOG.md git commit -m "fix(trigger): cobre o near-miss de refactor" git push origin ajuste-gatilho # abre PR, roda evals de gatilho, merge na main → publicado
✗ 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ó
✓ Responsable
- ✓Branch + PR + evals antes del merge
- ✓Cambios de activador documentados
- ✓CHANGELOG.md con cada release
📟 npx skills add / update
Los comandos que hacen que la skill exista en la máquina. Para probarla localmente antes de publicarla, la instalas desde la ruta del directorio; después de publicarla en GitHub, la instalas desde owner/repo. E update obtiene las últimas versiones.
comandos esenciales:
# instalar do diretório local (teste antes de publicar) npx skills add ./skills/minha-primeira-skill # instalar de um repo público no GitHub npx skills add owner/meu-repo-de-skills # puxar a última versão de tudo que está instalado npx skills update
El ciclo de prueba local
Antes de publicar: ejecuta npx skills add ./..., abre una sesión con 2-3 prompts realistas, compara el comportamiento con skill vs. baseline (sin skill). ¿Ajustaste el SKILL.md? Ejecuta npx skills update y vuelve a probar. Publica solo cuando el activador y el resultado te convenzan.
💡 Symlink = iteración gratis
Como la instalación es un symlink a la carpeta, editar el SKILL.md en su ubicación ya se refleja en la próxima sesión, sin reinstalar. Esto hace que el ciclo de ajustes sea rápido. El mismo symlink explica por qué, después de publicar, un push incorrecto afecta a todo el mundo de inmediato.
🌐 Publicar y aparecer en skills.sh
Publicar es dejar el repo público en GitHub con la carpeta skills/ con la convención correcta. skills.sh indexa repos públicos y expone el install count. La cronología desde cero hasta la publicación:
Crea el repositorio público en GitHub
Con README, LICENSE y la carpeta skills/ en la raíz. Nombre claro del repo: pasa a formar parte del owner/repo que la gente instala.
Push de la v1 probada
SKILL.md con frontmatter validado, resources en su lugar y evals de activación aprobadas. git push en main.
Indexación en skills.sh
El directorio recorre repos públicos y tu skill aparece en los resultados de búsqueda. name e description son lo que la gente lee en la vitrina.
Las instalaciones empiezan a contar
Cada npx skills add owner/repo aumenta el install count — tu señal social de descubrimiento. Recuerda la ley de potencia: solo el 0,3% supera los 100k.
El naming y la description venden
En el escaparate de skills.sh, la persona decide instalar leyendo solo name + description. Un nombre específico (git-commit-conventional) y una description que dice qué hace y cuándo supera a un nombre genérico (git-helper) siempre. Es el mismo texto que sirve de disparador: dos pájaros de un tiro.
⏱️ La cronología completa, desde cero hasta publicar
Reúne todo en una secuencia que puedes seguir hoy. Siete pasos, desde la decisión hasta que install count esté en marcha:
Decidir — responde las 4 preguntas del checklist y sigue el árbol skill/CLAUDE.md/MCP/subagente.
Estructurar — crea skills/nome/SKILL.md con frontmatter + cuerpo conciso.
Probar en local — npx skills add ./... y compara con-skill vs. baseline en prompts reales.
Ajustar el disparador — ejecuta evals should-trigger / should-not-trigger, ajusta la description.
Versionar — commit, CHANGELOG, branch + PR. git push en main = publicado.
Publicar — repo público, indexación en skills.sh, aparece en la búsqueda.
Medir — la cantidad de instalaciones y el feedback empiezan a fluir. Entra el ciclo de vida (próximo módulo).
💡 Puente al 5.5
Publicar la primera skill es el paso 6. El 5.5 cierra el curso con lo que viene después a escala: skills internas, seguridad, implementación en equipo y cómo mantener las skills vigentes sin que se vuelvan un caos.
✅ Resumen del módulo
Próximo:
Módulo 5.5 — 🚀 Consejos avanzados: gobernanza, seguridad y escala. Skills internas, evitar sorpresas, rollout en equipo y medir la adopción. Cierra el curso.