Amélioration continue des agents grâce aux compétences : réutilisation, sélection, réparation et vérification.

Un agent de codage qui se heurte deux fois au même problème manque généralement d’un endroit fiable pour conserver ce qu’il a appris. L’idée derrière un plugin appelé Whetstone est que le travail effectué aujourd’hui doit améliorer celui de demain. Un outil que l’agent a écrit et testé devrait être disponible la prochaine fois. Un flux de travail nécessitant une correction doit aboutir à un changement durable que quelqu’un puisse examiner. Et avant que le résultat ne soit transmis, les vérifications nécessaires à cette tâche doivent déjà avoir été effectuées.

Ce sont des habitudes d’ingénierie ordinaires, mais elles restent souvent dans l’esprit de la personne et se répètent à la fin de chaque session. Whetstone les regroupe en quatre compétences qui s’appliquent aux autres compétences : réutiliser du code éprouvé, améliorer le mode de sélection des compétences, consigner les leçons procédurales, et vérifier la sortie avant de la renvoyer à l’utilisateur.

Le cadre retenu est celui des « agents auto-améliorateurs » au sens délibérément modeste. L’agent aide à améliorer ses propres instructions et outils, un humain examine les modifications et décide de ce qui devient permanent ; le modèle lui-même n’est pas réentraîné, et rien ne fonctionne en arrière-plan sans surveillance pour apprendre de manière autonome.

Un audit initial de 383 fichiers de compétences a fourni au plugin un terrain d’essai concret. Cependant, l’aspect le plus transférable reste la conception : où placer les éléments réutilisables, comment choisir l’intervention appropriée, et quels éléments de preuve exiger avant de valider une modification. Cette logique s’applique aussi bien au plugin qu’à une version conçue autour de vos propres workflows.

La partie d’un agent que l’on peut réellement améliorer

Une compétence est un dossier. Il contient un fichier SKILL.md contenant des instructions, ainsi que, éventuellement, des scripts et des documents de référence. La spécification ouverte Agent Skills définit un format standard, avec un nom et une description succincts en tête du fichier. L’équipe d’ingénierie d’Anthropic décrit les compétences comme un moyen de fournir aux agents polyvalents des connaissances réutilisables, et l’avantage réside dans le fait que l’on peut améliorer une procédure sans devoir reconstruire l’environnement de exécution.

Deux tâches distinctes sont impliquées : l’agent doit choisir la bonne compétence, et cette dernière doit ensuite guider efficacement le travail. Résoudre l’un des problèmes ne résout pas automatiquement l’autre.

Whetstone attribue à chacune de ses quatre compétences une seule responsabilité :

• dry-promotion permet de conserver du code réutilisable.
• skill-audit vérifie les informations utilisées pour sélectionner la compétence.

skill-repair propose des modifications procédurales.

verify-before-return vérifie le résultat.

Ce qui permet à cette séparation de fonctionner, c’est que chaque opération modifie un élément différent. Un outil d’aide peut mériter d’être enregistré même si rien n’a échoué. Une description vague peut nécessiter une attention supplémentaire alors que la procédure sous-jacente fonctionne parfaitement. Traiter chaque demande par l’intermédiaire des quatre opérations lierait des tâches non liées entre elles, tandis que des points d’entrée séparés permettent d’appeler uniquement la partie nécessaire à une tâche.

Chaque opération se termine par quelque chose que l’on peut consulter : un fichier sur le disque, un rapport d’audit, une différence suggérée ou des preuves de vérification. Cela facilite le débogage et donne à l’examinateur quelque chose de concret à valider. L’aide de l’agent est la bienvenue, mais une explication convaincante à elle seule ne rend jamais une modification permanente.

1. DRY : conserver le travail qui a déjà réussi

DRY signifie « ne vous répétez pas », et il s’agit également d’un agent qui inclut le code fonctionnel qu’il a généré précédemment. Lorsque chaque demande de présentation force une reconstruction du rendeur, celui-ci doit résoudre un ancien problème technique avant de traiter le nouveau contenu.

