mes_skills/amelioration.md

Proposition d'amélioration de l'installeur de skills

Résumé

Le problème observé avec ha-log-investigator ne vient probablement pas d'une désynchronisation du dépôt, mais d'un écart entre :

1. le format réellement standard de Claude Code, fondé sur un dossier de skill contenant un fichier d'entrée SKILL.md et éventuellement des fichiers de support ;
2. le format interne historique choisi par ce dépôt, fondé sur un fichier par agent (claude-code.md, codex.md, etc.) que l'installeur copie ensuite vers SKILL.md.

ha-log-investigator suit le premier modèle. install.sh ne sait actuellement traiter que le second.

---

1. Structure actuelle du dépôt

La documentation locale du projet définit aujourd'hui cette convention :

skills/<categorie>/<nom>/
  claude-code.md
  gemini-cli.md
  codex.md
  hermes.md

Cette convention apparaît notamment dans :

• README.md
• docs/structure_repo.md
• docs/structure_skill.md
• docs/structure_script_install.md
• docs/superpowers/specs/2026-05-16-mes-skills-design.md

Le rôle de l'installeur est alors de copier un fichier source propre à l'agent vers la destination finale sous le nom SKILL.md :

<agent>.md  ->  ~/.<agent>/skills/<categorie>/<nom>/SKILL.md

Cette architecture est cohérente en interne, mais ce n'est pas la structure native d'un skill Claude Code complet.

---

2. Structure réellement attendue par Claude Code

La documentation officielle Claude Code décrit un skill comme un dossier dont le point d'entrée obligatoire est SKILL.md :

my-skill/
  SKILL.md
  template.md
  examples/
  scripts/

Les fichiers annexes sont optionnels mais font partie du modèle prévu : modèles, exemples, scripts, documentation de référence. Cette structure permet à un skill d'être plus qu'un simple fichier Markdown.

Le dossier actuel skills/infra/ha-log-investigator/ correspond précisément à ce modèle :

ha-log-investigator/
  SKILL.md
  references/
  scripts/
  templates/

Il est donc valide du point de vue du format Claude Code, et même plus représentatif d'un skill avancé que les anciens exemples mono-fichier.

---

3. Pourquoi ha-log-investigator n'est pas détecté aujourd'hui

Dans install.sh, la fonction scan_skills() parcourt tous les fichiers Markdown puis déduit l'agent à partir du nom du fichier :

agent_file="${rel##*/}"
agent="${agent_file%.md}"

Cela fonctionne pour :

claude-code.md -> claude-code
codex.md       -> codex

Mais pour :

SKILL.md -> SKILL

l'installeur croit que l'agent s'appelle SKILL, puis le filtre car aucun agent détecté ne porte ce nom.

Il existe donc deux problèmes distincts :

1. détection impossible des skills au format standard SKILL.md ;
2. installation incomplète des skills groupés, car le script copie actuellement un seul fichier et ne sait pas recopier les ressources associées (scripts/, templates/, references/).

Le second point est important : même si l'on rendait simplement SKILL.md visible dans le menu, une copie limitée au fichier principal casserait une partie de la valeur de ha-log-investigator.

---

4. Diagnostic d'architecture

Le projet mélange aujourd'hui deux niveaux qui devraient être distingués :

A. Le format de stockage dans le dépôt

Actuellement :

un fichier par agent

Avantage : simple à filtrer et à copier.

Limite : ne représente pas correctement les skills modernes composés de plusieurs fichiers.

B. Le format final attendu par les agents

Pour Claude Code, le format final naturel est déjà :

un dossier de skill avec SKILL.md et ressources facultatives

L'installeur convertit donc artificiellement un modèle interne simplifié vers le modèle final. Cette conversion fonctionne pour les skills simples, mais devient fragile dès qu'un skill devient réellement structuré.

---

5. Proposition principale : passer à un modèle "bundle-first"

Principe

Faire du dossier de skill le format canonique du dépôt :

skills/<categorie>/<nom>/
  SKILL.md
  scripts/
  templates/
  references/

Le fichier SKILL.md devient la source principale. Le champ agents: du frontmatter indique les agents compatibles :

agents: [claude-code, codex]

