Création de compétences pour l'agent Hermes — Structure de SKILL.md et bonnes pratiques

Hermes Agent considère les compétences (skills) comme la méthode par défaut pour enseigner des flux de travail répétables. La documentation officielle les décrit comme des documents de connaissances sur demande, alignés sur le format ouvert agentskills.io, chargés via une révélation progressive afin que le modèle voie d’abord un index réduit et n’extraye les instructions complètes que lorsqu’une tâche en a réellement besoin.

La rédaction consiste moins à trouver des mots astucieux qu’à structurer — vous indiquez au runtime quand charger une procédure, quelle séquence d’étapes constitue une tâche « terminée », et comment distinguer un succès d’un échec silencieux. Cet article se concentre sur la structure de SKILL.md, les dossiers de support, les règles de visibilité et la distinction entre les paramètres secrets et non secrets — les détails qui déterminent si une compétence apparaît dans les commandes /slash, survit à une installation via le hub ou disparaît silencieusement en CI.

Hermes s’inscrit dans le cluster plus large Systèmes IA : Assistants auto-hébergés, RAG et infrastructure locale, où les assistants sont traités comme des systèmes construits à partir d’inférence, de récupération, de mémoire et d’outils, plutôt que comme une simple interface de chat. Les chemins d’installation, la configuration des fournisseurs, le comportement de la passerelle et la structure de ~/.hermes sont tous détaillés dans le guide Assistant IA Hermes - Installation, Configuration, Flux de travail et Dépannage ; l’ergonomie quotidienne en ligne de commande — hermes skills, profils, passerelle, mémoire — est plus facile à consulter dans la Fiche pratique de l’interface en ligne de commande de Hermes Agent — commandes, drapeaux et raccourcis slash. Dans les déploiements réels, les compétences héritent de l’isolation des profils (configuration, secrets, mémoires et arbres de compétences séparés). Compétences de l’assistant IA Hermes pour les configurations de production réelles préconise de traiter ces profils — et non les fichiers markdown individuels — comme l’unité d’appropriation ; gardez cela à l’esprit lorsque vous nommez des compétences et décidez ce qui appartient aux external_dirs partagés par rapport à un profil unique.

Compétence ou outil ?

Les directives officielles sont directes. Utilisez une compétence lorsque la capacité repose principalement sur des instructions en prose, des commandes shell et des outils que Hermes expose déjà — encapsuler une CLI, piloter git, appeler curl ou utiliser web_extract pour des extractions structurées. Utilisez un outil lorsque vous avez besoin d’une intégration stricte pour les clés API et les flux d’authentification, de la manipulation déterministe de binaires, du streaming ou de Python qui doit s’exécuter de manière identique à chaque fois.

Cette distinction est importante en pratique car les compétences sont déployées sans modifier le code de l’agent, tandis que les outils entraînent une surcharge de révision et de publication. La plupart des équipes bénéficient de commencer par une compétence, puis de promouvoir uniquement le cœur fragile en outil une fois les modes de défaillance évidents (boucles de rafraîchissement d’authentification, analyseurs binaires, idempotence stricte).

Procédures versus mémoire curatée

Les compétences répondent au comment exécuter un flux de travail ; la mémoire centrale bornée de Hermes répond au ce qui a déjà été convenu concernant l’utilisateur et le projet. Une compétence se charge lorsque la tâche correspond à sa description ; MEMORY.md et USER.md restent dans le prompt comme une petite couche de faits curatés. Les deux mécanismes s’empilent plutôt que de concourir, et la vue d’ensemble des instantanés, limites et fournisseurs externes est détaillée dans Système de mémoire de l’agent Hermes : Comment la mémoire IA persistante fonctionne réellement.

Anatomie d’un répertoire de compétence

Sur le disque, chaque compétence est un dossier sous ~/.hermes/skills/, souvent imbriqué sous une catégorie telle que devops/ ou research/. Hermes s’attend à trouver SKILL.md à la feuille ; tout le reste est une structure optionnelle que vous ajoutez lorsque les instructions seraient autrement dispersées. Le schéma habituel est references/ pour les longs tableaux ou la documentation des fournisseurs, templates/ pour les squelettes de sortie, scripts/ pour les assistants déterministes, et assets/ pour les fichiers statiques que l’agent ne doit pas réextraire.