Le rendeur est l’élément réutilisable, tandis que le contenu est ce qui varie. La documentation d’Anthropic aborde ce sujet en mentionnant une compétence PDF qui exécute un script d’extraction préécrit : le code s’occupe de la partie mécanique stable, tandis que le modèle prend les décisions spécifiques à la tâche.

C’est là la fonction de dry-promotion. Il copie un outil utile dans le dossier scripts/ de la compétence et réécrit les instructions afin que le script soit exécuté. Enregistrer un fichier seul ne suffit pas : bien que la compétence demande toujours à l’agent d’écrire un script, rien ne lui indique celui qui a été enregistré.

Un compteur de caractères est un bon exemple dans un flux de travail d’écriture. Une sous-titre a une limite de longueur, et un petit programme peut calculer ce nombre tandis que le modèle se concentre sur la rédaction. La procédure peut inclure une instruction du type suivant :

Avant de renvoyer une sous-titre, exécutez le compteur de caractères enregistré. Lorsque le résultat dépasse la limite, raccourcissez le texte et recommencez le comptage. Ne tentez jamais de deviner le nombre, et ne récréez jamais le compteur.

Cela permet d’obtenir une implémentation fiable qui peut être examinée et testée. Cela ne rend pas tout le flux de travail déterministe, car la sous-titre elle-même peut encore varier, et un programme peut reproduire fidèlement une définition erronée. Le compteur doit déterminer s’il compte des points de code Unicode ou des caractères visibles, ainsi que la manière dont il traite les espaces et les sauts de ligne.

Préparez un outil d’aide avant de le promouvoir : supprimez les chemins liés à une session donnée, précisez les entrées requises, et testez-le sur des cas autres que celui qui l’a inspiré. Ensuite, exécutez à nouveau le flux de travail et vérifiez que le fichier enregistré correspond bien à ce qui est sollicité. Une exécution qui crée discrètement un autre compteur annule l’intérêt de la réutilisation, même si les chiffres finaux coïncident.

Le même principe s’applique aux modèles et aux références partagées. Lorsque plusieurs compétences partagent un contrat de sortie, conservez une version officielle et faites en sorte que les autres fassent référence à celle-ci. Ne forcez pas deux flux de travail véritablement différents à passer par un même outil d’aide simplement parce que leurs premiers exemples se ressemblent. La réutilisation doit permettre de maintenir un fonctionnement stable et ne pas masquer des différences importantes.

2. Aidez l’agent à choisir la bonne compétence

Avec la divulgation progressive, un agent commence par des métadonnées légères et ne charge les instructions complètes d’une compétence que lorsqu’il choisit cette compétence. La raison pratique est que charger toutes les procédures à l’avance consomme des ressources pour des tâches qui pourraient ne jamais être demandées.

Pour une sélection automatique, le nom et la description servent donc d’informations de routage. L’explication soigneusement rédigée vers le milieu du fichier peut même ne pas être disponible lorsque le modèle décide s’il doit l’ouvrir.

Les descriptions ne sont pas le seul moyen de sélection. Claude Code prend également en charge une invocation explicite, et la configuration en temps de exécution influence ce qui est disponible. Néanmoins, la description constitue le signal de sélection que l’auteur de la compétence contrôle.

En parcourant la bibliothèque de compétences d’une personne, en comptant les doublons portant le même nom à part des conflits, on a obtenu ce résumé :

383 skills scanned
  missing description           0
  no trigger language         306
  colliding pairs               3
  duplicate names              23
  skills with >=1 defect      306  (79%)

