Que fait skillctl ?
Manuel opérationnel pour gérer les compétences d'agents avec l'interface en ligne de commande skillctl. Exécutez de vraies commandes ; ne simulez pas la sortie et ne copiez pas manuellement les fichiers SKILL.md entre les répertoires d'agents.
Règles d'or
- Un seul dépôt canonique — les compétences résident dans
~/.skillctl/skills/<nom>/; les agents reçoivent des liens symboliques viasync. - Versionnez le manifeste + le verrou — suivez
agent-skills.jsonetagent-skills.lockdans git pour la reproductibilité en équipe. - Spécificateurs portables uniquement — utilisez
file:./<chemin>,local:importé/<nom>,github:,npm:, ouskills.sh/; ne validez jamais de chemins absolus vers le répertoire personnel. - Installez avant de synchroniser —
installmatérialise le dépôt ;syncne fait que re-lier les agents. - Vérifiez après les modifications — exécutez
skillctl doctor(etskillctl auditen CI). - Privilégiez l'importation à la copie manuelle — utilisez
import from-projectouimport from-npxau lieu de dupliquer les dossiers de compétences.
Arbre de décision
| Situation | Commande |
|---|---|
| Nouveau projet, pas de manifeste | skillctl init ou skillctl init --with-skill |
| Ajouter une compétence distante ou locale | skillctl add <spécificateur> puis skillctl install |
Compétences déjà dans .claude/skills, .codex/skills, etc. | skillctl import from-project |
Migration depuis npx skills | skillctl import from-npx |
| Re-lier uniquement (verrou inchangé) | skillctl sync |
| Re-télécharger depuis la source | skillctl update ou skillctl update <nom> |
| Installation reproductible en CI | skillctl install --frozen puis skillctl audit --strict |
| Chemins non portables dans le verrou | skillctl install pour réécrire ; vérifiez les avertissements de skillctl doctor |
Recettes rapides
# Amorcer
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# Compétence locale au projet
skillctl add file:./ma-competence
skillctl install
skillctl sync
# Importer des répertoires agents existants
skillctl import from-project --dry-run
skillctl import from-project
# Inspecter
skillctl list
skillctl doctor
skillctl audit --json
Attendu après add file:./ma-competence + install : spécificateur du manifeste file:./ma-competence, canonicalPath du verrou comme ~/.skillctl/skills/ma-competence.
Portabilité (0.3.1+)
- Portable :
file:./rel,local:importé/<nom>, spécificateurs distants,canonicalPath: ~/.skillctl/skills/<nom>. - Non portable :
file:/Users/...absolu,local:/chemin/absoluabsolu,canonicalPathabsolu d'une autre machine. - Si
doctorémet des avertissements concernant des chemins non portables, exécutezskillctl installpour réécrire le verrou à partir du manifeste.
Modes de défaillance
| Symptôme | Action |
|---|---|
canonical path missing | skillctl install |
| Incohérence d'intégrité | skillctl update <nom> ou skillctl install |
| Échec du lien symbolique (Windows) | doctor le signale ; configurer defaultMode: copy |
| Aucun agent lié | skillctl sync ; activer les agents dans ~/.skillctl/config.json |
Frozen install failed | Dépôt désynchronisé ; exécuter install sans --frozen |
Références
- commands.md — aide-mémoire complet des commandes
- specifiers.md — grammaire des spécificateurs
- manifest-lock.md — sémantique du manifeste et du verrou
- workflows.md — intégration d'équipe, migration, CI
- troubleshooting.md — doctor, Windows, coexistence