L'installeur ne devrait plus déduire l'agent seulement depuis le nom d'un fichier, mais lire explicitement cette information dans le frontmatter.

Pourquoi ce modèle est meilleur

• Il suit le standard Claude Code au lieu de le reconstruire indirectement.
• Il permet les vrais skills avancés avec scripts, références et templates.
• Il évite de dupliquer le même contenu entre plusieurs fichiers quand le skill est réellement commun à plusieurs agents.
• Il rend le dépôt plus lisible : un skill = un dossier complet.
• Il aligne mieux le stockage source et le format installé.

---

6. Compatibilité recommandée pendant la transition

Il ne faut pas forcément casser l'existant d'un coup. Une migration douce serait préférable.

Phase 1 — compatibilité double format

L'installeur accepte les deux formes :

Format historique :
skills/dev/debugging/claude-code.md

Format standard :
skills/infra/ha-log-investigator/SKILL.md

Règles proposées :

1. si un dossier contient SKILL.md, il est traité comme un bundle standard ;
2. l'installeur lit agents: dans le frontmatter ;
3. il crée une entrée de menu par agent compatible détecté ;
4. lors de l'installation d'un bundle, il copie tout le dossier utile, pas seulement SKILL.md ;
5. les anciens fichiers <agent>.md restent supportés pour éviter une migration immédiate de tous les skills.

Phase 2 — migration progressive

Au fil du temps :

• convertir les skills simples vers SKILL.md quand c'est pertinent ;
• conserver des variantes par agent seulement lorsqu'un vrai écart de contenu est nécessaire ;
• mettre à jour les templates, les docs et les tests pour documenter le nouveau modèle comme format principal.

---

7. Point à décider pour le multi-agent

Le dépôt vise plusieurs agents. Il faut donc clarifier la politique suivante :

Option A — un SKILL.md commun multi-agent

ha-log-investigator/
  SKILL.md   # agents: [claude-code, codex]

À privilégier quand le contenu est identique ou presque identique entre agents.

Option B — bundle commun + adaptations ciblées

ha-log-investigator/
  SKILL.md
  variants/
    codex.md
    hermes.md

À utiliser seulement si certains agents nécessitent réellement des différences de frontmatter ou de formulation.

Option C — rester entièrement par agent

ha-log-investigator/
  claude-code.md
  codex.md

Simple mais moins adapté aux skills avec ressources partagées ; cette option devient moins convaincante pour les bundles riches.

Recommandation

Adopter A comme règle générale, B comme échappatoire, et éviter C sauf pour les anciens skills en cours de migration.

---

8. Améliorations concrètes à prévoir dans install.sh

Sans détailler encore l'implémentation ligne par ligne, l'évolution devrait couvrir :

1. Découverte des skills

   • chercher les dossiers contenant SKILL.md ;
   • continuer à reconnaître les anciens fichiers <agent>.md.

2. Lecture du frontmatter

   • parser agents: comme une liste réelle ;
   • ne plus déduire systématiquement l'agent depuis le nom de fichier.

3. Installation

   • pour un bundle standard, recopier le dossier entier du skill ;
   • préserver references/, scripts/, templates/ et autres ressources ;
   • éventuellement exclure les fichiers internes non destinés à l'installation si une convention est définie plus tard.

4. Affichage dans le menu

   • présenter un même skill pour chaque agent compatible détecté ;
   • distinguer clairement les skills bundle des skills legacy si utile au diagnostic.

5. Tests

   • ajouter un test de détection d'un SKILL.md multi-agent ;
   • ajouter un test d'installation avec ressources annexes ;
   • ajouter un test de coexistence entre format historique et nouveau format.

6. Documentation

   • corriger README.md, docs/structure_repo.md, docs/structure_skill.md et docs/structure_script_install.md ;
   • préciser que le format historique est encore accepté mais n'est plus le format recommandé.

---

9. Cas particulier de ha-log-investigator

ha-log-investigator est en réalité un bon révélateur d'un besoin déjà présent dans le projet :

• il est plus complexe qu'un skill simple ;
• il contient des ressources annexes utiles ;
• il suit naturellement le standard moderne de Claude Code ;
• il met en évidence que l'architecture actuelle de l'installeur était suffisante pour des exemples simples, mais pas encore pour des skills complets.

