SKILL.md : créer une Agent Skill utile, déclenchable et testable

Un prompt répond à une situation présente. Une skill formalise un savoir-faire destiné à être retrouvé et appliqué dans plusieurs tâches. Son nom et sa description permettent à l’agent d’évaluer sa pertinence avant de charger les instructions complètes.

Une skill n’est pas non plus un outil. L’outil fournit une capacité d’action — lire un fichier, appeler une API, exécuter un test. La skill explique quand utiliser ces capacités, dans quel ordre, avec quelles limites et quelle preuve de réussite. Enfin, l’agent reste le système qui choisit, agit, observe et décide de poursuivre ou de s’arrêter.

La spécification Agent Skills impose un dossier contenant au minimum SKILL.md. Le fichier commence par un frontmatter YAML. name identifie la skill ; description explique à la fois ce qu’elle accomplit et les situations où elle doit être activée. Le corps Markdown contient les instructions que l’agent lit après activation.

Gardez ce fichier orienté décision. Placez les procédures longues ou les connaissances détaillées dans references/, les opérations déterministes dans scripts/ et les modèles réutilisables dans assets/. Ce chargement progressif évite d’occuper le contexte avec des ressources inutiles à la demande présente.

Commencez par le résultat attendu, puis décrivez les décisions dans l’ordre où elles surviennent. Une instruction comme « vérifier la qualité » est trop vague. Précisez les surfaces à inspecter, les signaux à rechercher, les commandes autorisées et la forme de la preuve finale.

Ajoutez les exceptions qui changent le parcours : fichier manquant, environnement non authentifié, sortie ambiguë, test impossible ou action destructive. Dites également ce qui ne doit pas être fait. Les limites explicites empêchent une procédure utile de devenir une autorisation générale.

La description est le principal signal de découverte. Elle doit nommer la capacité et les formulations de demande qui la rendent pertinente. Une description trop étroite rate des cas utiles ; une description trop large charge la skill sur des tâches qu’elle ne sait pas traiter.

Constituez deux petits corpus : des demandes qui doivent activer la skill et des demandes voisines qui ne doivent pas l’activer. Les faux négatifs révèlent un vocabulaire absent. Les faux positifs indiquent qu’il faut mieux décrire le périmètre ou réserver certaines variantes à une autre skill.

La validation syntaxique du frontmatter est nécessaire mais insuffisante. Exécutez la skill sur des cas représentatifs, vérifiez ses artefacts et comparez le résultat à des critères observables. Les scripts doivent avoir des entrées bornées, des erreurs lisibles et un comportement déterministe lorsque c’est possible.

Versionnez la skill avec ses exemples et ses tests. Lorsqu’une instruction change, rejouez les cas qui avaient motivé l’ancienne règle. Une skill fiable conserve aussi une sortie honnête : elle distingue ce qui a été vérifié, ce qui reste manuel et ce qui est bloqué par une permission ou un environnement absent.