mes_skills/docs/superpowers/specs/2026-05-16-mes-skills-design.md

Spec — Dépôt personnel de skills IA + installeur bash

Date : 2026-05-16 Statut : Approuvé

---

1. Objectif

Créer un dépôt Gitea personnel (gitea.maison43.duckdns.org/gilles/mes_skills) pour stocker des skills réutilisables pour agents IA (Claude Code, Gemini CLI, Codex, Hermes), accompagné d'un script d'installation interactif bash et d'un portail web statique.

---

2. Agents IA supportés

Agent	Détection (primaire)	Détection (secondaire)	Doc officielle
Claude Code	test -d ~/.claude/	command -v claude	https://code.claude.com/docs/en/skills
Gemini CLI	command -v gemini	$(npm config get prefix)/bin/gemini	https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
Codex	command -v codex	~/.npm-global/bin/codex	https://developers.openai.com/codex/skills
Hermes	command -v hermes	~/.local/bin/hermes	https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/

---

3. Structure du dépôt

Impact du site web : le dossier web/ est prévu dès v1 pour éviter une réorganisation future. Le site lira directement skills/ et le frontmatter YAML pour générer ses pages.

mes_skills/
├── skills/
│   ├── dev/
│   │   └── <nom-skill>/
│   │       ├── claude-code.md      ← SKILL.md pour Claude Code
│   │       ├── gemini-cli.md       ← SKILL.md pour Gemini CLI
│   │       ├── codex.md            ← SKILL.md pour Codex
│   │       └── hermes.md           ← SKILL.md pour Hermes
│   ├── infra/
│   ├── ai/
│   ├── tools/
│   ├── jardinage/
│   ├── electronique/
│   ├── diy/
│   └── task/
├── templates/
│   ├── claude-code.md              ← squelette vierge Claude Code
│   ├── gemini-cli.md               ← squelette vierge Gemini CLI
│   ├── codex.md                    ← squelette vierge Codex
│   └── hermes.md                   ← squelette vierge Hermes
├── web/                            ← portail web statique (Hugo)
│   ├── Dockerfile                  ← image Docker du site
│   ├── docker-compose.yml          ← déploiement + sync Gitea
│   ├── hugo.toml                   ← config Hugo
│   ├── content/                    ← pages générées depuis skills/
│   ├── themes/gruvbox/             ← thème CSS gruvbox dark
│   └── static/
├── docs/
│   ├── structure_skill.md          ← référence format SKILL.md par agent
│   ├── structure_script_install.md ← référence architecture install.sh
│   └── structure_repo.md           ← référence structure bibliothèque
├── install.sh                      ← script d'installation interactif
├── README.md                       ← guide d'utilisation
├── evolution.md                    ← améliorations prévues
└── CLAUDE.md

---

4. Format des skills par agent

4.1 Frontmatter commun (tous agents)

Champ tags ajouté sur tous les agents — utilisé par l'installeur (filtre) et le site web (navigation) :

tags: [bash, debug, git]         # mots-clés libres, minuscules, sans espace

4.2 Claude Code (claude-code.md)

Docs : https://code.claude.com/docs/en/skills

---
name: <nom-du-skill>
version: 1.0.0
description: <description claire et déclencheurs>
agents: [claude-code]
category: <dev|infra|ai|tools|jardinage|electronique|diy|task>
tags: [tag1, tag2]
---

# <Titre du skill>

<Instructions en markdown pour Claude Code>

Champs optionnels : disable-model-invocation, user-invocable, allowed-tools. Destination globale : ~/.claude/skills/<categorie>/<nom>/SKILL.md Destination locale : .claude/skills/<categorie>/<nom>/SKILL.md

Commande de test post-installation :

claude "utilise le skill <nom>" --print

4.3 Gemini CLI (gemini-cli.md)

Docs : https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md

---
name: <nom-du-skill>
version: 1.0.0
description: <description — décrit quand ce skill se déclenche>
agents: [gemini-cli]
category: <categorie>
tags: [tag1, tag2]
---

# <Titre>

<Instructions en markdown>

Destination globale : ~/.gemini/skills/<categorie>/<nom>/SKILL.md Destination locale : .gemini/skills/<categorie>/<nom>/SKILL.md Alias supporté : ~/.agents/skills/ et .agents/skills/

Commande de test post-installation :

gemini -p "utilise le skill <nom>"

4.4 Codex (codex.md)

Docs : https://developers.openai.com/codex/skills

---
name: <nom-du-skill>
version: 1.0.0
description: <description>
allow_implicit_invocation: true
agents: [codex]
category: <categorie>
tags: [tag1, tag2]
---

