🔒 Skills internas (privadas)
No todas las skills deben ir al catálogo público. El conocimiento propietario, las convenciones internas y los flujos de tu equipo viven como skills internas — marcadas con metadata.internal y se instalan solo con la flag INSTALL_INTERNAL_SKILLS. Quedan fuera de skills.sh y del conteo público de instalaciones.
marcar una skill como interna:
--- name: deploy-runbook-acme description: Runbook interno de deploy da Acme. Acione em deploy, rollback ou incidente em produção. metadata: internal: true --- # só instala com a flag explícita: INSTALL_INTERNAL_SKILLS=1 npx skills add acme/skills-privadas
Buenas candidatas para uso interno
- ›Runbooks de deploy/incidentes del equipo
- ›Convenciones de código propias
- ›Integraciones con sistemas internos
Por qué separarlo del público
- ›Evita filtrar contexto sensible en el catálogo
- ›No llenes skills.sh de ruido solo tuyo
- ›Instala solo con consentimiento explícito, nunca por accidente
🛡️ Sin sorpresas y seguridad
El principio de oro: la skill nunca hace lo que la description no promete. Como las skills se instalan mediante symlink y se actualizan con un comando, un repo malicioso o descuidado contamina a muchas personas de una vez. La confianza de todo el ecosistema depende de ello.
✗ Sorpresa / riesgo
- ✗Script que exfiltra datos o envía telemetría oculta
- ✗
rm -rfogit push --forceoculto en un paso - ✗Accede a secretos/credenciales sin que el usuario lo pida
- ✗Descarga y ejecuta código de una fuente externa en tiempo de ejecución
✓ Confiable
- ✓Hace exactamente lo que dice la description
- ✓Una acción destructiva requiere confirmación explícita
- ✓Principio de mínimo privilegio: accede solo a lo necesario
- ✓Scripts auditables, sin dependencias oscuras
💡 Audita como quien instala
Antes de publicar, lee tus propios scripts/ con los ojos de un usuario desconfiado. Sin malware, sin exfiltración, sin efectos secundarios inesperados. Una ruptura de confianza arruina la reputación de todo el repo — y afecta a skills.sh.
🏷️ Estrategia de versionado
A escala, "push en main" sin estrategia se convierte en inestabilidad. Como el symlink propaga cada cambio de inmediato, necesitas una disciplina de versionado que separe lo seguro de lo arriesgado.
Qué exige cada tipo de cambio
Corrección de texto, aclaración del cuerpo. Bajo riesgo: puedes aplicarla directamente, con una evaluación rápida.
Nuevo comportamiento aditivo. Sigue siendo compatible: ejecuta las evals completas antes.
Cambio del activador o del comportamiento esperado. Perjudica a quienes dependían de ella — comunícalo y documéntalo en el CHANGELOG.
etiqueta la release y mantén un CHANGELOG:
## [1.2.0] - 2026-06 ### Changed - description agora cobre o near-miss de "refatorar" (minor) ### Fixed - corpo: removido MUST que causava overfit em projetos sem testes git tag v1.2.0 && git push --tags
La regla del cambio de activador
Modificar la description es el cambio más peligroso que existe: altera cuándo la skill se activa para todos los que la instalaron. Trata toda edición de description como potencial major hasta que los evals demuestren lo contrario.
👥 Despliegue en equipo
Distribuir skills para un equipo es diferente de publicar para todo el mundo. Quieres consistencia (que todos tengan el mismo conjunto), control de versiones y una vía de adopción que no tome a nadie por sorpresa.
Un repo curado del equipo
Centraliza las skills aprobadas en un solo repo, público o interno. Se convierte en la fuente única: nadie instala skills aleatorias directamente en el proyecto compartido.
Haz una prueba piloto antes del despliegue general
Un subgrupo instala, usa durante una semana y envía comentarios. Ajusta el activador y el contenido con comentarios reales antes de ampliarlo a todo el mundo.
Comunica cada actualización antes de publicarla
Cómo npx skills update propaga todo; avisa al equipo antes de hacer cambios en los activadores. Un registro de cambios en un canal compartido evita el "¿por qué la skill empezó a activarse con esto?".
💡 Consejo profesional para la incorporación
Documenta el conjunto de skills del equipo en el README del repo curado, con un npx skills add por línea. Quien se incorpora sigue la lista y es productivo desde el primer día, con el mismo comportamiento de agente que todos los demás.
📈 Medir la adopción
Una skill a escala es un producto, y los productos se miden. Dos métricas que importan: install count (cuántos lo adoptaron) y triggering (si se activa en los casos correctos). Una cifra alta y la otra baja cuentan historias muy distintas.
Número de instalaciones
Mide el descubrimiento y la adopción. Un valor bajo con buen triggering = un problema de nombre/descripción o de nicho, no de calidad. No persigas el leaderboard.
Triggering
Mide si la skill aparece en el momento adecuado. Muchas instalaciones + triggering deficiente es el peor escenario: mucha gente frustrada. Mídelo con evals should-trigger / should-not-trigger / near-miss.
♻️ Mantener skills actualizadas a escala
Una skill es fácil de mantener. Veinte skills se convierten en un portafolio, y un portafolio sin mantenimiento se deteriora. Los pro tips para mantener decenas de skills útiles sin caer en el caos:
✗ Portafolio que se deteriora
- ✗Skills duplicadas con activadores que se superponen
- ✗Ningún eval: los errores pasan desapercibidos
- ✗Skills muertas que nadie usa y que contaminan las búsquedas
- ✗Cuerpos que con el tiempo crecieron hasta 800 líneas
✓ Portafolio vivo
- ✓Cada skill atómica, activadores sin superposición
- ✓La suite de evals se ejecuta en CI en cada push
- ✓Revisión periódica: retira lo que no se activa
- ✓Cuerpo conciso; los detalles van en references/
Consejos profesionales finales
- ★Evals en CI: ejecuta should-trigger / should-not-trigger automáticamente en cada PR: detecta pronto las regresiones del trigger.
- ★Audita los solapamientos: dos skills que se activan con el mismo prompt compiten y confunden. Fúndelas o diferencia los activadores.
- ★Retira sin piedad: una skill confiable sin crecimiento en las instalaciones y con una activación deficiente solo genera ruido. Despréciala en el CHANGELOG y elimínala.
- ★Manténlo conciso: en cada release, pregunta qué se puede recortar. Un cuerpo de <500 líneas no es una meta, es higiene.
💡 El cierre
Recorriste las 5 rutas: panorama del ecosistema, calidad y las mejores, anatomía, el ciclo de creación y los modelos mentales para decidir, publicar y escalar. A partir de aquí, toca practicar: elige un workflow repetible, escríbelo, publícalo, mide los resultados e itera.
✅ Resumen del módulo
Próximo:
Módulo 5.6 — Reglas 2026: grados de libertad, límites de la descripción, hooks en la skill, el corte de 5.000 tokens y la lista de verificación de las 10 reglas con el validador.