Agent Skills : donner de vraies procédures à votre agent IA

Les Agent Skills sont des dossiers d'instructions que votre agent charge lorsqu'une tâche précise les réclame. Un skill transforme une consigne ponctuelle en procédure réutilisable, avec une entrée définie, un format de sortie, des sources autorisées et des cas d'échec.

Le minimum tient dans un dossier et un fichier SKILL.md. Le frontmatter permet à l'agent de reconnaître la tâche. Le corps lui dit ensuite comment l'exécuter. Des scripts, références ou modèles peuvent compléter ce fichier sans occuper le contexte avant d'être nécessaires.

Cette structure améliore la reproductibilité du travail, pas celle du monde extérieur. Deux appels suivent le même contrat, mais une page modifiée, un outil indisponible ou un modèle différent peut encore changer le résultat.

Un prompt n'est pas un skill

Un prompt demande un résultat maintenant. Un skill définit la méthode à réutiliser lorsque la même famille de tâches revient.

Prenez une demande courante : contrôler plusieurs pages avant leur publication. Le prompt ponctuel peut tenir sur une ligne.

Auditez ces URL et donnez-moi les problèmes SEO.

La consigne ne précise ni les champs à relever, ni la source à consulter, ni le traitement d'une URL inaccessible. Un premier appel peut parler du title et du H1. Un autre peut ajouter des conseils de contenu, ignorer une erreur HTTP ou proposer une balise absente. La tâche semble identique, mais le contrat change à chaque interprétation.

Le skill ne se distingue donc pas par sa longueur. Il se distingue par les décisions prises avant l'exécution. Il fixe, par exemple, qu'une balise absente vaut absent, qu'une donnée invérifiable vaut inconnu et qu'aucune valeur ne doit être devinée. L'agent garde moins de choix inutiles pendant la tâche.

La vidéo suivante montre ce passage d'une consigne générale à des procédures activées dans Hermes Agent. Elle permet de voir le rôle des skills dans un agent utilisé au quotidien.

Le format SKILL.md des Agent Skills

Un SKILL.md valide commence par un frontmatter YAML, puis contient des instructions en Markdown. Le fichier doit se trouver dans un dossier dont le nom correspond exactement au champ name.

La spécification Agent Skills définit deux champs requis et quatre champs facultatifs. Les ajouts propres à un client doivent rester identifiés comme des extensions, sinon un fichier accepté par un agent peut être refusé par le validateur d'un autre.

Le nom audit-urls-seo est valide si le dossier parent porte ce même nom. Audit_URLs_SEO ne l'est pas, car les majuscules et les tirets bas sont exclus. -audit-seo et audit--seo échouent aussi à cause du trait initial et du trait double.

Placez author et version sous metadata si vous voulez rester dans le format portable. La version doit être une chaîne YAML, par exemple version: '1.0'. Un champ version ou platforms placé à la racine peut appartenir à une implémentation, mais il ne fait pas partie des six champs du standard.

Le corps Markdown n'a pas de plan obligatoire. Il peut contenir des étapes, des exemples et des cas limites. Cette liberté n'excuse pas un fichier interminable : la recommandation officielle est de garder le SKILL.md principal sous 500 lignes et son corps sous 5 000 tokens. Le détail volumineux va dans references/.

Le validateur de référence contrôle le frontmatter et les conventions de nommage. Si vous avez installé cette bibliothèque depuis son dépôt, lancez-la depuis le dossier qui contient audit-urls-seo/.

skills-ref validate ./audit-urls-seo

Le champ description est le seul que l'agent lit toujours

Avec le nom, la description est toute l'information disponible avant l'activation. Le nom sert d'identifiant, tandis que la description porte le sens qui permet à l'agent de reconnaître la tâche.

Le chargement progressif explique cette priorité. Au démarrage, l'agent reçoit name et description pour chaque skill, soit environ 100 tokens de métadonnées par skill dans le modèle décrit par le standard. Il ne lit pas encore les étapes, les exemples ou les garde-fous du corps.

Lorsque la demande correspond, le corps complet du SKILL.md est chargé. Les fichiers de scripts/, references/ et assets/ arrivent seulement si la procédure en a besoin. Une documentation volumineuse peut donc rester hors contexte tant qu'aucune question ne réclame son chapitre.

