# 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/ │ │ └── / │ │ ├── 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) : ```yaml 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 ```markdown --- name: version: 1.0.0 description: agents: [claude-code] category: tags: [tag1, tag2] --- # ``` Champs optionnels : `disable-model-invocation`, `user-invocable`, `allowed-tools`. Destination globale : `~/.claude/skills///SKILL.md` Destination locale : `.claude/skills///SKILL.md` Commande de test post-installation : ```bash claude "utilise le skill " --print ``` ### 4.3 Gemini CLI (`gemini-cli.md`) Docs : https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md ```markdown --- name: version: 1.0.0 description: agents: [gemini-cli] category: tags: [tag1, tag2] --- # ``` Destination globale : `~/.gemini/skills///SKILL.md` Destination locale : `.gemini/skills///SKILL.md` Alias supporté : `~/.agents/skills/` et `.agents/skills/` Commande de test post-installation : ```bash gemini -p "utilise le skill " ``` ### 4.4 Codex (`codex.md`) Docs : https://developers.openai.com/codex/skills ```markdown --- name: version: 1.0.0 description: allow_implicit_invocation: true agents: [codex] category: tags: [tag1, tag2] --- # ``` Destination globale : `~/.codex/skills///SKILL.md` Destination locale : `.codex/skills///SKILL.md` Commande de test post-installation : ```bash codex "$" ``` ### 4.5 Hermes Agent (`hermes.md`) Docs : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/ ```markdown --- name: version: 1.0.0 description: agents: [hermes] category: tags: [tag1, tag2] metadata: hermes: tags: [tag1, tag2] category: --- # ## Quand utiliser ce skill ## Référence rapide ## Procédure ## Pièges connus ## Vérification ``` Destination globale : `~/.hermes/skills///SKILL.md` Destination locale : `.hermes/skills///SKILL.md` Commande de test post-installation : ```bash hermes "utilise le skill " ``` --- ## 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 ```bash # 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_/ 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 .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_/ ``` ### 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 ```bash 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 ```bash 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)