Cette structure reflète la façon dont la révélation progressive fonctionne en pratique : l’agent peut rester sur le fichier principal jusqu’à ce qu’il ait réellement besoin d’une annexe approfondie. Garder le texte du « chemin heureux » dans SKILL.md et déplacer les détails rarement utilisés dans references/ est l’un des moyens les moins coûteux de protéger les budgets de tokens.

Hermes peut également fusionner des répertoires de compétences externes via skills.external_dirs dans config.yaml. Ces chemins sont scannés pour la découverte, mais l’agent écrit toujours via skill_manage dans l’arborescence principale ~/.hermes/skills/. Les noms locaux masquent les noms externes, donc si vous « corrigez » une compétence partagée dans votre répertoire personnel, les collègues qui tirent du même référentiel externe ne verront pas votre modification tant qu’ils n’ont pas supprimé ou renommé la copie locale — une source courante de confusion du type « ça marche sur ma machine ».

Frontmatter SKILL.md qui survit à la révision

Le corps de SKILL.md est du Markdown ; le bloc d’ouverture doit être du YAML valide entre les délimiteurs ---. Les compétences réelles accumulent de longs exemples clôturés, donc les petites habitudes issues de Blocs de code Markdown : Guide complet avec syntaxe, langages et exemples — balises de langue cohérentes, extraits lisibles, clôtures serrées — gardent les gros fichiers maintenables pour les humains et légèrement plus faciles à scanner pour le modèle.

Les champs requis sont name et description. Le name devient la route slash et la clé d’index ; il reste en minuscules avec des tirets et doit respecter la limite de longueur documentée. La description est le seul prose pour lequel de nombreuses sessions paient au niveau zéro, elle doit donc ressembler à un résultat de recherche ou une chaîne de routage (« lorsque les sauvegardes semblent obsolètes, vérifier l’archive la plus récente et le checksum »), et non le premier paragraphe d’un article de blog.

Les clés de niveau supérieur facultatives telles que version, author et license aident à l’emballage du hub et aux audits. La liste platforms (macos, linux, windows) est plus efficace qu’il n’y paraît — lorsque elle est définie, Hermes omet la compétence entièrement sur les hôtes non correspondants, c’est pourquoi une compétence qui « fonctionne sur mon Mac » peut disparaître en CI Linux sans autre message d’erreur qu’une liste de compétences plus courte.

Les paramètres spécifiques à Hermes se trouvent sous metadata.hermes : tags, related_skills, et les champs de visibilité conditionnelle dans la section suivante. required_environment_variables déclare les secrets qui doivent atterrir dans .env et passer dans les sandboxes ; required_credential_files couvre les fichiers de jetons OAuth et autres identifiants sur disque qui doivent être montés dans Docker ou Modal ; metadata.hermes.config déclare les préférences non secrètes stockées sous skills.config dans config.yaml.

Les documents officiels insistent sur la discipline de taille pour une raison. Réduisez la description à son budget, mettez la procédure en avant et déplacez les notes historiques ou les matrices d’options géantes dans references/ afin qu’un skill_view partiel donne toujours à l’agent quelque chose d’actionnable.

Voici un SKILL.md minimal que vous pouvez déposer dans ~/.hermes/skills/devops/backup-check/SKILL.md (ou dans n’importe quel dossier de catégorie) et itérer à partir de là.

---
name: backup-check
description: Vérifier que les archives de sauvegarde nocturnes existent, ne sont pas vides et passent un contrôle ponctuel de checksum sur le fichier le plus récent.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Chemin absolu vers le répertoire qui contient les archives de sauvegarde
        default: "/var/backups"
        prompt: Répertoire d'archive de sauvegarde (chemin absolu)
---

# Contrôle ponctuel de l'archive de sauvegarde

## Quand utiliser

Utiliser lorsque l'utilisateur demande de confirmer que les sauvegardes ont été exécutées, d'auditer l'archive la plus récente sur le disque, ou de capturer les fichiers de sauvegarde vides ou obsolètes avant une procédure de restauration.

## Référence rapide

- Le répertoire d'archive le plus récent est configuré sous `skills.config.backup_check.archive_dir` (défini via `hermes config migrate` si déclaré dans les métadonnées).
- Le contrôle par défaut utilise `ls` par mtime et `test -s` pour les fichiers non vides.

## Procédure

1. Résoudre le répertoire d'archive depuis la configuration de la compétence ou demander à l'utilisateur une fois si non défini.
2. Lister le fichier modifié le plus récemment correspondant au motif attendu (par exemple `*.tar.zst`).
3. Confirmer que le fichier existe, n'est pas vide, et enregistrer son chemin et sa taille pour la réponse.
4. Si un fichier de checksum existe à côté de l'archive, le vérifier avec l'outil documenté (par exemple `sha256sum -c`).

