Créer un skill Hermes Agent réutilisable

Introduction

Un skill Hermes Agent transforme une procédure répétée en instructions réutilisables, versionnables et chargées seulement quand la tâche l’exige. Il convient aux builders qui veulent stabiliser une revue de dépôt, un préflight éditorial ou une routine d’exploitation sans recopier un long prompt à chaque session. Ce guide montre comment choisir le bon périmètre, écrire SKILL.md, répartir références, scripts et templates, puis vérifier le déclenchement et le résultat. En revanche, ce n’est pas le bon choix pour mémoriser une préférence courte ni pour intégrer une capacité nécessitant une exécution native précise : une mémoire ou un outil sera alors plus simple.

Résumé rapide

1. Réservez le skill à une procédure récurrente qui mobilise des outils existants.
2. Écrivez un déclencheur explicite dans description, puis une procédure courte dans SKILL.md.
3. Déplacez le détail vers references/, la logique déterministe vers scripts/ et les formats vers templates/.
4. Testez le chargement et des critères d’acceptation observables sur un cas réel.
5. Relisez toute source tierce et accordez la priorité projet → local → externe.

Comprendre ce qu’un skill apporte à Hermes

Un skill est un document de connaissance à la demande. Il explique à Hermes quand appliquer une méthode, comment l’exécuter avec les outils disponibles, quels pièges éviter et comment vérifier le résultat. Il ne réentraîne pas le modèle et n’ajoute pas magiquement une capacité système. Il rend une méthode explicite, transmissible et reproductible. C’est ce caractère procédural qui distingue Hermes dans ce guide pour builders IA.

La progressive disclosure évite de charger toute votre bibliothèque dans chaque conversation. Au premier niveau, Hermes voit surtout le nom, la description et la catégorie des skills. Quand une tâche correspond, skill_view(name) charge le contenu principal. Une référence volumineuse n’est ouverte qu’au troisième niveau avec skill_view(name, path). Un guide de 300 lignes peut donc rester disponible sans occuper le contexte d’une demande sans rapport.

Il faut aussi distinguer trois couches :

Couche	Ce qu’elle conserve ou fournit	Bon exemple
Mémoire	faits durables et préférences courtes, utiles dans plusieurs sessions	« répondre en français » ou chemin d’un projet
Skill	procédure conditionnelle, critères et ressources chargés à la demande	préflight d’un article avant publication
Outil	action exécutable exposée avec un schéma d’entrée et un résultat	lire un fichier, lancer un terminal, appeler un navigateur

La mémoire des agents IA répond à « que faut-il garder en tête ? ». Les outils d’un agent IA répondent à « quelle action peut-il exécuter ? ». Le skill répond à « quelle méthode fiable doit-il suivre dans cette situation ? ».

Créez donc un skill quand le savoir tient dans des instructions, des commandes et des outils existants. Préférez un outil si l’intégration exige une authentification de bout en bout, du streaming, un traitement binaire ou une logique qui doit s’exécuter exactement de la même façon à chaque appel. Un prompt ponctuel reste suffisant pour une demande rare qui ne mérite ni maintenance ni partage.

Construire un skill à partir d’une procédure réelle

La bonne méthode ne commence pas par le YAML. Elle commence par une procédure qui a déjà produit un résultat et dont vous pouvez nommer l’entrée, les décisions, la sortie et les échecs connus. Nous allons prendre un fil rouge concret : le préflight d’un article MDX dans un dépôt. L’objectif du skill sera de lire un brief, contrôler la structure, exécuter les validateurs du dépôt, réparer le brouillon, puis ne conclure que lorsque tous les contrôles passent.

1. Réduire la procédure à un contrat

Avant d’écrire, formulez le contrat en une phrase : « À partir d’un article et de son brief, obtenir un brouillon conforme aux règles éditoriales et trois validateurs au vert, sans publier ni modifier d’autres fichiers. » Cette phrase fixe le résultat et les limites. Listez ensuite :

• les signaux d’entrée : chemin de l’article, chemin du brief, racine du dépôt ;
• les actions permises : lire, modifier le brouillon temporaire, lancer les validateurs ;
• les actions interdites : publier, déplacer le brief, écrire des secrets, changer la configuration ;
• les preuves attendues : trois codes de sortie nuls et les résumés ok: true ;
• les cas d’arrêt : brief absent, commande introuvable, conflit entre règles.