Les 79 % correspondent à une valeur tronquée de 306 divisé par 383, soit environ 79,9 %. Ces descriptions ont échoué au contrôle de formulation, ce qui n’est pas identique aux 306 cas d’échec observés concernant l’utilisation d’une compétence. Le scanneur ne vérifie que des formulations littérales comme « utiliser lorsque » ou « lorsque l’utilisateur ». Un modèle peut suivre une description ne contenant pas de telles expressions, et une description les contenant peut néanmoins être trop vague pour être utile. Le résultat fourni est une liste à examiner, et non une mesure de l’ampleur des dysfonctionnements de l’agent.

Attribuez des tâches différentes aux compétences voisines

Examinons deux descriptions réelles provenant de deux compétences au sein du même plugin :

L’un d’eux se présente comme un expert en création de systèmes de génération améliorée par la récupération d’informations, utilisant des bases de données vectorielles, des embeddings et des stratégies avancées de récupération. L’autre se présente comme un expert en sélection, configuration et ajustement de bases de données vectorielles telles que Pinecone, Weaviate, Chroma, Qdrant et Milvus pour la recherche sémantique et le RAG.

Les deux textes sont bien rédigés, alors lequel convient le mieux à un utilisateur qui a besoin d’aide pour choisir un stockage vectoriel pour une application RAG ? Un modèle compétent pourrait privilégier le second, dont les compétences sont plus ciblées, mais le premier prétend également posséder les mêmes compétences. Rien n’indique précisément ce que chacun maîtrise, ce qui oblige le modèle à déterminer lui-même les limites.

Des réécritures dans ce sens permettraient de tracer une frontière plus claire entre eux. Ils n’ont pas encore fait l’objet d’évaluations comparatives :

name: vector-database-selection
description: >-
  Compare vector databases against workload, filtering,
  deployment, and operating-cost requirements. Use when
  choosing or replacing a vector store. For retrieval-pipeline
  design with an already chosen store, use rag-pipeline-design.

name: rag-pipeline-design
description: >-
  Design ingestion, chunking, retrieval, reranking, and
  evaluation for a RAG application. Use when building or
  diagnosing a retrieval pipeline. For a standalone vector
  database selection, use vector-database-selection.

Le premier est responsable du choix de la base de données, tandis que le second s’occupe du chemin menant des documents au contexte utile pour obtenir une réponse. Une partie du vocabulaire reste commune, car les tâches se chevauchent réellement.

Rédigez d’abord les demandes de test avant de modifier le moindre mot. « Comparer les solutions de stockage vectoriel pour une application de recherche de documents auto-hébergée » concerne le choix de la base de données. « Où devraient être stockés nos embeddings ? Aidez-moi à décider » signifie la même chose sous d’autres mots. « Nous disposons déjà d’un système de stockage vectoriel, mais la récupération manque des paragraphes pertinents » relève du diagnostic du processus.

Ensuite, ajoutez une demande qui ne relève d’aucune des deux compétences, comme corriger l’espacement d’un bouton de recherche sur mobile. Sans cela, vous n’avez testé que laquelle des deux compétences l’emporte, et non si l’agent peut refuser les deux tâches.

Essayez-les dans des sessions nouvelles avec un modèle identique, des compétences activées et le même contexte de projet. Omettez le nom de la compétence visée dans tout test de sélection automatique, car son indication modifie l’expérience. Lorsque le système le révèle, notez quelle compétence a été chargée et conservez la réponse ou l’artefact généré. Un traceur indiquant le fichier qui a été ouvert constitue une preuve plus fiable que l’affirmation de l’agent selon laquelle il aurait utilisé la bonne compétence.

Comparez les résultats avant et après, et excluez certaines paraphrases de la session de réécriture afin de ne pas ajuster les paramètres uniquement en fonction de vos propres exemples. Cette petite suite de tests de régression permet de déterminer si un changement a été utile pour les requêtes importantes.

3. Transformer l’expérience en instructions réutilisables

Déceler un problème soulève une question plus utile : où doit se trouver la correction ?

