From 21958198da32ffda84934241ae9a5c086d23d3f3 Mon Sep 17 00:00:00 2001 From: Gilles Soulier Date: Sat, 16 May 2026 04:13:40 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20r=C3=A9f=C3=A9rence=20format=20SKILL.md?= =?UTF-8?q?,=20structure=20d=C3=A9p=C3=B4t=20et=20architecture=20install.s?= =?UTF-8?q?h?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/structure_repo.md | 54 ++++++++++++ docs/structure_script_install.md | 76 +++++++++++++++++ docs/structure_skill.md | 140 +++++++++++++++++++++++++++++++ 3 files changed, 270 insertions(+) create mode 100644 docs/structure_repo.md create mode 100644 docs/structure_script_install.md create mode 100644 docs/structure_skill.md diff --git a/docs/structure_repo.md b/docs/structure_repo.md new file mode 100644 index 0000000..b2627ce --- /dev/null +++ b/docs/structure_repo.md @@ -0,0 +1,54 @@ +# Structure de la Bibliothèque de Skills + +## Arborescence + +``` +mes_skills/ +├── skills/ ← bibliothèque principale +│ ├── / ← catégorie (dev, infra, jardinage, ...) +│ │ └── / ← 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 : `.md` (ex: `claude-code.md`) +- Version : semver `X.Y.Z` dans le frontmatter +- Tags : minuscules, sans espace (ex: `[bash, debug]`) +- L'installeur copie `.md` → `SKILL.md` dans la destination + +## Ajouter un nouveau skill + +1. Créer le dossier : `skills///` +2. Copier un template depuis `templates/.md` +3. Remplir le frontmatter et le contenu +4. Committer et pusher vers Gitea diff --git a/docs/structure_script_install.md b/docs/structure_script_install.md new file mode 100644 index 0000000..370fa17 --- /dev/null +++ b/docs/structure_script_install.md @@ -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_/ + +scan_skills() + └─ pour chaque skills///.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_] + └─ TAB → cycle_action() + reload + └─ ENTER → liste des sélections + +install_selected() + └─ mkdir -p destination + └─ cp .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///SKILL.md` | `.claude/skills///SKILL.md` | +| gemini-cli | `~/.gemini/skills///SKILL.md` | `.gemini/skills///SKILL.md` | +| codex | `~/.codex/skills///SKILL.md` | `.codex/skills///SKILL.md` | +| hermes | `~/.hermes/skills///SKILL.md` | `.hermes/skills///SKILL.md` | diff --git a/docs/structure_skill.md b/docs/structure_skill.md new file mode 100644 index 0000000..486dd4f --- /dev/null +++ b/docs/structure_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///claude-code.md` +**Destination globale :** `~/.claude/skills///SKILL.md` +**Destination locale :** `.claude/skills///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 " --print +``` + +--- + +## Gemini CLI + +**Docs :** https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md + +**Fichier dans le dépôt :** `skills///gemini-cli.md` +**Destination globale :** `~/.gemini/skills///SKILL.md` +**Destination locale :** `.gemini/skills///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 " +``` + +--- + +## Codex (OpenAI) + +**Docs :** https://developers.openai.com/codex/skills + +**Fichier dans le dépôt :** `skills///codex.md` +**Destination globale :** `~/.codex/skills///SKILL.md` +**Destination locale :** `.codex/skills///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 "$" +``` + +--- + +## Hermes Agent (NousResearch) + +**Docs :** https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/ + +**Fichier dans le dépôt :** `skills///hermes.md` +**Destination globale :** `~/.hermes/skills///SKILL.md` +**Destination locale :** `.hermes/skills///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 " +```