JMBargueno/skanvil

Que fait skanvil ?

Objectif

Modifier les bibliothèques de compétences via le CLI skanvil, de sorte que les dossiers de compétences, le frontmatter SKILL.md, l'index README et les conventions de la bibliothèque restent cohérents et que la validation reste verte.

Quand activer cette compétence

• Le dépôt contient un .skanvilrc.json, un dossier skills/ de fichiers SKILL.md, ou skanvil dans son package.json.
• L'utilisateur demande d'ajouter, écrire, renommer, déplacer, retitrer, redécrire, supprimer, lister, valider ou indexer des compétences.
• skanvil validate, npm test ou CI échoue avec des diagnostics skanvil.
• L'utilisateur souhaite que les compétences d'une bibliothèque soient disponibles pour Claude Code, GitHub Copilot ou Codex dans un autre projet.

Instructions

1. S'orienter

1. Lisez .skanvilrc.json. Il définit les catégories (id, préfixe de dossier prefix, titre README title, aliases), les sections requises, les espaces réservés et les sévérités des règles. Un fichier manquant signifie la présélection par défaut : front-, back-, transversal sans préfixe (par défaut) et _internal.
2. Exécutez npx skanvil list --json pour voir chaque compétence avec sa catégorie, sa présence dans le README et sa validité.
3. Exécutez npx skanvil validate --json avant toute modification, afin de connaître les problèmes déjà existants.

2. Règles d'or

• Ne renommez, ne déplacez et ne supprimez jamais les dossiers de compétences à la main, et ne modifiez jamais l'index README à la main. Utilisez skanvil edit, qui maintient la synchronisation du dossier, du name dans le frontmatter, de l'en-tête # et de l'entrée README, et annule en cas d'échec.
• Ne créez jamais de dossiers de compétences à la main. Utilisez skanvil add, qui applique le préfixe de catégorie, le modèle, les métadonnées du frontmatter et l'entrée README.
• Passez toujours toutes les options dans les shells non interactifs. add nécessite --type, --name et --description. edit --remove nécessite --yes. Sinon, la commande demande une interaction, ou échoue sans TTY.
• N'exécutez jamais skanvil sans arguments ou skanvil wizard. Ils ouvrent un menu interactif destiné aux humains. Utilisez les commandes explicites ci-dessous. Si l'utilisateur préfère les menus, suggérez-lui d'exécuter npx skanvil lui-même.
• Ajoutez --json chaque fois que vous devez analyser la sortie. Les données vont vers stdout ; les avertissements et erreurs vont vers stderr.
• Exécutez npx skanvil validate après chaque modification et terminez sans erreur. Le code de sortie 1 signifie des erreurs, ou des avertissements lorsque --strict est utilisé.
• Préfixez chaque commande avec npx sauf si skanvil est dans le PATH. Utilisez -C <path> pour cibler une bibliothèque dans un autre dossier.

3. Tâches courantes

Créer une compétence, puis écrire son contenu.

npx skanvil add --type <catégorie> --name "<nom court>" \
  --description "<ce qu'elle fait>. Utiliser quand <situations déclencheurs>."

Modifiez ensuite skills/<préfixe><nom>/SKILL.md :

• Remplissez chaque section requise avec un contenu concret et actionnable.
• Remplacez toutes les phrases génériques du modèle. Tant que ce n'est pas fait, validate signale un avertissement template-unchanged, et validate --strict (le npm test de la bibliothèque) échoue.
• Déplacez le contenu volumineux dans references/, et ne créez de liens que vers des fichiers existants (broken-references).

Utilisez --no-scripts, --no-assets ou --no-references lorsque ces dossiers resteraient vides. Utilisez --template <nom> pour un modèle personnalisé dans .skanvil/templates/.

Renommer ou déplacer une compétence.

npx skanvil edit <compétence> --rename <nouveau-nom>          # le préfixe est réappliqué automatiquement
npx skanvil edit <compétence> --type <autre-catégorie>      # nouveau préfixe, section README, métadonnées
npx skanvil edit <compétence> --title "<Titre>" --description "<texte>"

--rename prend le nom de base : edit front-a --rename b donne front-b.

Supprimer une compétence. Confirmez d'abord avec l'utilisateur ; cette opération est permanente.

npx skanvil edit <compétence> --remove --yes

Corriger les erreurs de validation.

1. Exécutez npx skanvil doctor --fix. Il répare les entrées README, les discordances de name, les tabulations dans le frontmatter et convertit tools en allowed-tools.
2. Corrigez ce qui reste en éditant SKILL.md. Utilisez le tableau de diagnostic ci-dessous.
3. Exécutez à nouveau npx skanvil validate.