skill-repair écrivait ses propositions sous forme de diffs à faire approuver par une personne, par rapport à une cible soumise à un contrôle de version. L’objectif est d’effectuer la modification la plus minimale possible pour corriger la panne observée, afin qu’un réviseur puisse la lire et la révoquer si elle endommage autre chose.

Imaginez une compétence de rédaction de rapports qui restitue un résumé sans consulter le document source. Lui demander de « faire plus attention » ne donne à l’agent que très peu d’éléments sur lesquels agir. La solution dépend de la raison pour laquelle la vérification a été omise :

• Le document source n’est jamais requis par la procédure : il faut modifier la procédure.
• Le document source est requis mais son emplacement n’est pas indiqué : il faut fournir ce contexte ou demander les informations manquantes.
• Le document source a été lu mais une figure a été copiée incorrectement : une autre vérification est nécessaire.

Un avertissement général collé dans tous les cas éviterait complètement le diagnostic.

Conservez la demande échouée ainsi que la modification proposée, décrivez le comportement attendu, et gardez l’élément qui a révélé l’échec. Relancez la demande dans une session nouvelle, puis essayez une demande similaire qui devrait encore fonctionner. Sinon, il est facile d’approuver un changement car il est présenté de manière convaincante, ce qui constitue un moyen confortable de passer l’après-midi sans améliorer quoi que ce soit.

Le champ d’application est également important. Une préférence concernant un rapport reste associée à ce rapport. Une règle pour chaque rapport généré par une compétence est intégrée dans cette compétence. Un fait qui change fréquemment convient mieux dans une référence que la compétence consulte. Si chaque correction se retrouve dans les instructions permanentes, une procédure réutilisable devient progressivement un simple journal de la dernière session d’une personne.

Les succès méritent la même attention. Lorsqu’une séquence fonctionne de manière fiable, il convient de conserver l’ordre utile, les entrées et les exemples, et non seulement les avertissements concernant les erreurs survenues. Les directives d’élaboration des compétences Agent Skills recommandent de fonder ces compétences sur des tâches réelles et de les affiner par leur mise en œuvre. Une compétence doit contenir les connaissances manquantes lors du prochain exécution, et non une transcription de tout ce qui s’est produit.

Lorsque le guide partagé a besoin de réparations

La bibliothèque d’une personne représente son propre enchevêtrement d’éléments, vérifié par ses propres outils ; c’est pourquoi la même vérification a été appliquée à un dépôt de plugins public géré par une équipe de logiciels de recherche universitaire. Dans cette capture d’écran, on y trouvait 76 compétences réparties sur 12 plugins.

Les drapeaux sont regroupés par plugin. Sept plugins ont été entièrement marqués, et un plugin scientifique en Python présentait quatre des cinq éléments marqués. Ce regroupement a conduit à la recherche de modèles et de conventions communs, et le guide de contribution s’est avéré être la source. Il demandait « une description claire de l’agent et de sa finalité » et proposait un modèle de remplacement indiquant ce que fait l’agent. Il ne demandait jamais quand l’utiliser. Trente-six compétences ont suivi le guide correctement, mais le guide lui-même constituait le défaut.

Deux problèmes publics auraient été ouverts, un pour le guide et un pour les 36 descriptions, et l’ordre est important. Mettez à jour la convention, donnez un bon exemple, et ce n’est qu’alors que vous devriez aligner les descriptions existantes. Sinon, le prochain contributeur suivra parfaitement le guide et réintroduira le même schéma.

Une vérification CI peut être utile, mais commencez par l’utiliser à titre consultatif. Si la règle ne connaît que quelques phrases déclencheuses, en faire une condition de validation stricte incite les contributeurs à coller ces phrases jusqu’à ce que la compilation réussisse, ce qui augmente le nombre de tentatives sans améliorer les compétences. Le véritable test d’acceptation nécessite toujours des demandes représentatives, y compris celles que la compétence devrait ignorer.

4. Vérifier avant le transfert