# <Titre>

<Instructions en markdown>

Destination globale : ~/.codex/skills/<categorie>/<nom>/SKILL.md Destination locale : .codex/skills/<categorie>/<nom>/SKILL.md

Commande de test post-installation :

codex "$<nom>"

4.5 Hermes Agent (hermes.md)

Docs : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/

---
name: <nom-du-skill>
version: 1.0.0
description: <description>
agents: [hermes]
category: <categorie>
tags: [tag1, tag2]
metadata:
  hermes:
    tags: [tag1, tag2]
    category: <categorie>
---

# <Titre>

## Quand utiliser ce skill
## Référence rapide
## Procédure
## Pièges connus
## Vérification

Destination globale : ~/.hermes/skills/<categorie>/<nom>/SKILL.md Destination locale : .hermes/skills/<categorie>/<nom>/SKILL.md

Commande de test post-installation :

hermes "utilise le skill <nom>"

---

5. Script d'installation install.sh

5.1 Philosophie

• Zéro sudo — toutes les destinations sont dans $HOME
• Dépendances : bash, git, fzf (installation proposée si absent)
• Couleurs : palette Gruvbox Dark (256 couleurs, style seventies)

5.2 Palette Gruvbox Dark

# Gruvbox Dark — couleurs 256
GRV_BG='\033[48;5;235m'      # fond sombre
GRV_FG='\033[38;5;223m'      # texte principal (beige chaud)
GRV_RED='\033[38;5;167m'     # erreur
GRV_GREEN='\033[38;5;142m'   # succès / installé
GRV_YELLOW='\033[38;5;214m'  # attention / MAJ dispo
GRV_BLUE='\033[38;5;109m'    # info
GRV_PURPLE='\033[38;5;175m'  # accent
GRV_AQUA='\033[38;5;108m'    # nouveau skill
GRV_ORANGE='\033[38;5;208m'  # warning fort
GRV_GRAY='\033[38;5;245m'    # non applicable / désactivé
RESET='\033[0m'

5.3 Icônes d'état

Icône	Signification	Couleur Gruvbox
✓	Installé	GRV_GREEN
↑	Mise à jour dispo	GRV_YELLOW
+	Nouveau (absent)	GRV_AQUA
·	Non applicable	GRV_GRAY

5.4 Icônes d'action (cycle TAB)

Icône	Action	Couleur
●L	Installer en local	GRV_GREEN
●G	Installer en global	GRV_BLUE
○	Ignorer	GRV_GRAY
↑	Mettre à jour	GRV_YELLOW

5.5 Flux d'exécution

1. Vérifier dépendances (git, fzf)
   └─ fzf absent → proposer installation (apt / binaire GitHub Releases)
   └─ git absent → erreur fatale (GRV_RED)

2. Détecter agents IA installés
   └─ Au moins 1 requis, sinon avertissement (GRV_ORANGE)

3. Cloner le dépôt dans /tmp/mes_skills_<timestamp>/

4. Scanner les skills du dépôt
   └─ Filtrer par agents détectés
   └─ Comparer version: locale vs dépôt (sort -V) → détecter MAJ

5. Menu fzf interactif (thème gruvbox via FZF_DEFAULT_OPTS)
   ├─ Affichage : [icône-état] [categorie/nom] [agent] [action]
   ├─ TAB → cycle action : ●L → ●G → ○ → (↑ si MAJ) → ●L
   ├─ ENTER → confirmer les sélections
   └─ ESC → quitter sans installer

6. Installer les skills sélectionnés
   └─ mkdir -p destination
   └─ cp <agent>.md → destination/SKILL.md
   └─ Afficher bilan : X installés, Y mis à jour, Z ignorés

7. Afficher commandes de test (copiables)
   └─ Une ligne par skill installé, par agent détecté
   └─ Encadrée dans un bloc GRV_PURPLE

8. Afficher liens vers docs des agents détectés
   └─ Une ligne par agent (URL cliquable dans terminal moderne)

9. Nettoyage /tmp/mes_skills_<timestamp>/

5.6 Écran de fin (étapes 7 et 8)

╔══════════════════════════════════════════════════════╗
║  ✓  3 skills installés  ↑ 1 mis à jour  ○ 2 ignorés ║
╚══════════════════════════════════════════════════════╝

  Tester vos skills :

  claude "utilise le skill debugging" --print
  gemini -p "utilise le skill debugging"

  Documentation agents :

  Claude Code  →  https://code.claude.com/docs/en/skills
  Gemini CLI   →  https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
  Codex        →  https://developers.openai.com/codex/skills
  Hermes       →  https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/

