Rédaction de compétences pour l'agent Hermes — Structure du fichier SKILL.md et bonnes pratiques

Hermes Agent traite les compétences comme la méthode par défaut pour enseigner des workflows répétables. La documentation officielle les décrit comme des documents de connaissances à la demande alignés sur le format ouvert agentskills.io, chargés via une divulgation progressive afin que le modèle voie d’abord un petit index et ne charge les instructions complètes que lorsqu’une tâche en a réellement besoin.

L’écriture des compétences repose moins sur des formulations astucieuses que sur l’emballage — vous indiquez au runtime quand charger une procédure, quelle séquence d’étapes constitue « terminé », 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 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 de l’inférence, la récupération, la mémoire et les outils plutôt que comme une simple interface de chat. Les chemins d’installation, le câblage des fournisseurs, le comportement du gateway et la structure de ~/.hermes sont tous détaillés dans le guide Hermes AI Assistant - Installation, Configuration, Workflow et Dépannage}; l’ergonomie quotidienne en shell — hermes skills, profils, gateway, mémoire — est plus facile à consulter dans la Fiche de référence CLI Hermes Agent — commandes, options et raccourcis slash. Dans les déploiements réels, les compétences héritent de l’isolation des profils (configurations, secrets, mémoires et arbres de compétences séparés). Compétences Hermes AI Assistant pour des Configurations de Production Réelles plaide pour traiter ces profils — et non les fichiers markdown individuels — comme l’unité de propriété ; gardez cela à l’esprit lorsque vous nommez des compétences et décidez ce qui appartient aux external_dirs partagés versus un profil unique.

Compétence ou outil ?

L’orientation officielle est franche. Utilisez une compétence lorsque la capacité est principalement des instructions en prose plus des commandes shell et des outils qu’Hermes expose déjà — envelopper une CLI, piloter git, appeler curl, ou utiliser web_extract pour des récupérations structurées. Utilisez un outil lorsque vous avez besoin d’une intégration étroite pour les clés API et les flux d’authentification, le traitement binaire déterministe, le streaming, ou du Python qui doit s’exécuter de la même manière à chaque fois.

Cette frontière compte en pratique parce que les compétences se distribuent sans modifier le code de l’agent, tandis que les outils comportent un surcoût d’examen et de publication. La plupart des équipes bénéficient de commencer par une compétence, puis de promouvoir uniquement le cœur fragile vers un outil une fois les modes de défaillance évidents (boucles de rafraîchissement d’auth, parseurs binaires, idempotence stricte). Pour la question architecturale plus large de savoir quand utiliser une Compétence Agent versus un serveur MCP — notamment autour des identifiants, de l’état en direct et des écritures transactionnelles — consultez notre cadre décisionnel Compétences Agent vs Serveurs MCP.

Procédures versus mémoire curatée

Les compétences répondent au comment exécuter un workflow ; la mémoire centrale bornée d’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 rivaliser, et le tableau complet des snapshots, limites et fournisseurs externes est exposé dans Système de Mémoire Hermes Agent : Comment la Mémoire IA Persistante Fonctionne Réellement.

Anatomie d’un dossier 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 longues tables ou documents fournisseurs, templates/ pour les squelettes de sortie, scripts/ pour les helpers déterministes, et assets/ pour les fichiers statiques que l’agent ne devrait pas recharger.

Cette structure reflète comment fonctionne la divulgation progressive en pratique : l’agent peut rester au fichier principal jusqu’à ce qu’il ait réellement besoin d’un appendice approfondi. Garder le « chemin de succès » dans SKILL.md et déplacer les détails rarement utilisés vers references/ est l’un des moyens les moins coûteux de protéger les budgets de tokens.

Hermes peut également fusionner des dossiers 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, vos collègues qui tirent le même dépôt externe ne verront pas votre modification jusqu’à ce qu’ils suppriment ou renomment la copie locale — une source commune de confusion du type « ça marche sur ma machine ».

Frontmatter SKILL.md qui survit à l’examen

Le corps de SKILL.md est en Markdown ; le bloc d’ouverture doit être un YAML valide entre les délimiteurs ---. Les compétences réelles accumulent de longs exemples clôturés, donc les petites habitudes de Blocs de Code Markdown : Guide Complet avec Syntaxe, Langues et Exemples — tags de langue cohérents, extraits lisibles, clôtures serrées — maintiennent les grands fichiers maintenables pour les humains et légèrement plus faciles pour le modèle à parcourir.

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 la seule prose que beaucoup de sessions paient au niveau zéro, donc elle devrait ressembler à un résultat de recherche ou une chaîne de routage (« lorsque les sauvegardes semblent périmées, vérifier l’archive la plus récente et le checksum »), pas au premier paragraphe d’un article de blog.

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

Les réglages spécifiques à Hermes vivent sous metadata.hermes : tags, related_skills, et les champs de visibilité conditionnelle dans la section suivante. required_environment_variables déclare les secrets qui devraient 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.

La documentation officielle insiste sur la discipline de taille pour une raison. Réduisez la description à son budget, mettez en avant la procédure, et poussez les notes historiques ou les grandes matrices d’options vers references/ afin qu’un skill_view partiel donne toujours à l’agent quelque chose d’actionnable.