verify-before-return équipe une compétence de critères d’acceptation et d’un cycle de révision. Écrire un fichier sur le disque n’est qu’une étape intermédiaire, et le flux de travail doit encore examiner le résultat à l’aide d’éléments de preuve adaptés à la tâche :

• Pour un diaporama, il faut le rendre, puis vérifier s’il y a du texte coupé, des étiquettes illisibles ou des éléments en dehors de la zone de visualisation.
• Pour un rapport de recherche, ouvrez les sources et assurez-vous qu’elles soutiennent les affirmations présentées.
• Pour du code, exécutez des tests qui vérifient le comportement requis.

Toute affirmation selon laquelle le travail est terminé doit indiquer ce qui a réellement été vérifié.

Définissez ces critères avant de commencer la génération. Ensuite, faites en sorte que l’outil rédige un premier brouillon, inspecte le texte, corrige les erreurs et réexécute les vérifications affectées par ces corrections. Limitez le cycle de révision et exigez que tout problème non résolu soit divulgué, car l’idée de « continuer à améliorer » risquerait sinon de se transformer en une édition infinie sans résultat concret.

Les travaux subjectifs nécessitent une forme différente d’évaluation. Un débutant simulé peut signaler des termes inexplicables, et un lecteur sceptique peut remettre en question l’argumentation. Ces deux approches sont utiles, mais il s’agit toutes deux de critiques générées par un modèle et non de retours d’auditeurs réels ; évaluez donc chaque suggestion en fonction de l’objectif du texte plutôt que d’accepter toutes les objections. Le jugement concernant le goût et la stratégie reste entre les mains de celui qui a commandé le travail.

Effectuer une vérification n’est pas la même chose que l’effectuer correctement, et les tests effectués par l’auditeur montrent pourquoi.

Quels tests l’auditeur a modifiés

Les tests ont révélé que l’auditeur devait traiter les installations dupliquées et les descriptions superposées comme des constats distincts. La première série de tests a identifié 81 paires potentielles, dont beaucoup correspondaient à des compétences identiques présentes dans différentes versions en mémoire tampon du plugin. En examinant ces paires, les doublons portant le même nom ont été exclus de l’analyse des conflits, ce qui a réduit le nombre de paires potentielles à 3.

C’est pourquoi les données sous-jacentes à un résumé doivent être examinées avant toute modification. Les fichiers dupliqués nécessitent une vérification de l’inventaire, tandis que les descriptions concurrentes exigent un test de routage. Les regrouper ensemble conduit les gens vers la mauvaise solution de correction.

La séparation des noms dupliqués a également révélé 23 noms présents dans plus d’un chemin scanné. Les copies en mémoire cache ne prouvent pas que des versions anciennes étaient actives, ce qui nécessite de vérifier les plugins activés par le système et les chemins résolus. De même, le comptage de 383 fichiers indique des fichiers scannés mais pas des compétences uniques actives, et l’exclusion des comparaisons de noms identiques ne permet pas de dédupliquer l’ensemble de l’inventaire.

Le score n’est qu’une heuristique basée sur le vocabulaire : il s’agit du nombre de mots communs aux deux descriptions, divisé par le nombre de mots de contenu distincts entre elles, avec 0,35 comme seuil par défaut. Une exclusion peut ressembler à une superposition, et deux descriptions différentes d’un même poste peuvent passer inaperçues. Le parseur de frontmatter ne prend également en charge qu’un sous-ensemble de YAML. Toute indication nécessite une vérification humaine avant d’être transformée en correction.

Lorsqu’une réparation est validée, conservez le cas défaillant ainsi qu’un cas où la version ancienne fonctionnait déjà correctement. Ensemble, ils permettent de déterminer si une modification ultérieure corrige un comportement en en altérant un autre. Aucune amélioration globale du taux de réussite des tâches n’a été mesurée pour whetstone, et ce sont ces vérifications qui serviraient à l’évaluer.