La conséquence est directe : une section Quand l'utiliser écrite uniquement dans le corps arrive trop tard pour corriger un mauvais déclenchement automatique. Placez dans description la tâche, les formulations attendues et les exclusions qui séparent ce skill de ses voisins. Répétez ensuite les limites utiles dans le corps pour cadrer l'exécution ou une invocation manuelle.

Aide avec le SEO est une mauvaise description. Elle peut correspondre à un audit technique, une recherche de mots-clés, une rédaction ou une analyse de liens. Préférez une phrase comme : Audite les balises on-page d'une liste d'URL. À utiliser lorsque l'utilisateur fournit plusieurs pages à contrôler avant publication. Ne pas utiliser pour rédiger les balises ou analyser les backlinks.

Hermes documente le même chargement progressif avec ses propres outils. skills_list() renvoie l'index de métadonnées, autour de 3 000 tokens pour l'ensemble observé. skill_view(nom) charge le skill complet, puis skill_view(nom, chemin) récupère un fichier précis.

Les quatre parties qui rendent un skill fiable

Une procédure fiable fixe quatre éléments : l'entrée, la sortie attendue, les sources et les garde-fous. Ce plan n'est pas imposé par agentskills.io, mais il ferme plusieurs décisions qui créent des écarts.

1. Entrée. Indiquez ce que l'utilisateur doit fournir, le format accepté et la limite de volume. Sans ce contrat, l'agent peut corriger silencieusement une donnée mal formée, mélanger plusieurs tâches ou commencer avec une liste incomplète.
2. Sortie attendue. Nommez les colonnes, leur ordre, les valeurs de repli et le niveau de détail. Sans cette structure, deux exécutions peuvent produire des réponses impossibles à comparer ou à réinjecter dans un tableur.
3. Sources. Dites quelles données font autorité et lesquelles sont interdites. Sans cette frontière, l'agent peut compléter un HTML absent avec un extrait de moteur de recherche ou une supposition tirée du nom de domaine.
4. Garde-fous. Définissez les refus, les erreurs récupérables et les comportements à ne jamais adopter. Sans eux, une URL inaccessible peut disparaître du résultat, une valeur inconnue peut être inventée et un audit peut devenir une réécriture non demandée.

Ajoutez aussi une frontière négative au déclenchement. Un skill d'audit on-page ne doit pas s'activer pour écrire des balises, comparer des concurrents ou mesurer des backlinks. Cette exclusion évite qu'un skill voisin soit choisi pour la mauvaise étape du travail.

Un squelette complet pour auditer une liste d'URL

Le squelette suivant est prévu pour audit-urls-seo/SKILL.md. Il reste portable, décrit son déclenchement dans le frontmatter et refuse de transformer un constat en recommandation inventée.

---
name: audit-urls-seo
description: Audite une liste de 1 à 50 URL et restitue le statut HTTP, le title, la meta description, le H1 et les anomalies détectées. À utiliser lorsque l'utilisateur fournit plusieurs URL, demande un audit SEO on-page, cherche des balises absentes ou veut contrôler des pages avant publication. Ne pas utiliser pour rédiger des balises, analyser des backlinks ou comparer des concurrents.
license: MIT
compatibility: Requiert un accès réseau HTTP ou HTTPS et un outil capable de lire le HTML des URL à auditer.
metadata:
  author: feu-seo
  version: "1.0"
---

# Audit SEO d'une liste d'URL

## Objectif

Contrôler les balises présentes dans le HTML servi par chaque URL. Produire un constat reproductible dans sa structure, sans rédiger de remplacement ni extrapoler une donnée absente.

## Quand l'utiliser

Utiliser ce skill pour contrôler plusieurs pages avant publication ou relever des balises on-page absentes.

Ne pas l'utiliser pour rédiger des balises, analyser des backlinks ou comparer des concurrents.

## Entrée

Accepter une URL HTTP ou HTTPS par ligne, avec 50 lignes non vides au maximum.

Conserver l'ordre fourni. Ne pas corriger une URL mal formée.

Demander une nouvelle entrée si aucune URL n'est valide ou si la liste dépasse 50 lignes non vides.

Si l'accès réseau est indisponible, arrêter et signaler que l'exigence de compatibilité n'est pas satisfaite.

Si la liste contient au moins une URL valide, conserver les lignes invalides dans le résultat avec le problème "URL invalide".

## Procédure

Pour chaque URL valide :

