shimo4228/skill-stocktake

skill-stocktake — Audit de qualité des compétences

Évaluer les compétences installées de manière holistique, toutes dans un seul contexte, et attribuer à chacune un verdict : Conserver / Améliorer / Mettre à jour / Retirer / Fusionner. Ce skill ne fait PAS l'amélioration — une fois le verdict rendu, il passe la main à skill-creator (le moteur d'amélioration). Cette frontière est le point clé : stocktake est le contrôle qualité, skill-creator est le réparateur.

Note de conception : l'ancienne version utilisait des scripts de scan et divisait l'évaluation en lots d'environ 20 compétences par sous-agent. Avec un contexte de 1M, cela est non seulement inutile mais nuisible — le lotissement empêche chaque sous-agent de voir les compétences des autres lots, ce qui fait manquer les chevauchements entre compétences. Désormais, on énumère avec Glob et on lit chaque compétence dans un seul contexte. La détection des chevauchements dépend de cette vue unique.

Modes ($ARGUMENTS)

Argument	Comportement
aucun / full	Lire et évaluer chaque compétence (par défaut)
changed	Réévaluer uniquement les compétences dont SKILL.md a une mtime plus récente que evaluated_at dans results.json ; reporter les verdicts des autres depuis le registre

changed détecte les modifications en ligne (sans script) :

find ~/.claude/skills -name SKILL.md -newermt "$(jq -r .evaluated_at ~/.claude/skills/skill-stocktake/results.json)"

Phase 1 — Inventaire

Énumérer les fichiers de définition des compétences avec Glob (aucun script nécessaire) :

• ~/.claude/skills/*/SKILL.md
• ~/.claude/skills/learned/*.md
• si le répertoire courant contient .claude/skills/, aussi {cwd}/.claude/skills/*/SKILL.md (compétences de projet)