Le packaging ne se déplace pas ; ce sont les compétences qui le font

Un objectif était de rendre whetstone utilisable en dehors de Claude Code. Le partage du format SKILL.md contribue partiellement à cet objectif. Une compétence peut encore dépendre d’outils, de permissions ou de chemins de fichiers que d’autres clients ne fournissent pas, et chaque client empaquette les plugins différemment. La norme Agent Plugins, la référence Claude Code ainsi que la documentation OpenCode décrivent ces structures.

Whetstone envoie les deux listes de manifeste depuis un même répertoire partagé skills/. La procédure est conservée en un seul endroit et l’intégration de chaque client est testée séparément. Les instructions portables ne rendent pas pour autant les modèles interchangeables ; exécutez donc la même tâche représentative sur un autre environnement compatible et vérifiez ses appels d’outils, ses dépendances et son résultat avant de supposer que le comportement est identique.

Essai sur un flux de travail

Aucune bibliothèque importante n’est requise. Choisissez un flux de travail, comme un outil d’aide que l’agent réconstruit constamment, deux compétences qu’il mélange, ou un résultat que vous finalisez habituellement manuellement. Conservez une demande représentative et son résultat pour comparaison.

Ensuite, choisissez l’intervention qui convient : réutiliser un outil existant, affiner la sélection, enregistrer une leçon procédurale, ou ajouter une vérification d’acceptation manquante. Comparez ensuite l’exécution suivante avec l’exemple enregistré. Un inventaire plus complet peut attendre, et un cache ancien ne doit pas être supprimé simplement parce qu’un balayage récursif a révélé des fichiers anciens.

Le projet est soumis à une licence MIT. Pour Claude Code, son fichier README indique les commandes d’installation suivantes :

claude plugin marketplace add cdcore09/whetstone
claude plugin install whetstone@whetstone

Quatre points d’accès sont exposés : /audit, /promote, /repair et /verify. Utilisez celui qui convient au flux de travail. Lors de la première tentative, il est judicieux de le laisser examiner les fichiers pertinents et proposer des modifications avant d’appliquer quoi que ce soit.

Pour étudier l’outil d’audit sans installer quoi que ce soit, clonez le répertoire, lisez skills/skill-audit/scripts/audit_skills.py. Depuis le sommet du répertoire, la commande ci-dessous le lance, et seule la bibliothèque standard de Python est utilisée :

python3 skills/skill-audit/scripts/audit_skills.py ./skills

Remplacez ./skills par le répertoire que vous souhaitez examiner, en commençant par une petite collection que vous reconnaissez avant d’analyser chaque cache de plugin sur votre machine. --json génère un rapport structuré, tandis que --threshold 0.25 affiche un ensemble plus large de descriptions superposées.

Le script ne lit que des fichiers et ne réécrit jamais les informations relatives aux compétences. Un statut de sortie égal à 1 indique la présence de drapeaux, de collisions entre candidats ou de noms dupliqués, ce qui n’est pas nécessairement dû à une panne de Python. Ses racines par défaut ne couvrent pas non plus le schéma d’installation de tous les clients ; donc, indiquer explicitement le chemin rend la portée plus claire et plus facile à reproduire. Si le rapport contient des descriptions de compétences privées ou des chemins de système de fichiers, conservez-le localement, et partagez uniquement les comptes et un exemple anonymisé à la place d’un inventaire des projets internes.

L’objectif est d’accumuler des travaux utiles : du code qui peut être réutilisé, des procédures qui peuvent être examinées, ainsi que des vérifications associées aux tâches. C’est un point d’entrée pratique pour des agents capables d’améliorer eux-mêmes, et qui restent sous contrôle de version. Toute personne dont le flux de travail nécessite une implémentation différente peut raisonner à partir de quatre questions : quoi réutiliser, quoi sélectionner, quoi apprendre, et comment vérifier le résultat.