commit ff632f6953f5e41b8a3daeff1b4071784159b8e9 Author: Gilles Soulier Date: Sat May 16 03:55:21 2026 +0200 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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d330eb4 --- /dev/null +++ b/CLAUDE.md @@ -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 diff --git a/docs/superpowers/specs/2026-05-16-mes-skills-design.md b/docs/superpowers/specs/2026-05-16-mes-skills-design.md new file mode 100644 index 0000000..e1ccd00 --- /dev/null +++ b/docs/superpowers/specs/2026-05-16-mes-skills-design.md @@ -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/ +│ │ └── / +│ │ ├── 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)