skill-doctor

Que fait skill-doctor ?

Diagnostiquez une bibliothèque de compétences. Trouvez les compétences dont les descriptions entrent en concurrence pour les mêmes prompts, puis corrigez le routage.

Quand l'exécuter

• Vous avez installé de nombreuses compétences et "la mauvaise se déclenche sans cesse"
• Avant de publier un pack de compétences (pour attraper les collisions que les réviseurs rencontreront)
• Après avoir ajouté une compétence (entre-t-elle en collision avec une existante ?)
• Contrôle de santé périodique sur une bibliothèque en pleine croissance

Entrée

Pointez le moteur vers SOIT :

• Un répertoire de compétences (<root>/<name>/SKILL.md), soit
• Un manifest.json de Claude Code (skills-plugin/.../manifest.json)

Comment exécuter

Le moteur se trouve dans scripts/ à côté de ce fichier. Zéro dépendances (Python 3.8+ bibliothèque standard).

# Depuis le répertoire contenant ce SKILL.md :
python3 -m scripts <chemin-vers-competences-ou-manifest>            # Rapport Markdown
python3 -m scripts <chemin> --format json --out report.json # Sortie machine
python3 -m scripts <chemin> --fail-on critical               # Porte CI (code de sortie 1)

Options courantes :

• --merge-at 0.55 — score de collision déclenchant une recommandation FUSION
• --disambig-at 0.30 — score déclenchant une recommandation DÉSAMBIGUISATION
• --vague-threshold 0.5 — signaler les descriptions plus vagues que ce seuil
• --top 12 — nombre de collisions principales à lister
• --format md|json|both

Ce qu'il détecte (codes de problème)

Code	Gravité	Signification
DUPLICATE_TRIGGER	🔴	Même phrase déclencheur revendiquée par 2+ compétences (principale cause de mauvais routage)
DUPLICATE_NAME	🔴	Deux compétences partagent un nom
MISSING_DESCRIPTION	🔴	La compétence ne peut jamais se déclencher de manière fiable
HIGH_OVERLAP	🔴/🟠	Deux descriptions sont sémantiquement trop proches
VAGUE_DESCRIPTION	🟠	Remplie de mots vides, pas de "utiliser quand", pas de déclencheurs
NAME_DIR_MISMATCH	🟠	nom ≠ répertoire (casse la spécification)
BAD_NAME_FORMAT	🟠	le nom enfreint les règles de minuscules/traits d'union
DESC_TOO_SHORT / DESC_TOO_LONG	🟠/🟡	En dehors de 40–1024 caractères
NO_BOUNDARY	🟡	Pas de renvoi croisé "Pour X, voir "
BODY_TOO_LONG	🔵	Corps de SKILL.md > 500 lignes

Comment le scoring fonctionne (une ligne)

collision = 0.50·cosinus(TF-IDF des descriptions)
          + 0.35·jaccard(phrases déclencheurs)
          + 0.15·jaccard(mots-clés du domaine)

Bandes : <0.22 FAIBLE · 0.22 MOYEN · 0.38 ÉLEVÉ · 0.55 CRITIQUE. Voir references/scoring.md pour la justification complète.

Flux de travail pour l'agent

1. Exécutez le moteur sur le chemin des compétences de l'utilisateur → lisez le rapport Markdown.
2. Résumez le score de santé, les pires clusters et les déclencheurs en double.
3. Pour chaque recommandation principale, proposez la modification concrète :
   • MERGE (FUSION) → rédigez une description combinée, suggérez le nom survivant.
   • ABSORB (ABSORPTION) → nommez la compétence à supprimer et où ses déclencheurs sont déplacés.
   • DISAMBIGUATE (DÉSAMBIGUISER) → écrivez les deux lignes de démarcation miroir ("Pour X, voir Y.").
4. Proposez d'appliquer les réécritures de description (éditez chaque frontmatter de SKILL.md).
5. Réexécutez pour confirmer que le score de santé s'est amélioré.

Sortie

• Un rapport Markdown : score de santé, principales collisions, clusters confusables, tableau des déclencheurs en double, recommandations, liste complète des problèmes, heatmap ASCII.
• JSON optionnel (--format json) pour les portes CI ou d'autres outils.

Règles

• Le moteur est en lecture seule — il ne modifie jamais les compétences. Les réécritures sont appliquées par l'agent (vous) uniquement après approbation de l'utilisateur.
• Ne supprimez jamais une compétence sans confirmation explicite.
• Lors de la réécriture des descriptions, préservez chaque phrase déclencheur réelle sur laquelle l'utilisateur compte ; déplacez/désambiguïsez-les uniquement — ne les supprimez pas.

Voir references/methodology.md pour l'algorithme et references/issue-catalog.md pour savoir comment corriger chaque type de problème.