Comme Glob cible uniquement SKILL.md / learned/*.md, les fichiers markdown de dépendances sous .venv ou .pytest_cache sont exclus structurellement (aucun élagage requis). Le bruit que l'ancien find -name "*.md" pouvait introduire ne se produit pas.

Compteurs d'utilisation : lire ~/.claude/metrics/skill-usage.jsonl en ligne (le hook PostToolUse log-skill-usage.sh y ajoute des lignes — une couche de mesure indépendante) et compter les événements par compétence sur 7 / 30 / 90 jours. Chaque ligne est au format JSON {ts,event,skill,path,project} ; compter à la fois les événements invoke et read. Agréger avec une commande python3/jq jetable plutôt qu'un comptage manuel — le journal grandit avec le temps et le comptage manuel gaspille un tour d'outil par invocation.

• Si le journal est absent ou que son premier événement date de moins de 90 jours, afficher l'utilisation comme — (non mesurée). Ne jamais l'afficher comme 0 — non mesuré et inutilisé sont des faits différents.

Indiquer d'emblée le résultat du scan : quels chemins ont été scannés, combien de compétences trouvées, et si l'utilisation est mesurable.

Phase 2 — Évaluation (entièrement en ligne, holistique)

Lire le corps de chaque compétence cible et les évaluer une par une tout en voyant l'ensemble complet. Liste de contrôle :

• Chevauchement de contenu avec d'autres compétences (une séparation orchestrateur/sous-compétence documentée n'est PAS un chevauchement — par exemple paper-ecosystem → ses reviewers, citation-sync → release-doi/wikidata. Distinguer la stratification intentionnelle de la duplication réelle)
• Chevauchement avec MEMORY.md / CLAUDE.md / règles
• Fraîcheur des références techniques (si les indicateurs CLI / API / noms d'outils semblent obsolètes, vérifier avec WebSearch)
• Fréquence d'utilisation (l'ignorer comme signal lorsqu'elle n'est pas mesurée)

L'évaluation est un jugement holistique, pas un barème numérique. Dimensions directrices : Actionnabilité (exemples/étapes concrets sur lesquels agir), Adéquation du périmètre (nom, déclencheur et corps alignés — ni trop large ni trop étroit), Unicité (non remplaçable par MEMORY / une autre compétence), Actualité (les références fonctionnent dans l'environnement actuel).

Coût agrégé (au niveau de l'ensemble, pas par compétence) : détenir une compétence n'est pas gratuit même si la compétence est individuellement bonne. Les bénéfices des compétences sont fragiles — une bibliothèque large et non curée dégrade la capacité de l'agent à sélectionner la bonne compétence et ramène le comportement vers la base sans compétence. Ainsi, le seuil de Conservation augmente avec la taille de la bibliothèque : lorsque l'ensemble est grand, une compétence simplement acceptable (utilisation rare, faible unicité, forte proximité avec d'autres) est candidate à Retirer/Fusionner sur la seule base de la dilution agrégée — indépendamment de tout défaut dans la compétence elle-même. C'est une entrée de jugement, jamais un quota ; ne pas retirer pour atteindre un nombre.

Verdict	Signification
Conserver	Utile, actuelle, valeur unique
Améliorer	Vaut la peine d'être conservée, mais des améliorations spécifiques nécessaires
Mettre à jour	Technologie référencée obsolète (vérifier avec WebSearch)
Retirer	Faible qualité, obsolète, ou coût asymétrique
Fusionner dans [X]	Chevauchement important avec une autre compétence ; nommer la cible

Règle de non-utilisation : lorsque le premier événement du journal d'utilisation date d'au moins 90 jours ET qu'une compétence a use_90d == 0, elle DOIT être présentée comme candidate au Retrait (la décision finale revient à l'utilisateur). Tant que le journal a moins de 90 jours, cette règle ne s'applique pas, et les verdicts reposent uniquement sur le jugement holistique.

L'évaluation est aveugle à l'origine : ne pas faire de branchement selon que la compétence est ECC / auto-rédigée / extraite automatiquement. La même liste de contrôle s'applique à chaque compétence.

Phase 3 — Résumé

Afficher un tableau : Compétence | 7j | 90j | Verdict | Raison.

Phase 4 — Consolidation

• Retirer / Fusionner : par fichier, présenter (1) le défaut spécifique trouvé, (2) ce qui couvre le même besoin à la place (Retirer : quelle compétence/règle existante ; Fusionner : la cible et quel contenu intégrer), (3) l'impact de la suppression (compétences dépendantes, références dans MEMORY). Agir seulement après confirmation de l'utilisateur.
• Améliorer / Mettre à jour : proposer de passer la main — « Confier <compétence> à skill-creator pour l'améliorer ? » — et sur approbation invoquer skill-creator avec la compétence cible. Stocktake ne fait jamais le travail d'amélioration lui-même.
• Mettre à jour le registre : Lire results.json → fusionner les verdicts de cette exécution → réécrire (evaluated_at = UTC réel depuis date -u +%Y-%m-%dT%H:%M:%SZ). En mode changed, conserver les verdicts antérieurs des compétences non réévaluées.
• Si MEMORY.md dépasse 100 lignes, proposer une compression.

Qualité de la raison (obligatoire)

Chaque raison doit être autonome — permettant une décision par elle-même. « inchangé » seul est interdit ; toujours reformuler la preuve.

• Retirer : énoncer le défaut + le remplacement. Mauvais : "Remplacé" / Bon : "disable-model-invocation: true déjà défini ; continuous-learning-v2 couvre les mêmes motifs plus le scoring de confiance. Aucun contenu unique restant."
• Fusionner : nommer la cible + ce qu'il faut intégrer. Mauvais : "Chevauchement avec X" / Bon : "Contenu mince de 42 lignes ; l'étape 4 de chatlog-to-article couvre déjà ce workflow. Intégrer le conseil 'angle d'article' là-bas comme une note."
• Améliorer : quelle section, quel changement (taille cible si pertinent). Mauvais : "Trop long" / Bon : "276 lignes ; 'Comparison des frameworks' (L80–140) duplique ai-era-architecture-principles. Supprimer pour atteindre ~150 lignes."
• Conserver (changement de mtime uniquement en mode changed) : reformuler la justification originale. Mauvais : "Inchangé" / Bon : "Contenu inchangé. Référence Python unique importée explicitement par rules/python/ ; aucun chevauchement."

results.json (registre allégé)

{
  "evaluated_at": "2026-06-24T11:09:00Z",
  "skills": {
    "<nom-compétence>": {
      "path": "~/.claude/skills/<nom>/SKILL.md",
      "verdict": "Conserver",
      "reason": "...",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}

Un registre pour l'historique des verdicts et l'horodatage du dernier audit uniquement. Le mettre à jour en ligne avec Lecture/Écriture, pas avec un script. Compétences globales uniquement (les compétences de projet sont lues à partir du répertoire courant, non mises en cache ici).

Liés

• skill-creator — le moteur d'amélioration ; lui déléguer le travail d'Amélioration/Mise à jour.
• config-gc — GC sur l'existence des compétences et l'ensemble de ~/.claude (hooks/permissions/MCP/cache) ; stocktake juge la qualité des compétences.
• harness-sync — l'utiliser pour synchroniser ce skill vers son dépôt public.
• Mesure de l'utilisation : ~/.claude/hooks/log-skill-usage.sh → ~/.claude/metrics/skill-usage.jsonl (une couche de mesure indépendante de stocktake).