# 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 : ```text skills/// 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` : ```text .md -> ~/./skills///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` : ```text 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 : ```text 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** : ```bash agent_file="${rel##*/}" agent="${agent_file%.md}" ``` Cela fonctionne pour : ```text claude-code.md -> claude-code codex.md -> codex ``` Mais pour : ```text 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 : ```text 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à : ```text 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 : ```text skills/// SKILL.md scripts/ templates/ references/ ``` Le fichier `SKILL.md` devient la source principale. Le champ `agents:` du frontmatter indique les agents compatibles : ```yaml 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 : ```text 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 `.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 ```text 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 ```text 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 ```text 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 `.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 `.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 : ```text skills///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` ```text skills///.md ``` Exemples : ```text 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` ```text skills///SKILL.md skills///scripts/ skills///templates/ skills///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 : ```text 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 : ```text cat|skill|agent|etat|repo_version|local_version|desc|tags|kind|source_path ``` Avec : - `kind=legacy` pour les anciens fichiers `.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 : ```bash 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=`. ### 3.2 Conserver la découverte legacy Garder un second chemin pour les fichiers historiques : ```bash 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 : ```text 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. ```yaml 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 : ```text /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 : ```text /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é : ```text copier .md vers /SKILL.md ``` ### 6.2 Installation bundle Nouveau comportement : ```text 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 : ```text /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 : - `.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é ```text Le format recommandé pour les nouveaux skills est désormais le bundle : skills///SKILL.md Le format historique .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 `.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.