Cette étape empêche un défaut fréquent : documenter beaucoup de commandes sans dire quelle décision prendre après leur sortie.

2. Créer l’arborescence minimale

Un skill possède un fichier principal obligatoire et, si nécessaire, des ressources associées :

article-preflight/
├── SKILL.md
├── references/
│   └── editorial-contract.md
├── scripts/
│   └── run_checks.py
└── templates/
    └── report.md

Commencez avec SKILL.md seul. Ajoutez un sous-dossier seulement lorsqu’un contenu a une responsabilité claire. references/ accueille des règles détaillées consultées à la demande. scripts/ contient la logique déterministe ou répétitive qu’il serait risqué de réécrire à chaque run. templates/ conserve la forme d’une sortie. Cette séparation est plus efficace qu’un fichier principal énorme : elle réduit le contexte courant tout en gardant la profondeur disponible.

3. Écrire un déclencheur qui sélectionne bien

La description n’est pas un slogan. C’est la règle de routage visible avant le chargement complet. Elle doit commencer par le cas d’usage, employer les mots qu’un utilisateur emploierait et nommer le comportement attendu. Par exemple :

description: "Use when preflighting or repairing a repository article. Run its editorial validators, fix the temporary draft, and report verified PASS evidence."

« Helps with articles » est trop large : le skill risque de se charger pour une simple idée de titre. « Run validator X » est trop étroit : il manquera les demandes de réparation ou de préflight. Un bon déclencheur couvre les formulations naturelles tout en excluant les tâches voisines. Si la procédure exige des capacités précises, le frontmatter peut déclarer requires_toolsets: [terminal, file] afin que le skill soit masqué quand elles sont absentes.

4. Rédiger un SKILL.md orienté exécution

Voici une version centrale, suffisamment complète pour être testée sans devenir un manuel :

    ---
    name: article-preflight
    description: "Use when preflighting or repairing a repository article. Run its editorial validators, fix the temporary draft, and report verified PASS evidence."
    version: 1.0.0
    platforms: [linux, macos]
    metadata:
      hermes:
        tags: [editorial, mdx, validation]
        requires_toolsets: [terminal, file]
    ---

    # Article Preflight

    ## When to Use
    Use for a draft that must satisfy repository editorial gates before release.
    Do not publish, move briefs, or change repository state outside the draft.

    ## Procedure
    1. Read the brief, the draft, and the repository writing contract.
    2. Confirm the target path and allowed write scope.
    3. Run `python3 scripts/verify_article.py <article>`.
    4. Run `python3 scripts/editorial_intelligence.py <article> --brief <brief>`.
    5. Run `python3 scripts/editorial_quality_gate.py <article> --brief <brief>`.
    6. Fix the draft itself, then rerun all three checks after every repair.
    7. Stop only when each command returns success and reports `ok: true`.

    Load `references/editorial-contract.md` only when a structural rule fails.
    Run `python3 /absolute/path/to/skill/scripts/run_checks.py <article> <brief>`
    when all three checks should be executed together.
    Use `templates/report.md` for the final evidence report.

    ## Pitfalls
    - Never trust an estimated word count over the repository verifier.
    - Never repair only a report artifact while leaving the draft invalid.
    - Never broaden the write scope without explicit approval.

    ## Verification
    Confirm the final file path, all three exit codes, all three PASS states,
    and the verifier-reported word count.

Le frontmatter rend le skill découvrable et filtrable. Le corps porte l’ordre d’exécution. Les conditions d’arrêt évitent qu’Hermes annonce un succès après une vérification partielle. Au chargement, Hermes expose le chemin absolu du dossier du skill ; reprenez ce chemin pour appeler un script associé sans deviner son emplacement.

5. Appliquer la progressive disclosure

Le fichier principal doit contenir le chemin heureux, les limites de sécurité et la vérification finale. Il ne doit pas recopier tout le guide éditorial du dépôt. Placez dans references/editorial-contract.md les détails rarement nécessaires : liste exacte des champs, longueurs par type, exemples de messages d’erreur et stratégie de réparation. Hermes les chargera seulement si la situation le justifie.