Ci-dessous se trouve un SKILL.md minimal que vous pouvez déposer dans ~/.hermes/skills/devops/backup-check/SKILL.md (ou 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 rapide 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 du répertoire contenant les archives de sauvegarde
        default: "/var/backups"
        prompt: Répertoire d'archives de sauvegarde (chemin absolu)
---

# Contrôle ponctuel des archives de sauvegarde

## Quand utiliser

Utiliser lorsque l'utilisateur demande de confirmer que les sauvegardes ont tourné, d'auditer l'archive la plus récente sur disque, ou de détecter des fichiers de sauvegarde vides ou périmés avant un exercice de restauration.

## Référence rapide

- Le répertoire d'archives 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'archives depuis la config 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 toujours avoir un mtime récent si un job échoué a touché le chemin ; vérifier toujours la taille.
- Les chemins relatifs cassent lorsque le cwd du terminal n'est pas l'hôte de sauvegarde ; utiliser des chemins absolus dans la config.

## Vérification

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

Divulgation progressive en pratique

La divulgation 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 utilisateur. Hermes parcourt trois étapes conceptuelles : un catalogue compact (noms et courtes descriptions), le SKILL.md complet lorsque la tâche correspond, et — uniquement 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 devrait aider le routage, pas le 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 le « vert »). L’historique narratif, les dumps de changelog fournisseur et les tables 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 pour que les lignes shell pointent vers le dossier installé sans chemins construits à la main. Les extraits de shell inline optionnels (!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 flag comme une frontière de confiance pour toute la source de la compétence, pas comme un commutateur de commodité.

Activation conditionnelle et hygiène du prompt

Les compétences peuvent apparaître ou se cacher en fonction des toolsets ou outils présents 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 — le fallback 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 juste milieu utile consiste à nommer des prérequis réels, tester avec hermes chat --toolsets skills, et basculer les clés ou toolsets intentionnellement en observant si la liste de compétences respire comme vous l’attendez.

Secrets, config et fichiers d’identification

Les secrets devraient ê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 distant refusent de collecter des clés inline et pointent plutôt vers hermes setup ou des édits manuels de .env — écrivez votre texte de compétence pour qu’il corresponde à ce comportement (dites aux utilisateurs qu’une clé est requise, pas *de la coller dans Telegram).

Les préférences non secrètes — chemins par défaut, noms d’organisation, toggles de fonctionnalité — appartiennent à metadata.hermes.config. Les valeurs se résolvent 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 pour que le modèle n’ait pas besoin d’ouvrir votre fichier de config en cours de tâche.

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

Scripts de support et dépendances

Le guide upstream pousse les auteurs vers des dépendances ennuyeuses : stdlib Python, curl, et les propres outils d’Hermes (web_extract, read_file, terminal). Cela a moins à voir avec la pureté qu’avec la reproductibilité — chaque pip install supplémentaire est un autre échec silencieux lorsque l’agent tourne dans un conteneur propre.

Lorsque le parsing JSON ou XML est délicat, un court script sous scripts/ plus un chemin ${HERMES_SKILL_DIR} bat la demande au modèle de re-dériver des parseurs à 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 défaillance dans Pièges, et donnez une commande de Vérification qui échoue bruyamment lorsque la dépendance est manquante.

Publication, installations hub et confiance

Les compétences communautaires transitent 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 URLs brutes SKILL.md. Les installations sont scannées pour une exfiltration évidente, injection et patterns destructeurs ; les niveaux de confiance vont du builtin au communautaire, et certaines découvertes ne se débloquent qu’avec --force tandis que les pires cas restent bloqués entièrement.

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

Les déploiements à grande échelle d’organisation appairent généralement un tap privé ou dépôt Git partagé avec external_dirs pour un partage en lecture seule, tout en gardant la copie writable 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 checklist avant de réécrire la prose.

• Visibilité — Confirmez les prédicats platforms, requires_* et fallback_for_*. Une compétence qui « marche sur mon Mac » mais pas en CI Linux est souvent un garde-fou de plateforme.
• Collisions de noms — Les noms dupliqués à travers les dossiers locaux et externes suivent la préférence locale. Renommez ou espacez les noms agressivement.
• Structure de découverte — Un SKILL.md mal placé ou un mauvais dossier de catégorie peut faire tomber la compétence de l’indexation entièrement.
• Charge de tokens — Si les sessions semblent lentes, raccourcissez les descriptions niveau zéro, déplacez la profondeur vers references/, et dédupliquez les grandes tables.
• Éditions par l’agent — Hermes peut créer, patcher ou supprimer des compétences via skill_manage. Traitez les compétences précieuses comme du code : examinez les diffs, exportez des snapshots, et réinitialisez délibérément les compétences bundled lorsque les mises à jour dérivent.

Une boucle de régression serrée bat la relecture du fichier entier : hermes chat --toolsets skills -q "Utiliser le workflow <compétence> pour <tâche concrète>" devrait montrer l’agent tirant le bon niveau de divulgation avant qu’il n’improvise. S’il n’invoque jamais skill_view, votre texte Quand utiliser ou description ne correspond probablement pas à la façon dont les gens formulent leurs requêtes.

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