5.7 Thème fzf Gruvbox

export FZF_DEFAULT_OPTS="
  --color=bg+:#3c3836,bg:#282828,spinner:#fb4934,hl:#928374
  --color=fg:#ebdbb2,header:#928374,info:#8ec07c,pointer:#fb4934
  --color=marker:#fb4934,fg+:#ebdbb2,prompt:#fb4934,hl+:#fb4934
  --border --height=80% --layout=reverse
"

5.8 Gestion de version

• Format semver X.Y.Z dans le frontmatter version:
• Comparaison : sort -V (tri version natif bash)
• Si version dépôt > version locale → état ↑ (MAJ dispo)

5.9 Légende permanente (bas du menu fzf)

───────────────────────────────────────────────────────────────
État : ✓ installé  ↑ MAJ dispo  + nouveau  · non applicable
Action : ●L local  ●G global  ○ ignorer   TAB=changer  ENTER=ok

---

6. Site web statique (web/)

6.1 Choix technologique : Hugo

Hugo est retenu car :

• Binaire unique, zéro dépendance Node.js (cohérent avec la philosophie du projet)
• Génère les pages depuis les fichiers Markdown + frontmatter YAML existants
• Déployable dans Docker sans runtime
• Thème gruvbox dark à créer dans web/themes/gruvbox/

6.2 Synchronisation

Le container Docker monte skills/ en lecture seule depuis le dépôt cloné. Un cron interne au container (git pull toutes les heures) maintient la synchro.

6.3 Fonctionnalités v1 du site

• Navigation par catégorie et par agent
• Filtrage par tags
• Affichage du contenu Markdown de chaque skill
• Style CSS inspiré de skillsmp.com, thème gruvbox dark

6.4 Fonctionnalités futures du site (hors scope v1)

• Éditeur de skill depuis le navigateur (avec push Gitea via token)
• Création depuis template
• Statistiques d'utilisation

---

7. Documents à produire

Fichier	Contenu
docs/structure_skill.md	Format SKILL.md détaillé par agent + liens
docs/structure_script_install.md	Architecture et logique de install.sh
docs/structure_repo.md	Structure de la bibliothèque de skills
README.md	Guide d'utilisation du dépôt
evolution.md	Améliorations et fonctionnalités futures

---

8. Plan de test et de débogage

8.1 Tests unitaires (bash)

Test	Commande	Résultat attendu
Détection Claude Code	test -d ~/.claude/ && echo OK	OK
Détection Gemini	command -v gemini && echo OK	OK ou "non trouvé"
Comparaison versions	echo -e "1.0.0\n1.2.0" | sort -V | tail -1	1.2.0
Parsing version frontmatter	grep '^version:' skill.md | awk '{print $2}'	version correcte
Parsing tags frontmatter	grep '^tags:' skill.md	liste YAML correcte
Création dossier local	mkdir -p .claude/skills/dev/test && ls	dossier créé

8.2 Tests d'intégration

Scénario	Étapes	Validation
Installation locale	Lancer install.sh, sélectionner un skill, choisir ●L	Fichier dans ./.claude/skills/
Installation globale	Sélectionner ●G	Fichier dans ~/.claude/skills/
Détection MAJ	Installer v1.0, modifier version dépôt à v1.1, relancer	État ↑ affiché
Pas d'agent détecté	Supprimer ~/.claude/, lancer	Avertissement (GRV_ORANGE), pas de crash
fzf absent	Désinstaller fzf, lancer	Proposition d'installation
Filtre par tags	Lancer avec SKILLS_TAG=bash	Seuls les skills tagués bash listés

8.3 Environnements de test

• Debian 12 (cible principale)
• Ubuntu 24.04
• VM légère (sans docker, sans sudo)

8.4 Variables de débogage

SKILLS_DEBUG=1      bash install.sh   # étapes détaillées
SKILLS_DRY_RUN=1    bash install.sh   # simule sans écrire
SKILLS_REPO=/path   bash install.sh   # dépôt local (pas de clone)
SKILLS_TAG=bash     bash install.sh   # filtre par tag
SKILLS_AGENT=claude bash install.sh   # force un seul agent

---

9. Évolutions futures (hors scope v1)

• Upload de skills locaux vers Gitea (via token API Gitea)
• Support des dossiers scripts/ et references/ (Hermes)
• Site web v2 : éditeur de skill depuis le navigateur
• Synchronisation automatique (cron système)
• Signature/vérification d'intégrité des skills
• Interface similaire à skillsmp.com (CSS style, navigation, éditeur)