Le script run_checks.py doit pour sa part enchaîner les commandes, préserver leurs codes de sortie et produire une synthèse machine-lisible. Écrivez-le en bibliothèque standard si possible. Ne cachez pas une décision éditoriale dans le script : le code mesure et agrège, tandis que SKILL.md explique comment interpréter puis réparer.

Le template de rapport peut imposer quatre lignes : fichier testé, validateurs, nombre de mots, limite restante. Grâce à cette distribution, la procédure courante reste courte, la logique sensible reste déterministe et la sortie reste cohérente.

6. Installer le skill au bon niveau

Pour une procédure propre à un dépôt, placez-la dans <project-root>/.hermes/skills/ ou <project-root>/.agents/skills/. Hermes demande de faire confiance au projet avant de charger ces instructions : depuis le dépôt, utilisez hermes skills trust. Cette précaution compte, car un SKILL.md cloné est une procédure que l’agent pourrait suivre.

Une procédure personnelle ou valable dans plusieurs projets appartient au profil local, généralement sous ~/.hermes/skills/. Des bibliothèques partagées peuvent être ajoutées avec skills.external_dirs dans config.yaml. En cas de collision de nom, la priorité actuelle est projet → local → répertoires externes. Le niveau projet gagne donc dans son dépôt, sans écraser la copie globale.

Pour découvrir et gérer des skills publiés, les commandes utiles sont notamment :

hermes skills list
hermes skills search preflight
hermes skills inspect owner/article-preflight
hermes skills install owner/article-preflight
hermes skills check
hermes skills update

Inspectez toujours avant d’installer. Un skill externe peut contenir des commandes destructrices ou une tentative d’exfiltration même si son intitulé semble anodin.

7. Tester le déclenchement avant de partager

Un test utile compare la même tâche sans et avec le skill. Préparez un brouillon volontairement imparfait : une section manquante, un compte de mots hors borne et un exemple trop mince. Dans la baseline, demandez simplement le préflight. Relevez les écarts : validations oubliées, mauvaise portée d’écriture, absence de second passage. Cette logique rejoint les tests de non-régression pour agents IA, mais avec des critères propres à la procédure.

Chargez ensuite explicitement la compétence Hermes Agent :

hermes chat --toolsets skills,terminal,file \
  --skills article-preflight \
  -q "Répare ce brouillon temporaire avec son brief et rapporte les preuves."

Vous pouvez aussi invoquer /article-preflight dans une session. Puis testez une formulation naturelle sans nommer le skill, car un bon déclencheur doit être sélectionné sur l’intention. Vérifiez enfin un contre-exemple, comme « propose trois titres d’article » : le skill ne devrait pas s’imposer.

Le test d’acceptation doit porter sur le résultat, pas sur l’impression que l’agent a « mieux travaillé ». Pour notre cas : le brouillon est le seul fichier modifié ; les trois validateurs retournent zéro et ok: true ; le nombre de mots vient du vérificateur ; aucune publication n’a lieu ; le rapport cite les preuves exactes. Rejouez ce test après chaque modification du déclencheur, du script ou du contrat éditorial. En production, conservez au moins le prompt de test, la version du skill, les sorties des validateurs et l’incident qui motive une correction. Cette petite observabilité réduit les régressions silencieuses ; des guardrails pour agents IA restent nécessaires pour encadrer l’exécution réelle.

Exemple concret

Une équipe produit chaque semaine des guides MDX. Avant le skill, trois personnes utilisaient trois prompts différents : l’une vérifiait la structure, une autre le maillage, la troisième lançait parfois le contrôle éditorial. Le résultat semblait correct, mais un article sur cinq revenait en revue pour un H2 en trop, une FAQ incomplète ou un exemple impossible à reproduire.

L’équipe crée article-preflight avec le SKILL.md ci-dessus. Elle ajoute dans references/editorial-contract.md les huit sections obligatoires et les bornes de longueur. Un script standard exécute les trois validateurs sans modifier le dépôt. Le template final exige le chemin, le statut de chaque commande et le nombre de mots annoncé par le vérificateur.

Le cas d’acceptation utilise demo-invalid.mdx. La baseline corrige la FAQ mais oublie de relancer le contrôle de structure. Avec le skill, Hermes lit d’abord le brief, limite l’écriture au brouillon, lance les trois commandes, corrige les deux échecs puis relance les trois validateurs. Le résultat attendu est explicite :

