Mantener tu skill

Publicar es el principio, no el final. Los skills necesitan actualizaciones a medida que evoluciona el runtime del agente, se acumula feedback de usuarios y la especificación SKILL.md añade nuevas funcionalidades.

Versionado

Sigue el versionado semántico:

Tipo de cambio	Incremento de versión	Ejemplo
Corregir un typo o aclarar redacción	Patch	`1.0.0` → `1.0.1`
Añadir nuevos ejemplos o comportamiento opcional	Minor	`1.0.0` → `1.1.0`
Reescribir instrucciones o cambiar el trigger	Major	`1.0.0` → `2.0.0`

Cuando subes una nueva versión a GitHub, el indexador del marketplace detecta el cambio de versión y vuelve a puntuar el skill actualizado automáticamente. No se necesita reenvío manual.

Subir actualizaciones

# Make your changes to SKILL.md
# Bump the version field in frontmatter
git add SKILL.md
git commit -m "fix: clarify trigger wording (1.0.1)"
git push

El marketplace se sincroniza con tu repo en 15 minutos tras un push a tu rama por defecto.

Validación en CI

Añade validación automática a tu workflow de GitHub Actions para detectar errores de esquema antes de que lleguen al marketplace:

# .github/workflows/validate-skills.yml
name: Validate Skills

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @hordago/skill-validator ./ --recursive

Esto ejecuta el mismo validador que usa el auto-scorer del marketplace, así que ves los problemas localmente antes de hacer push.

Deprecar un skill

Si has reemplazado un skill por uno mejor, deprécalo en lugar de borrarlo. Los usuarios que tengan el skill antiguo instalado reciben un aviso de migración.

---
name: old-skill
# ... other fields ...
deprecated: true
deprecated_by: "new-skill"
---

Sube la actualización a GitHub. El marketplace:

Quitará el skill de los resultados de búsqueda
Mostrará un aviso de deprecación en la página de detalle del skill
Notificará a los usuarios instalados para cambiar a new-skill

No borres el repositorio ni el fichero SKILL.md — el runtime necesita que el fichero siga presente para servir el aviso de deprecación a los usuarios existentes.

Responder al feedback de usuarios

Las valoraciones y comentarios de usuarios aparecen en tu dashboard del marketplace. Patrones comunes sobre los que merece la pena actuar:

“El trigger no dispara” — Tu descripción de trigger puede ser demasiado estrecha. Amplíala y sube un patch.
“Instrucciones poco claras” — Añade ejemplos o pasos numerados al cuerpo.
“Conflicto con el skill X” — Añade una nota al trigger explicando cuándo NO usar tu skill.

Archivar

Si ya no mantienes un skill y no existe un reemplazo, archívalo:

---
name: my-skill
deprecated: true
---

Sin el campo deprecated_by, el skill se marca como archivado en lugar de redirigido. Los skills archivados se ocultan de las búsquedas, pero siguen siendo accesibles por URL directa.