docs: référence format SKILL.md, structure dépôt et architecture install.sh

2026-05-16 04:13:40 +02:00
parent ce09f81959
commit 21958198da
3 changed files with 270 additions and 0 deletions
@@ -0,0 +1,54 @@
+# Structure de la Bibliothèque de Skills
+
+## Arborescence
+
+```
+mes_skills/
+├── skills/                     ← bibliothèque principale
+│   ├── <categorie>/            ← catégorie (dev, infra, jardinage, ...)
+│   │   └── <nom-skill>/        ← un dossier par skill
+│   │       ├── claude-code.md  ← variante Claude Code
+│   │       ├── gemini-cli.md   ← variante Gemini CLI
+│   │       ├── codex.md        ← variante Codex
+│   │       └── hermes.md       ← variante Hermes Agent
+├── templates/                  ← squelettes vierges par agent
+│   ├── claude-code.md
+│   ├── gemini-cli.md
+│   ├── codex.md
+│   └── hermes.md
+├── web/                        ← portail web statique (Hugo + Docker)
+├── docs/                       ← documentation du dépôt
+├── tests/                      ← tests bash de install.sh
+├── install.sh                  ← installeur interactif
+├── README.md
+├── evolution.md
+└── CLAUDE.md
+```
+
+## Catégories disponibles
+
+| Catégorie | Usage |
+|-----------|-------|
+| `dev` | Développement : debug, git, tests, refactoring |
+| `infra` | Infrastructure : docker, proxmox, homelab |
+| `ai` | Agents IA : prompting, workflows |
+| `tools` | Scripts utilitaires, automatisations |
+| `jardinage` | Jardinage et plantes |
+| `electronique` | Électronique, Arduino, ESP32 |
+| `diy` | Bricolage, impression 3D |
+| `task` | Gestion de tâches, organisation |
+
+## Conventions
+
+- Nom du skill : kebab-case (`mon-skill`)
+- Nom des fichiers : `<agent>.md` (ex: `claude-code.md`)
+- Version : semver `X.Y.Z` dans le frontmatter
+- Tags : minuscules, sans espace (ex: `[bash, debug]`)
+- L'installeur copie `<agent>.md` → `SKILL.md` dans la destination
+
+## Ajouter un nouveau skill
+
+1. Créer le dossier : `skills/<categorie>/<nom>/`
+2. Copier un template depuis `templates/<agent>.md`
+3. Remplir le frontmatter et le contenu
+4. Committer et pusher vers Gitea
@@ -0,0 +1,76 @@
+# Architecture de install.sh
+
+## Vue d'ensemble
+
+`install.sh` est un script bash autonome qui :
+1. Vérifie les dépendances (git, fzf)
+2. Détecte les agents IA installés
+3. Clone le dépôt en /tmp
+4. Présente un menu fzf interactif avec état par skill
+5. Installe les skills sélectionnés sans sudo
+6. Affiche un bilan + commandes de test
+
+## Variables d'environnement
+
+| Variable | Défaut | Effet |
+|----------|--------|-------|
+| `SKILLS_DEBUG=1` | non | Affiche chaque étape en détail |
+| `SKILLS_DRY_RUN=1` | non | Simule sans écrire de fichiers |
+| `SKILLS_REPO=/path` | (Gitea) | Utilise un dépôt local |
+| `SKILLS_TAG=bash` | (tous) | Filtre les skills par tag |
+| `SKILLS_AGENT=claude` | (auto) | Force un seul agent |
+
+## Palette Gruvbox Dark (256 couleurs)
+
+| Variable | Code | Usage |
+|----------|------|-------|
+| `GRV_GREEN` | `\033[38;5;142m` | Succès, installé ✓ |
+| `GRV_YELLOW` | `\033[38;5;214m` | MAJ dispo ↑ |
+| `GRV_AQUA` | `\033[38;5;108m` | Nouveau skill + |
+| `GRV_GRAY` | `\033[38;5;245m` | Non applicable · |
+| `GRV_RED` | `\033[38;5;167m` | Erreur fatale |
+| `GRV_ORANGE` | `\033[38;5;208m` | Avertissement |
+| `GRV_BLUE` | `\033[38;5;109m` | Info, action globale |
+| `GRV_PURPLE` | `\033[38;5;175m` | Encadrés, titres |
+
+## Flux d'exécution
+
+```
+check_deps()
+  └─ fzf absent → install_fzf() ou exit
+  └─ git absent → exit 1
+
+detect_agents() → tableau DETECTED_AGENTS[]
+
+clone_repo() → /tmp/mes_skills_<PID>/
+
+scan_skills()
+  └─ pour chaque skills/<cat>/<nom>/<agent>.md du dépôt
+  └─ si agent dans DETECTED_AGENTS
+  └─ get_local_version() vs get_repo_version()
+  └─ compare_versions() → état (✓ ↑ + ·)
+
+run_menu()  [fzf + fichier état /tmp/skills_state_<PID>]
+  └─ TAB → cycle_action() + reload
+  └─ ENTER → liste des sélections
+
+install_selected()
+  └─ mkdir -p destination
+  └─ cp <agent>.md → SKILL.md
+
+print_summary()
+  └─ bilan coloré
+  └─ commandes de test copiables
+  └─ liens docs agents
+
+cleanup() [trap EXIT]
+```
+
+## Destinations d'installation (sans sudo)
+
+| Agent | Global | Local |
+|-------|--------|-------|
+| claude-code | `~/.claude/skills/<cat>/<nom>/SKILL.md` | `.claude/skills/<cat>/<nom>/SKILL.md` |
+| gemini-cli | `~/.gemini/skills/<cat>/<nom>/SKILL.md` | `.gemini/skills/<cat>/<nom>/SKILL.md` |
+| codex | `~/.codex/skills/<cat>/<nom>/SKILL.md` | `.codex/skills/<cat>/<nom>/SKILL.md` |
+| hermes | `~/.hermes/skills/<cat>/<nom>/SKILL.md` | `.hermes/skills/<cat>/<nom>/SKILL.md` |
@@ -0,0 +1,140 @@
+# Structure des Skills par Agent IA
+
+Ce document décrit le format exact attendu pour chaque agent.
+Un même skill peut exister en plusieurs versions (une par agent).
+
+---
+
+## Format commun (frontmatter YAML)
+
+Tous les agents partagent ces champs de base :
+
+| Champ | Requis | Description |
+|-------|--------|-------------|
+| `name` | oui | Identifiant unique du skill (kebab-case) |
+| `version` | oui | Version semver `X.Y.Z` |
+| `description` | oui | Description + déclencheurs (crucial pour l'activation automatique) |
+| `agents` | oui | Liste des agents : `[claude-code]`, `[gemini-cli]`, etc. |
+| `category` | oui | Catégorie : `dev`, `infra`, `ai`, `tools`, `jardinage`, `electronique`, `diy`, `task` |
+| `tags` | recommandé | Mots-clés libres : `[bash, debug, git]` |
+
+---
+
+## Claude Code
+
+**Docs :** https://code.claude.com/docs/en/skills
+
+**Fichier dans le dépôt :** `skills/<categorie>/<nom>/claude-code.md`
+**Destination globale :** `~/.claude/skills/<categorie>/<nom>/SKILL.md`
+**Destination locale :** `.claude/skills/<categorie>/<nom>/SKILL.md`
+
+```yaml
+---
+name: mon-skill
+version: 1.0.0
+description: Description et déclencheurs.
+agents: [claude-code]
+category: dev
+tags: [tag1, tag2]
+# Optionnels :
+# disable-model-invocation: true   # seul l'utilisateur peut invoquer
+# user-invocable: false            # seul Claude peut invoquer
+# allowed-tools: [Read, Grep]      # restreint les outils disponibles
+---
+```
+
+**Commande de test :**
+```bash
+claude "utilise le skill <nom>" --print
+```
+
+---
+
+## Gemini CLI
+
+**Docs :** https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
+
+**Fichier dans le dépôt :** `skills/<categorie>/<nom>/gemini-cli.md`
+**Destination globale :** `~/.gemini/skills/<categorie>/<nom>/SKILL.md`
+**Destination locale :** `.gemini/skills/<categorie>/<nom>/SKILL.md`
+**Alias :** `~/.agents/skills/` et `.agents/skills/`
+
+```yaml
+---
+name: mon-skill
+version: 1.0.0
+description: Description et déclencheurs.
+agents: [gemini-cli]
+category: dev
+tags: [tag1, tag2]
+---
+```
+
+**Commande de test :**
+```bash
+gemini -p "utilise le skill <nom>"
+```
+
+---
+
+## Codex (OpenAI)
+
+**Docs :** https://developers.openai.com/codex/skills
+
+**Fichier dans le dépôt :** `skills/<categorie>/<nom>/codex.md`
+**Destination globale :** `~/.codex/skills/<categorie>/<nom>/SKILL.md`
+**Destination locale :** `.codex/skills/<categorie>/<nom>/SKILL.md`
+
+```yaml
+---
+name: mon-skill
+version: 1.0.0
+description: Description et déclencheurs.
+allow_implicit_invocation: true
+agents: [codex]
+category: dev
+tags: [tag1, tag2]
+---
+```
+
+**Commande de test :**
+```bash
+codex "$<nom>"
+```
+
+---
+
+## Hermes Agent (NousResearch)
+
+**Docs :** https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/
+
+**Fichier dans le dépôt :** `skills/<categorie>/<nom>/hermes.md`
+**Destination globale :** `~/.hermes/skills/<categorie>/<nom>/SKILL.md`
+**Destination locale :** `.hermes/skills/<categorie>/<nom>/SKILL.md`
+
+```yaml
+---
+name: mon-skill
+version: 1.0.0
+description: Description et déclencheurs.
+agents: [hermes]
+category: dev
+tags: [tag1, tag2]
+metadata:
+  hermes:
+    tags: [tag1, tag2]
+    category: dev
+---
+```
+
+Structure Markdown recommandée par Hermes :
+- `## Quand utiliser ce skill`
+- `## Référence rapide`
+- `## Procédure`
+- `## Pièges connus`
+- `## Vérification`
+
+**Commande de test :**
+```bash
+hermes "utilise le skill <nom>"
+```