## Pièges

- Les fichiers vides peuvent avoir un mtime récent si un travail échoué a touché le chemin ; vérifier toujours la taille.
- Les chemins relatifs échouent lorsque le cwd du terminal n'est pas l'hôte de sauvegarde ; utiliser des chemins absolus dans la configuration.

## Vérification

L'utilisateur devrait voir le chemin de l'archive la plus récente, la taille en octets, et soit une ligne de checksum OK, soit une note explicite indiquant qu'aucun sidecar `.sha256` n'a été trouvé.

Révélation progressive en pratique

La révélation progressive est la différence entre une bibliothèque de compétences qui semble réactive et une qui brûle des milliers de tokens avant le premier message de l’utilisateur. Hermes parcourt trois étapes conceptuelles : un catalogue compact (noms et descriptions courtes), le SKILL.md complet lorsque la tâche correspond, et — seulement si nécessaire — une tranche d’un fichier de référence via les chemins skill_view. Supposez que le niveau zéro est tout ce que le modèle lira jusqu’à ce qu’il s’engage explicitement ; chaque phrase dans la description et le premier écran de texte du corps doit aider au routage, pas au storytelling.

Un plan pratique qui survit aux chargements partiels est Quand utiliser (déclencheurs en langage clair), Référence rapide (commandes, variables d’environnement, chemins de fichiers), Procédure (étapes ordonnées que l’agent ne devrait pas improviser), Pièges (modes de défaillance connus) et Vérification (à quoi ressemble un état « vert »). L’histoire narrative, les dumps de journal de changement des fournisseurs et les tableaux d’options de vingt lignes appartiennent à references/ avec des titres stables afin que l’agent puisse extraire une seule section.

Lorsqu’une compétence s’active, Hermes peut réécrire ${HERMES_SKILL_DIR} et ${HERMES_SESSION_ID} dans le corps afin que les lignes shell pointent vers le dossier installé sans chemins construits à la main. Les extraits shell en ligne facultatifs (!cmd``) peuvent injecter du contexte frais (branche actuelle, espace disque libre), mais ils s’exécutent sur l’hôte et restent désactivés sauf si skills.inline_shell est activé — traitez ce drapeau comme une frontière de confiance pour toute la source de la compétence, et non comme un simple commode.

Activation conditionnelle et hygiène du prompt

Les compétences peuvent montrer ou masquer en fonction des ensembles d’outils ou des outils existants dans la session actuelle. requires_toolsets / requires_tools verrouillent une compétence derrière des capacités qui doivent être présentes ; fallback_for_toolsets / fallback_for_tools font apparaître un chemin moins cher ou local lorsqu’une intégration premium est absente — la solution de repli DuckDuckGo lorsqu’une API de recherche web payante n’est pas configurée est l’exemple canonique.

Ces prédicats façonnent directement le bruit du prompt. Une règle requires_* trop stricte cache une compétence aux nouveaux venus qui n’ont pas terminé la configuration hermes tools ; une règle fallback_for_* trop lâche duplique la moitié de votre bibliothèque chaque fois que quelqu’un omet une clé API. Le compromis utile est de nommer les prérequis réels, de tester avec hermes chat --toolsets skills, et de basculer les clés ou les ensembles d’outils délibérément tout en observant si la liste des compétences respire comme vous le attendez.

Secrets, configuration et fichiers d’identification

Les secrets doivent être déclarés dans required_environment_variables. Hermes peut demander lors du chargement d’une compétence dans la CLI locale, persister les valeurs dans .env, et les passer dans les sandboxes terminal et execute_code sans streamer le secret brut dans la transcription du modèle. Les surfaces de chat refusent de collecter les clés en ligne et pointent plutôt vers hermes setup ou des modifications manuelles de .env — rédigez votre texte de compétence pour qu’il corresponde à ce comportement (dire aux utilisateurs *qu’*une clé est requise, et non de la coller dans Telegram).

Les préférences non secrètes — chemins par défaut, noms d’organisation, bascules de fonctionnalité — appartiennent à metadata.hermes.config. Les valeurs se résoluent dans skills.config à l’intérieur de config.yaml, apparaissent dans hermes config show, et arrivent dans le message de compétence comme des faits résolus afin que le modèle n’ait pas besoin d’ouvrir votre fichier de configuration en plein milieu d’une tâche.