Il ne faudrait donc pas traiter ce dossier comme une anomalie à corriger, mais comme le premier cas concret justifiant l'évolution de l'installeur.

---

10. Recommandation finale

Court terme

Faire évoluer l'installeur pour supporter sans casser l'existant :

• les anciens fichiers <agent>.md ;
• les bundles standards avec SKILL.md ;
• la copie récursive des ressources d'un bundle.

Moyen terme

Faire du modèle suivant la convention officielle recommandée du dépôt :

skills/<categorie>/<nom>/SKILL.md

avec agents: dans le frontmatter comme source de vérité.

Bénéfice attendu

Le dépôt deviendrait :

• plus fidèle aux standards réels des agents modernes ;
• plus robuste pour les skills évolués ;
• plus simple à maintenir à long terme ;
• moins dépendant d'une convention interne inventée uniquement pour faciliter le premier script.

---

11. Sources consultées

• Documentation officielle Claude Code, section consacrée aux skills : structure en dossier avec SKILL.md comme point d'entrée obligatoire et fichiers de support optionnels.
• Documentation interne du dépôt : README.md, docs/structure_repo.md, docs/structure_skill.md, docs/structure_script_install.md, docs/superpowers/specs/2026-05-16-mes-skills-design.md.

---

Plan technique proposé pour faire évoluer install.sh

Objectif du chantier

Faire évoluer l'installeur pour qu'il sache gérer deux familles de skills :

1. les skills historiques mono-fichier, encore présents dans le dépôt ;
2. les skills bundle, structurés selon le modèle SKILL.md + ressources associées.

L'objectif n'est pas de réécrire tout le script, mais d'isoler proprement les changements nécessaires pour :

• détecter ha-log-investigator ;
• l'installer correctement avec ses fichiers annexes ;
• préserver la compatibilité avec les skills existants ;
• préparer une migration progressive du dépôt vers le format moderne.

---

Étape 1 — Formaliser les deux formats supportés

1.1 Format historique legacy

skills/<categorie>/<nom>/<agent>.md

Exemples :

skills/dev/debugging/claude-code.md
skills/dev/debugging/codex.md

Caractéristiques :

• un fichier = un agent ;
• l'agent est déduit du nom de fichier ;
• l'installation copie ce fichier vers SKILL.md.

1.2 Format moderne bundle

skills/<categorie>/<nom>/SKILL.md
skills/<categorie>/<nom>/scripts/
skills/<categorie>/<nom>/templates/
skills/<categorie>/<nom>/references/

Caractéristiques :

• un dossier = un skill complet ;
• les agents compatibles sont lus dans agents: ;
• l'installation copie le dossier complet vers la destination.

Décision recommandée

Documenter dès maintenant ces deux formats, mais annoncer clairement que :

• bundle est le format recommandé pour les nouveaux skills ;
• legacy est un format encore supporté pour compatibilité.

---

Étape 2 — Faire évoluer le modèle interne utilisé par le script

Aujourd'hui, SKILLS_LIST stocke des chaînes de ce type :

cat|skill|agent|etat|repo_version|local_version|desc|tags

Ce format ne dit pas :

• d'où vient le skill ;
• s'il faut copier un fichier ou un dossier ;
• quel chemin source exact installer.

Nouveau format conseillé

Étendre chaque entrée avec deux champs supplémentaires :

cat|skill|agent|etat|repo_version|local_version|desc|tags|kind|source_path

Avec :

• kind=legacy pour les anciens fichiers <agent>.md ;
• kind=bundle pour les dossiers contenant SKILL.md ;
• source_path = chemin réel du fichier ou du dossier source.

Pourquoi cette étape est essentielle

Elle évite d'éparpiller des suppositions partout dans le script. Une fois qu'une entrée sait si elle est legacy ou bundle, les étapes suivantes deviennent beaucoup plus simples : affichage, aperçu, installation, copie, tests.

---

Étape 3 — Séparer la découverte des skills en deux chemins explicites

3.1 Ajouter une découverte des bundles

Créer une logique dédiée qui parcourt :

find "${REPO_DIR}/skills" -name "SKILL.md"

Pour chaque bundle :

