gilles/mes_skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add project spec and CLAUDE.md

Browse Source 
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>
This commit is contained in:
gilles soulier
2026-05-16 03:55:21 +02:00
commit ff632f6953
2 changed files with 468 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+49
View File
@@ -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
docs/superpowers/specs/2026-05-16-mes-skills-design.md
+419
View File
@@ -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)