verify_article.py: exit 0, ok=true, words=2348
editorial_intelligence.py: exit 0, ok=true, score>=70
editorial_quality_gate.py: exit 0, ok=true, failed_count=0
modified_files: [demo-invalid.mdx]

L’équipe accepte le skill seulement si ces quatre lignes correspondent aux sorties réelles. Elle ajoute ensuite un test négatif : avec un brief absent, Hermes doit s’arrêter et signaler le blocage au lieu d’inventer les critères. Ce test prouve à la fois la reproductibilité et la sécurité du comportement. Il montre aussi pourquoi une longue consigne copiée dans un chat ne suffit pas : la valeur vient du contrat versionné, des ressources chargées au besoin et d’une preuve rejouable.

Bonnes pratiques

Gardez un skill étroit. S’il sert à rédiger, publier, surveiller et promouvoir un article, ses décisions deviennent difficiles à tester. Séparez les procédures qui ont des permissions ou des critères d’acceptation différents. Consultez les permissions des outils pour agents IA avant d’autoriser écriture, réseau ou commandes sensibles.

Traitez tout skill tiers comme du code à relire. Utilisez hermes skills inspect avant l’installation, vérifiez les scripts référencés, les variables d’environnement, les commandes shell et les destinations réseau. Les installations issues du hub passent par un scanner de sécurité, mais un scan ne remplace pas votre décision de confiance. N’inscrivez jamais de secret dans SKILL.md ; déclarez les variables requises et configurez-les localement. Pour un dépôt partagé, n’accordez la confiance qu’après revue, puis réévaluez les changements reçus. Cette discipline complète une démarche plus large sur la sécurité d’OpenClaw.

Enfin, versionnez les critères et maintenez une mini-checklist : déclencheur encore précis, chemin heureux court, références réellement utilisées, scripts testés, sortie vérifiable, permissions minimales. Une procédure rare et stable peut rester un simple document. Un skill mérite son coût de maintenance lorsque son usage répété réduit des erreurs observables.

Questions fréquentes

Qu’est-ce qu’un skill Hermes Agent ?

Un skill Hermes Agent est une procédure versionnée qu’Hermes charge à la demande. Son fichier SKILL.md décrit le déclencheur, les étapes, les pièges et la vérification. Il peut référencer des documents, scripts et templates. Ce n’est ni un réentraînement du modèle, ni un outil natif supplémentaire : il organise l’usage fiable des capacités déjà disponibles.

Comment créer un skill Hermes réutilisable ?

Pour créer un skill Hermes, partez d’une tâche répétée avec une sortie mesurable. Créez un dossier contenant SKILL.md, rédigez une description qui exprime clairement le cas d’usage, puis ajoutez une procédure et des critères d’acceptation. Déplacez les détails vers references/, les traitements déterministes vers scripts/ et testez la même demande avant et après chargement.

Où placer un fichier SKILL.md Hermes Agent ?

Placez un SKILL.md Hermes Agent dans .hermes/skills/ ou .agents/skills/ du dépôt pour une procédure propre au projet, après avoir approuvé ce dépôt avec hermes skills trust. Pour un usage personnel transversal, utilisez le répertoire local du profil. En cas de nom identique, Hermes applique la priorité projet, puis local, puis répertoires externes configurés.

Quelle différence entre un skill, une mémoire et un outil Hermes ?

La mémoire conserve de petits faits durables, le skill décrit une méthode chargée quand elle devient pertinente, et l’outil exécute une action selon un schéma défini. Un Hermes skills tutorial doit garder cette frontière nette : une préférence va en mémoire, un préflight va dans un skill, tandis qu’une intégration native d’API ou de navigateur relève d’un outil.

Articles liés

Un skill est rentable quand il transforme une méthode répétée en contrat testable, sans charger inutilement le contexte. Commencez par une seule procédure fréquente, utilisez-la dans une routine Hermes, puis étendez votre bibliothèque seulement après un test d’acceptation concluant. La comparaison avec les skills OpenClaw peut ensuite vous aider à situer cette approche dans un autre environnement d’agents.

• Hermes Agent : guide pour builders IA
• Diagnostiquer Hermes Agent par symptôme
• Mémoire des agents IA : principes et architecture
• Permissions des outils pour agents IA
• Skills OpenClaw : créer des procédures réutilisables