chore: add project spec and CLAUDE.md

Spec complète du dépôt de skills IA avec installeur bash interactif. Structure dépôt, format skills par agent, palette Gruvbox, site web Hugo prévu. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-16 03:55:21 +02:00
commit ff632f6953
2 changed files with 468 additions and 0 deletions
@@ -0,0 +1,49 @@
 # CLAUDE.md
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 ## Contexte du projet
 Dépôt personnel de skills pour agents IA (Claude Code, Codex, Gemini CLI, Hermes Agent), hébergé sur Gitea (`https://gitea.maison43.duckdns.org/gilles/mes_skills`).
 L'objectif principal est de développer un installeur shell permettant d'installer, activer/désactiver et gérer les skills depuis ce dépôt.
 ## Langue et style
 - Communiquer en **français** avec l'utilisateur
 - Les commentaires dans le code sont en **français**
 - Déployer un plan avant toute écriture de code
 ## Philosophie technique
 - **Bash uniquement** — pas de Node.js, pas de Docker, pas de frameworks lourds
 - Dépendances minimales : `bash`, `curl`, `wget`, `git`
 - Python accepté uniquement si nécessaire, avec `python3 -m venv` ou `uv venv` (jamais `pip install` global)
 - Cible : Debian/Ubuntu, Proxmox, VM légères, homelab
 ## Architecture prévue
 ### Structure des dossiers de skills
 À définir par brainstorming — classement judicieux et évolutif pour plusieurs agents IA.
 ### Script d'installation (`install.sh`)
 Point d'entrée : `curl -fsSL https://gitea.maison43.duckdns.org/gilles/mes_skills/install.sh | bash`
 Comportement attendu :
 1. Détecter les outils présents (`git`, `curl`, `wget`, `python3`, `uv`, `docker`, `podman`)
 2. Détecter les agents IA installés sur le système
 3. Détecter les skills déjà installés (globalement et localement)
 4. Cloner le dépôt dans un répertoire temporaire
 5. Menu interactif (flèches haut/bas, espace, entrée, échap) pour sélectionner les skills
 6. Choix d'installation : global ou projet courant
 7. Gestion du versioning des skills
 8. Détection de skills locaux absents du dépôt → upload optionnel vers Gitea
 ## Structure d'un skill
 Consulter la référence de chaque agent pour la structure exacte :
 - Claude Code : `~/.claude/skills/` (fichiers Markdown avec frontmatter YAML)
 - Gemini CLI : structure similaire
 - Hermes Agent : voir `https://github.com/NousResearch/hermes-agent/blob/main/scripts/install.sh` comme inspiration pour la mécanique d'installation
@@ -0,0 +1,419 @@
 # 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) :
 ```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: <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 :
 ```bash
 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
 ```markdown
 ---
 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 :
 ```bash
 gemini -p "utilise le skill <nom>"
 ```
 ### 4.4 Codex (`codex.md`)
 Docs : https://developers.openai.com/codex/skills
 ```markdown
 ---
 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 :
 ```bash
 codex "$<nom>"
 ```
 ### 4.5 Hermes Agent (`hermes.md`)
 Docs : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/
 ```markdown
 ---
 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 :
 ```bash
 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
 ```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_<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
 ```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)