1. Consulter uniquement la réponse de l'URL elle-même.
2. Relever le statut HTTP lorsqu'il est disponible.
3. Lire le texte de l'élément title.
4. Lire l'attribut content de la balise meta dont le nom est description.
5. Lire le texte du premier H1 et compter le nombre de H1.
6. Retirer les espaces au début et à la fin avant de compter les caractères.
7. Ajouter les anomalies observées dans la colonne Problème.

Après le traitement, signaler les titles et meta descriptions identiques entre plusieurs URL.

## Sortie attendue

Produire un tableau avec une ligne par ligne non vide fournie :

| URL | Statut HTTP | Title | Longueur title | Meta description | Longueur meta | H1 | Problème |
| --- | --- | --- | --- | --- | --- | --- | --- |

Appliquer ces valeurs :

- balise absente ou vide : "absent" ;
- donnée impossible à vérifier : "inconnu" ;
- H1 ambigu ou impossible à identifier avec certitude : "incertain" ;
- plusieurs H1 : conserver le premier et ajouter "plusieurs H1" ;
- réponse en erreur : conserver la ligne et indiquer le code HTTP dans Problème ;
- aucune anomalie détectée : "aucun".

Séparer plusieurs problèmes par un point-virgule.

## Sources

Utiliser uniquement le statut de la réponse et le HTML servi par l'URL auditée.

Ne pas consulter d'outil SEO tiers. Ne pas déduire une balise depuis le nom de domaine, l'URL, un extrait de moteur de recherche ou une page voisine.

## Garde-fous

- Ne jamais inventer une valeur manquante.
- Ne jamais proposer un nouveau title, une nouvelle meta description ou un nouveau H1.
- Ne pas appliquer de seuil idéal de longueur si l'utilisateur n'en fournit pas.
- Si le statut HTTP n'est pas accessible, écrire "inconnu".
- Si une URL ne répond pas, poursuivre avec les autres URL.

## Vérification

Avant de répondre, vérifier que le tableau contient autant de lignes que l'entrée contient de lignes non vides et que chaque cellule manquante porte explicitement "absent" ou "inconnu".

Ce fichier ne contient aucun champ racine propre à un client. author et version restent des chaînes sous metadata. Le nom correspond au dossier parent. La description couvre le quoi, le quand et les cas où le skill ne doit pas intervenir.

La sortie ne juge pas la longueur d'un title avec un seuil arbitraire. Elle compte et expose la valeur. Vous pouvez ensuite traiter le tableau avec des outils SEO gratuits ou une règle propre à votre site, sans confondre extraction et recommandation.

Où vivent les skills et comment ils sont chargés

Le standard impose seulement un dossier contenant SKILL.md. Les dossiers de scripts, de références et de ressources sont facultatifs et ne sont chargés que lorsque la procédure les réclame.

audit-urls-seo/
|-- SKILL.md
|-- scripts/
|-- references/
+-- assets/

Placez les automatismes exécutables dans scripts/, la documentation détaillée dans references/ et les modèles statiques dans assets/. Citez chaque fichier par un chemin relatif depuis la racine du skill. Gardez les références à un niveau direct : un fichier appelé par SKILL.md ne devrait pas obliger l'agent à suivre une chaîne de renvois.

Dans Hermes, ~/.hermes/skills/ est la source locale de vérité. L'implémentation accepte aussi templates/ et examples/. Les répertoires partagés se déclarent sous skills.external_dirs dans ~/.hermes/config.yaml, et la copie locale l'emporte lorsqu'un skill externe porte le même nom.

skills:
  external_dirs:
    - ~/.agents/skills

Un répertoire externe n'est pas une barrière d'écriture. Hermes peut modifier un skill qui s'y trouve si le processus possède les permissions nécessaires. Utilisez les permissions du système si ce dossier partagé doit rester en lecture seule.

Si vous voulez garder l'agent disponible en continu, séparez cette organisation du déploiement. Le guide pour installer Hermes Agent sur un VPS traite le service, l'utilisateur système et le fonctionnement permanent. Le skill reste un dossier de procédure, pas un service à lancer.

templates/, examples/, les bundles, platforms et metadata.hermes sont des possibilités d'Hermes, pas des exigences du standard Agent Skills. Gardez un noyau portable si le même dossier doit fonctionner avec plusieurs clients.