Reconstruire l'index README après avoir modifié les titres de catégorie dans .skanvilrc.json :

npx skanvil index          # réécrit les sections de l'index
npx skanvil index --check  # vérification uniquement (CI)

Installer les compétences dans un projet.

npx skanvil sync <dossier-projet> -C <dossier-bibliothèque> --target claude,copilot --dry-run   # aperçu
npx skanvil sync <dossier-projet> -C <dossier-bibliothèque> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # paquet installé

Cibles :

• claude s'installe dans .claude/skills ;
• copilot s'installe dans .github/skills ;
• agents et codex s'installent dans .agents/skills.
• Un chemin personnalisé doit être un dossier dans le projet.
• --global (sans dossier de projet) installe dans ~/.claude/skills, ~/.copilot/skills ou ~/.agents/skills de l'utilisateur. Ne l'utilisez que lorsque l'utilisateur demande des compétences disponibles dans tous les projets.

Comportement de sync :

• Il n'écrase jamais les dossiers qu'il n'a pas installés.
• Il supprime les compétences qui ont été retirées de la bibliothèque.
• Il ignore les compétences avec des erreurs de validation sauf si --force est donné.
• Il ne publie jamais les compétences _internal.

Ajouter ou modifier des catégories. Modifiez categories dans .skanvilrc.json :

• exactement une catégorie a "default": true et pas de préfixe ;
• chaque autre catégorie a un préfixe qui est _ ou en kebab-case se terminant par - ;
• aucun préfixe ne peut commencer par un autre préfixe.

Déplacez ensuite les compétences existantes avec edit --type, et exécutez skanvil index.

4. Rédiger un bon contenu de compétence

• description indique ce que fait la compétence et quand l'utiliser, avec les mots-clés déclencheurs qu'un agent verrait. Elle doit faire au maximum 1024 caractères.
• name est égal au nom du dossier : lettres minuscules, chiffres et traits d'union simples, au maximum 64 caractères.
• Corps : gardez SKILL.md sous 500 lignes. Rédigez les instructions sous forme d'étapes numérotées et vérifiables, et placez les exemples, cas particuliers et longues listes de contrôle dans references/ (un niveau de profondeur).
• Espaces réservés : ne laissez jamais de texte de remplissage. Toute entrée de validation.placeholders (marqueurs à faire, texte latin factice, notes "à décider") échoue à la validation.
• metadata : valeurs sous forme de chaînes uniquement, donc mettez les nombres entre guillemets, comme dans version: "1.0".
• allowed-tools : une chaîne séparée par des espaces, pas une liste.

5. Diagnostic → correction

Règle	Correction
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix, ou edit --rename si le nom du dossier est erroné
frontmatter-tabs, tools-field	doctor --fix
frontmatter	Réparer le YAML entre les lignes --- (mettre entre guillemets les valeurs contenant : ou #).
required-sections	Ajouter la ## Section manquante listée dans validation.requiredSections.
placeholders	Remplacer le texte d'espace réservé par un contenu réel.
description-length, max-lines	Raccourcir ; déplacer les détails dans references/.
metadata-format	Mettre entre guillemets les valeurs non-chaîne.
duplicate-name	Deux dossiers partagent un name : renommer l'un avec edit --rename.
broken-references	Créer le fichier référencé, ou corriger le lien (les chemins sont relatifs à la compétence).
template-unchanged	Réécrire les phrases génériques du modèle avec des instructions spécifiques à la compétence.

Voir references/REFERENCE.md pour toutes les options de commande, le schéma de configuration et les formes de sortie JSON.

Format de sortie

Rapportez à l'utilisateur :

• les commandes skanvil que vous avez exécutées ;
• les compétences créées, modifiées ou supprimées, avec leurs noms de dossier ;
• le résultat final de skanvil validate (erreurs et avertissements), et tout ce qui reste à sa décision.

Critères de qualité

• Chaque modification structurelle est passée par skanvil add ou skanvil edit. Il n'y a pas de renommages de dossiers ou d'éditions d'index README faits à la main.
• npx skanvil validate ne signale aucune erreur, et npx skanvil index --check réussit.
• Les compétences nouvelles ou modifiées ont des descriptions spécifiques avec des déclencheurs, et aucun contenu de modèle ou espace réservé.
• Les suppressions et les synchronisations dans d'autres projets ont été confirmées avec l'utilisateur.