1. déterminer cat et skill depuis le chemin ;
2. lire agents: dans le frontmatter ;
3. créer une entrée par agent compatible détecté ;
4. stocker kind=bundle et source_path=<dossier du skill>.

3.2 Conserver la découverte legacy

Garder un second chemin pour les fichiers historiques :

find "${REPO_DIR}/skills" -name "*.md" ! -name "SKILL.md"

Mais avec une règle importante :

• ne considérer comme agent valide que les noms réellement connus (claude-code, gemini-cli, codex, hermes) ;
• ignorer les autres fichiers Markdown de support pour éviter les faux positifs.

3.3 Éviter les doublons

Si un même skill existe à la fois en bundle et en legacy, il faut décider une priorité.

Recommandation

Priorité au format bundle.

Exemple : si skills/dev/foo/SKILL.md existe déjà, les anciens fichiers foo/claude-code.md ne devraient plus créer de doublons pour le même agent, sauf si une convention de variante est introduite plus tard.

---

Étape 4 — Ajouter un vrai parseur minimal du champ agents:

Aujourd'hui, l'installeur lit des champs simples comme version: ou description: avec grep et awk.

Pour agents: [claude-code, codex], il faut au minimum une fonction dédiée, par exemple conceptuellement :

get_frontmatter_agents(file) -> claude-code codex

Ce que cette fonction doit savoir faire

• lire une ligne du type agents: [claude-code, codex] ;
• retirer crochets et espaces ;
• retourner une liste exploitable ;
• ignorer proprement un fichier mal formé ;
• permettre au mode debug d'expliquer pourquoi un bundle est ignoré.

Recommandation

Rester simple au début : supporter uniquement la forme compacte déjà utilisée dans ton dépôt.

agents: [claude-code, codex]

Pas besoin d'introduire tout de suite un vrai parseur YAML complet ; ce serait disproportionné pour ce script bash.

---

Étape 5 — Adapter la logique de version locale

Aujourd'hui, get_local_version() sait lire :

<destination>/SKILL.md

Cette partie peut rester presque inchangée, parce qu'après installation les deux formats aboutissent à la même destination finale.

À vérifier néanmoins

Pour un bundle, la version continue bien à être lue depuis :

<dest_dir>/SKILL.md

Donc le modèle de comparaison de versions peut rester commun entre legacy et bundle.

---

Étape 6 — Faire évoluer l'installation elle-même

C'est ici que la distinction legacy / bundle devient vraiment utile.

6.1 Installation legacy

Comportement actuel conservé :

copier <agent>.md vers <destination>/SKILL.md

6.2 Installation bundle

Nouveau comportement :

copier le contenu du dossier source vers le dossier destination

Cela doit inclure :

• SKILL.md
• scripts/
• templates/
• references/
• tout autre fichier de support réellement présent dans le bundle.

Point de vigilance

Il faut décider si une mise à jour de bundle :

• écrase uniquement les fichiers présents ;
• ou resynchronise exactement le dossier destination.

Recommandation

Pour commencer, privilégier la solution la plus sûre :

• créer le dossier si besoin ;
• recopier le contenu du bundle par-dessus ;
• ne pas supprimer automatiquement les fichiers supplémentaires présents côté destination.

Cela évite de détruire des fichiers locaux non prévus. Une vraie option --sync ou --clean pourra venir plus tard si besoin.

---

Étape 7 — Adapter l'aperçu et l'affichage du menu

7.1 Aperçu (v)

Aujourd'hui, l'aperçu sait retrouver un fichier à afficher. Pour un bundle, il faut afficher :

<source_path>/SKILL.md

et non le dossier lui-même.

7.2 Affichage dans la liste

Le menu peut rester presque identique. Il peut être utile d'ajouter, au moins en mode debug ou dans une future vue détaillée :

• legacy
• bundle

Mais je ne recommande pas d'ajouter trop de bruit dans l'interface principale dès la première étape.

7.3 Description et tags

Ils doivent toujours être lus depuis le fichier principal :

• <agent>.md pour legacy ;
• SKILL.md pour bundle.

---

Étape 8 — Mettre à jour les tests avant la migration réelle

Les tests actuels couvrent surtout :

• les versions ;
• le parsing de champs simples ;
• les chemins ;
• l'état du menu.

