¿Qué hace skillctl?
Manual operativo para gestionar Skills de Agentes con la CLI skillctl. Ejecuta comandos reales; no simules salidas ni copies archivos SKILL.md entre directorios de agentes manualmente.
Reglas de oro
- Un único almacén canónico — las skills residen en
~/.skillctl/skills/<nombre>/; los agentes obtienen enlaces simbólicos mediantesync. - Compromete manifiesto + lock — versiona
agent-skills.jsonyagent-skills.locken git para reproducibilidad en equipo. - Solo especificadores portables — usa
file:./<ruta>,local:imported/<nombre>,github:,npm:oskills.sh/; nunca comprometas rutas absolutas del directorio home. - Instala antes de sincronizar —
installmaterializa el almacén;syncsolo reenlaza agentes. - Verifica tras cambios — ejecuta
skillctl doctor(yskillctl auditen CI). - Prefiere importar antes que copiar manualmente — usa
import from-projectoimport from-npxen lugar de duplicar carpetas de skills.
Árbol de decisión
| Situación | Comando |
|---|---|
| Nuevo proyecto, sin manifiesto | skillctl init o skillctl init --with-skill |
| Añadir una skill remota o local | skillctl add <especificador> luego skillctl install |
Skills ya existentes en .claude/skills, .codex/skills, etc. | skillctl import from-project |
Migrar desde npx skills | skillctl import from-npx |
| Reenlazar solo (lock sin cambios) | skillctl sync |
| Recuperar desde origen | skillctl update o skillctl update <nombre> |
| Instalación reproducible en CI | skillctl install --frozen luego skillctl audit --strict |
| Rutas no portables en el lock | skillctl install para reescribir; revisa las advertencias de skillctl doctor |
Recetas rápidas
# Inicialización
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# Skill local del proyecto
skillctl add file:./my-skill
skillctl install
skillctl sync
# Importar directorios de agentes existentes
skillctl import from-project --dry-run
skillctl import from-project
# Inspección
skillctl list
skillctl doctor
skillctl audit --json
Se espera que tras add file:./my-skill + install: el especificador del manifiesto sea file:./my-skill, y el canonicalPath del lock sea algo como ~/.skillctl/skills/my-skill.
Portabilidad (0.3.1+)
- Portables:
file:./rel,local:imported/<nombre>, especificadores remotos,canonicalPath: ~/.skillctl/skills/<nombre>. - No portables: rutas absolutas
file:/Users/...,local:/abs/path,canonicalPathabsoluto de otra máquina. - Si
doctoradvierte sobre rutas no portables, ejecutaskillctl installpara reescribir el lock a partir del manifiesto.
Modos de fallo
| Síntoma | Acción |
|---|---|
canonical path missing | skillctl install |
| Discrepancia de integridad | skillctl update <nombre> o skillctl install |
| El enlace simbólico falla (Windows) | doctor lo señala; configura defaultMode: copy |
| Ningún agente enlazado | skillctl sync; habilita agentes en ~/.skillctl/config.json |
Frozen install failed | El almacén está desincronizado; ejecuta install sin --frozen |
Referencias
- commands.md — hoja de referencia completa de comandos
- specifiers.md — gramática de especificadores
- manifest-lock.md — semántica del manifiesto y lock
- workflows.md — onboarding de equipos, migración, CI
- troubleshooting.md — doctor, Windows, coexistencia