Les trois erreurs qui reviennent dans un SKILL.md

Ces trois échecs viennent d'un rôle mal défini, d'un silence sur les erreurs ou d'un périmètre trop large. Ils se repèrent avant même d'exécuter le skill.

Décrire un ton au lieu d'une tâche

Agissez comme un expert SEO rigoureux décrit une posture, pas une procédure observable. Remplacez ce rôle par des verbes et des objets : relever le HTML, extraire quatre champs, conserver les erreurs, produire huit colonnes. Le ton peut rester une consigne secondaire, mais il ne choisit ni les données ni la sortie.

Oublier le cas d'échec

Une procédure nominale paraît correcte jusqu'à la première URL invalide. Dites si l'agent refuse toute l'entrée, conserve une ligne d'erreur ou poursuit avec les autres éléments. Prévoyez aussi les données absentes et l'outil indisponible. Une valeur de repli explicite vaut mieux qu'une phrase plausible inventée pour remplir une cellule.

Tout mettre dans un seul skill

Un skill qui audite, rédige, publie et mesure les résultats possède plusieurs déclencheurs et plusieurs risques. Il sera chargé pour des demandes qui ne concernent qu'une étape. Séparez les tâches dont l'entrée, la sortie ou les permissions diffèrent. Si la même procédure a seulement besoin d'une documentation longue, gardez un skill et déplacez le détail dans references/.

Tester un skill avant de s'en servir

Testez séparément la forme, le déclenchement, le cas nominal et l'échec. Un seul exemple réussi ne montre pas si le skill sait refuser une entrée ou rester hors d'une tâche voisine.

1. Validez le dossier avec skills-ref validate ./audit-urls-seo. Corrigez chaque champ inconnu, nom non conforme ou différence entre name et le dossier.
2. Demandez un audit de plusieurs URL sans nommer le skill. Vérifiez qu'il s'active sur les mots et l'intention prévus dans description.
3. Demandez ensuite une rédaction de meta descriptions. Le skill d'audit doit rester inactif, car sa description exclut cette tâche.
4. Fournissez plusieurs URL accessibles. Contrôlez les colonnes, leur ordre, le nombre de lignes et les valeurs de repli.
5. Cassez volontairement l'entrée avec une URL mal formée, puis avec plus de 50 lignes non vides. Vérifiez que le comportement suit les règles écrites au lieu de réparer silencieusement la demande.
6. Rendez une donnée impossible à obtenir. La sortie doit afficher inconnu ou l'erreur prévue, sans compléter depuis une source interdite.

Refaites ce jeu de tests après chaque changement de description ou de garde-fou. Une modification du corps peut altérer la sortie. Une modification de la description peut changer quels appels chargent le skill, y compris ceux qui ne devaient pas le voir.

Installer un skill écrit par quelqu'un d'autre

Inspectez un skill tiers avant de l'installer, puis examinez ses instructions, ses scripts et les permissions qu'il suppose. Le fichier SKILL.md n'est pas exécuté comme un programme, mais il peut demander à votre agent de lancer du code et d'utiliser les accès de votre environnement.

La référence des commandes Hermes fournit browse, search, inspect, install, check, update, audit et uninstall. Commencez par une inspection avec un identifiant obtenu depuis le hub. N'installez qu'après avoir vérifié la provenance et les fichiers annoncés.

hermes skills inspect official/security/1password
hermes skills install official/security/1password

Tous les skills installés depuis le hub Hermes passent par un scanner. Il recherche notamment l'exfiltration de données, l'injection de prompt, les commandes destructrices et les signaux de compromission de la chaîne d'approvisionnement. Une copie manuelle ou un dossier déclaré dans external_dirs ne bénéficie pas automatiquement de ce passage.

Lisez la description, puis tout le corps. Ouvrez chaque fichier sous scripts/ et recherchez les dépendances, les écritures, les suppressions et les destinations réseau. Contrôlez aussi les chemins cités dans references/ et assets/. Le dépôt officiel Hermes Agent permet de comparer un skill présenté comme intégré avec sa source réelle.

Pour un environnement sensible, activez une revue humaine des écritures de skills. Hermes peut mettre les changements en attente sous ~/.hermes/pending/skills/ lorsque skills.write_approval vaut true. Cette barrière protège les modifications futures. Elle ne dispense pas d'examiner le skill initial et les outils auxquels votre agent a accès.