Ils ne couvrent pas encore le cœur du problème actuel.

Tests à ajouter

1. Détection d'un bundle simple

   • un dossier avec SKILL.md
   • agents: [claude-code]
   • attendu : une entrée détectée.

2. Détection d'un bundle multi-agent

   • agents: [claude-code, codex]
   • attendu : deux entrées, une par agent.

3. Ignorer les fichiers de support Markdown

   • references/foo.md
   • attendu : jamais interprété comme un skill installable.

4. Copie complète d'un bundle

   • présence de SKILL.md, scripts/a.sh, templates/x.md
   • attendu : tous les fichiers sont présents après installation.

5. Compatibilité legacy conservée

   • un ancien claude-code.md
   • attendu : toujours détecté et installable.

6. Priorité bundle sur legacy si les deux existent

   • même skill présent sous les deux formes
   • attendu : pas de doublon incohérent.

Pourquoi avant la migration

Parce qu'une fois ces tests en place, on peut faire évoluer install.sh avec beaucoup moins de risque de casser ce qui fonctionne déjà.

---

Étape 9 — Mettre à jour la documentation après validation du nouveau modèle

Les fichiers à revoir sont clairement identifiés :

• README.md
• docs/structure_repo.md
• docs/structure_skill.md
• docs/structure_script_install.md
• éventuellement templates/
• éventuellement docs/superpowers/specs/... si tu veux garder la spec historique comme document vivant plutôt qu'archive.

Message documentaire recommandé

Le format recommandé pour les nouveaux skills est désormais le bundle :
skills/<categorie>/<nom>/SKILL.md

Le format historique <agent>.md reste supporté pour compatibilité.

---

Étape 10 — Migration des skills existants

Je déconseille de migrer tous les skills dans le même commit que l'évolution de l'installeur.

Ordre conseillé

1. faire accepter bundle + legacy par l'installeur ;
2. valider avec ha-log-investigator ;
3. migrer un skill simple, par exemple docker-compose, comme test réel ;
4. seulement ensuite décider si tu veux convertir tout le dépôt.

Pourquoi

Cela te permet de vérifier le nouveau modèle avec :

• un skill complexe (ha-log-investigator) ;
• un skill simple (docker-compose) ;
• et de voir si la duplication multi-agent reste réellement utile dans ta pratique.

---

Découpage recommandé en commits

Commit 1 — Support technique du double format

• modèle interne enrichi ;
• scan bundle + legacy ;
• lecture de agents: ;
• tests de détection.

Commit 2 — Installation complète des bundles

• copie récursive ;
• aperçu adapté ;
• tests d'installation bundle.

Commit 3 — Documentation

• README ;
• docs de structure ;
• mention du format recommandé.

Commit 4 — Migration pilote

• migration éventuelle d'un skill simple vers SKILL.md ;
• retour d'expérience avant généralisation.

---

Ce que je ne recommande pas pour l'instant

1. Réécrire tout le script

Le script actuel contient déjà beaucoup de logique utile :

• détection des agents ;
• menu fzf ;
• gestion local/global ;
• comparaison de versions ;
• vue des skills installés.

Le problème est ciblé ; une refonte complète serait plus risquée que nécessaire.

2. Introduire un parseur YAML lourd

Le besoin actuel est limité. Tant que le frontmatter reste sous contrôle dans ton propre dépôt, une fonction bash simple suffit.

3. Migrer tous les anciens skills immédiatement

Ce serait tentant, mais cela mélangerait :

• changement d'architecture ;
• changement de données ;
• validation fonctionnelle.

Mieux vaut d'abord stabiliser la mécanique.

---

Ordre de décision proposé

Avant toute modification de code, il reste surtout trois décisions à valider :

1. Acceptes-tu que bundle devienne le format recommandé du dépôt ?
2. Veux-tu garder la compatibilité avec les anciens <agent>.md pendant une période de transition ?
3. Pour les bundles multi-agent, veux-tu partir sur un SKILL.md commun par défaut, avec variantes seulement si nécessaire ?

Ma recommandation personnelle

Oui aux trois :

• bundle comme format recommandé ;
• compatibilité legacy conservée ;
• SKILL.md commun par défaut, variantes uniquement quand l'écart entre agents devient réel.