Les identifiants en forme de fichier (JSON de jeton OAuth, clés de compte de service) sont mappés à required_credential_files. Lorsque ces fichiers existent, Hermes peut les monter en bind-mount dans Docker ou les synchroniser dans les jobs Modal ; les déclarer à l’avance évite le classique « le script fonctionne localement, échoue dans le sandbox ».

Scripts de support et dépendances

Le guide en amont pousse les auteurs vers des dépendances ennuyeuses : stdlib Python, curl, et les propres outils de Hermes (web_extract, read_file, terminal). Cela est moins une question de pureté que de reproductibilité — chaque pip install supplémentaire est une autre défaillance silencieuse lorsque l’agent s’exécute dans un conteneur propre.

Lorsque l’analyse JSON ou XML est fastidieuse, un court script sous scripts/ plus un chemin ${HERMES_SKILL_DIR} vaut mieux que de demander au modèle de réinventer des analyseurs à chaque exécution. Si vous avez vraiment besoin d’un package, indiquez la commande d’installation dans Procédure, répétez le symptôme de l’échec dans Pièges, et donnez une commande de Vérification qui échoue de manière explicite lorsque la dépendance est manquante.

Publication, installations via hub et confiance

Les compétences communautaires passent par le Skills Hub et les autres chemins de découverte listés dans le guide utilisateur — compétences officielles optionnelles, slugs GitHub, entrées skills.sh, index .well-known et URL brutes SKILL.md. Les installations sont scannées pour détecter des exfiltrations évidentes, des injections et des modèles destructeurs ; les niveaux de confiance vont de builtin (intégré) à community (communautaire), et certaines découvertes ne sont autorisées qu’avec --force tandis que les pires cas restent bloqués entièrement.

La forme du fichier SKILL.md n’est pas spécifique à Hermes ; les assistants centrés sur l’IDE utilisent la même idée de chargement progressif avec des découvertes et des déclencheurs différents. Compétences Claude et SKILL.md pour les développeurs : VS Code, JetBrains, Cursor est une lecture contrastée utile — la discipline du frontmatter et le « charger seulement quand pertinent » sont transférables, même lorsque l’installateur et le câblage des commandes slash diffèrent.

Les déploiements à l’échelle de l’organisation associent généralement un tap privé ou un dépôt Git partagé avec external_dirs pour un partage en lecture seule, tout en gardant la copie écrivable par l’agent sous chaque profil lorsque skill_manage est autorisé à muter les compétences sur place.

Dépannage et optimisation

Lorsqu’une compétence se comporte mal, parcourez cette liste de contrôle avant de réécrire le prose.

• Visibilité — Confirmez les prédicats platforms, requires_* et fallback_for_*. Une compétence qui « fonctionne sur mon Mac » mais pas en CI Linux est souvent une garde de plateforme.
• Collisions de noms — Les noms dupliqués entre les répertoires locaux et externes suivent la préférence locale. Renommez ou espacez de manière agressive.
• Structure de découverte — Un SKILL.md mal placé ou un mauvais dossier de catégorie peut faire disparaître la compétence de l’indexation entièrement.
• Charge de tokens — Si les sessions semblent lentes, raccourcissez les descriptions de niveau zéro, déplacez la profondeur dans references/ et dédupliquez les grands tableaux.
• Modifications de l’agent — Hermes peut créer, patcher ou supprimer des compétences via skill_manage. Traitez les compétences précieuses comme du code : révisez les diffs, exportez des instantanés et réinitialisez les compétences bundle délibérément lorsque les mises à jour dérivent.

Une boucle de régression serrée vaut mieux que de relire tout le fichier : hermes chat --toolsets skills -q "Utiliser le flux de travail <skill> pour <tâche concrète>" devrait montrer l’agent tirant le bon niveau de révélation avant qu’il n’improvise. S’il n’invoque jamais skill_view, votre texte Quand utiliser ou votre description ne correspondent probablement pas à la façon dont les gens formulent les demandes.

Les références officielles restent autoritaires pour les changements de comportement — le guide utilisateur Système de Compétences pour la sémantique du runtime, Création de Compétences pour les règles destinées aux auteurs, le Catalogue des Compétences Bundle pour les exemples à copier-coller, et la spécification agentskills.io pour le format de fichier partagé avec lequel Hermes s’aligne.