751 lines
22 KiB
Markdown
751 lines
22 KiB
Markdown
# 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/<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` :
|
|
|
|
```text
|
|
<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` :
|
|
|
|
```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/<categorie>/<nom>/
|
|
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 `<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
|
|
|
|
```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 `<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 :
|
|
|
|
```text
|
|
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`
|
|
|
|
```text
|
|
skills/<categorie>/<nom>/<agent>.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/<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 :
|
|
|
|
```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 `<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 :
|
|
|
|
```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=<dossier du skill>`.
|
|
|
|
### 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
|
|
<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 :
|
|
|
|
```text
|
|
<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é :
|
|
|
|
```text
|
|
copier <agent>.md vers <destination>/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
|
|
<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é
|
|
|
|
```text
|
|
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.
|