Les compétences des agents sont un code : définissez leur portée, révélez-les, écrivez des scripts pour elles et testez-les.

Un fichier SKILL.md ressemble à de la documentation, mais le modifier change le comportement d’un agent. Cela le rapproche du code plutôt que de la prose, et il doit donc être conçu, délimité et testé en conséquence.

Les compétences ne sont pas de la documentation

La première réaction habituelle lorsqu’on veut créer une compétence pour un LLM est d’écrire davantage : expliquer l’architecture, ajouter des exemples, décrire les cas limites et fournir du contexte afin que le modèle comprenne pourquoi les choses fonctionnent de cette manière. Cette réaction est généralement erronée.

Une compétence n’est pas un manuel destiné à un développeur apprenant votre système. C’est plutôt du contexte injecté dans un agent qui s’efforce d’accomplir une tâche. Cette différence influence l’ensemble de la conception. La question pertinente n’est pas de savoir comment expliquer le système au modèle, mais plutôt ce que l’agent doit connaître pour prendre la bonne décision suivante.

D’un tel point de vue, plusieurs choix deviennent plus simples :

• Rédiger les instructions sous forme de procédures
• Préciser les conditions d’activation
• Chargement progressif des informations
• Transférer les tâches déterministes dans des scripts
• Tester les compétences sur des tâches réelles

Seulement des connaissances procédurales

Les agents de codage modernes gèrent déjà une quantité surprenante de tâches liées à l’ingénierie logicielle générale. Ils maîtrisent Git et npm, et comprennent Angular, React, TypeScript, SQL, les API REST, les frameworks de test ainsi que la configuration CI. Une compétence qui se contente de reproduire ces éléments ne contribue presque en rien :

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Cela consomme du contexte sans fournir quoi que ce soit qui manquait au modèle. Les compétences utiles permettent d’acquérir des connaissances propres à votre environnement :

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Ici, l’agent a appris quelque chose qu’il ne pouvait pas déduire de manière fiable de la documentation publique d’Angular, à savoir la manière dont les travaux doivent se dérouler dans un répertoire spécifique. C’est précisément ce pour quoi les compétences sont utiles.

Le format Agent Skills organise cela sous la forme d’un répertoire contenant un SKILL.md ainsi que des scripts et des ressources optionnels. Des métadonnées sont disponibles pour faciliter la découverte, et les instructions complètes ainsi que les fichiers de support ne s’chargent que lorsque c’est nécessaire. Le format de fichier n’est pas l’élément essentiel ; l’essentiel réside dans la distinction entre les capacités générales du modèle et les connaissances que votre environnement doit fournir.

Le contexte est une ressource limitée

Tout ce qui est fourni à un agent nécessite du contexte. Les descriptions d’outils, les schémas d’outils MCP, les instructions relatives au répertoire, l’historique des conversations ainsi que les descriptions de compétences en consomment tous, et le corps d’une compétence activée en consomme encore plus. Ainsi, la question n’est pas simplement de savoir si certaines informations sont utiles, mais plutôt si elles le sont pour la tâche en cours.

Supposons que ces compétences soient installées :

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Lorsque la tâche consiste à corriger un test unitaire Angular défaillant, l’agent n’a aucune raison de connaître le processus de déploiement ou les étapes de débogage de PostgreSQL. C’est pourquoi la découverte est presque aussi importante que le contenu. Comparez deux descriptions : celle-ci est extrêmement facile à déclencher :

---
name: testing
description: Helps run tests in our repository.
---

Celui-ci est bien plus précis :

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

La deuxième description va au-delà de la simple définition de la compétence : elle délimite un cadre qui empêche les instructions non pertinentes d’entrer dans le contexte de travail. Un exposé sur la conception des compétences pour les agents LLM illustre bien ce point : les métadonnées des compétences ne sont pas de simples éléments décoratifs administratifs. Des règles d’activation mal conçues font en sorte que des instructions utiles sont affectées aux tâches incorrectes, tandis que des règles trop restrictives empêchent même la découverte de la compétence.

La divulgation progressive vaut mieux qu’un SKILL.md gigantesque

Une erreur fréquente consiste à laisser SKILL.md se transformer en une petite wiki interne. Il commence avec vingt lignes, puis quelqu’un y ajoute des étapes de déploiement, ensuite des procédures de dépannage, puis des exemples, enfin des options de configuration. Trois mois plus tard, l’agent doit lire 1 500 lignes pour modifier un seul fichier.

Structurez-le plutôt comme on structurerait du logiciel :

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md ne contient alors que la logique de routage :

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

Les instructions de test détaillées n’apparaissent dans le contexte que lorsque une tâche implique des tests. Anthropic qualifie cela de divulgation progressive : l’agent charge d’abord les métadonnées, lit le corps principal une fois que la compétence s’avère pertinente, et ouvre les fichiers référencés plus tard, uniquement si nécessaire. L’objectif n’est pas de transmettre autant de connaissances que possible, mais de fournir les bonnes connaissances au bon moment.

Laissez les scripts appliquer ce qu’ils peuvent appliquer

Une autre distinction est utile : les instructions servent aux décisions, tandis que les scripts sont conçus pour des tâches déterministes. Imaginez une compétence qui stipule ceci :

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Un agent peut s’en charger, mais uniquement en inspectant à plusieurs reprises les dossiers, en interprétant les fichiers, en déterminant ce qui compte comme archivé, en suivant l’état et en effectuant probablement de nombreuses appels d’outils. Lorsqu’une opération peut être exprimée avec précision, écrivez-la une seule fois :

node scripts/check-angular-versions.mjs

Cette compétence indique simplement quand l’exécuter et quoi faire avec le résultat :

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

Cela présente des avantages à plusieurs égards. Le script peut être testé unitairement et se comporte de la même manière à chaque fois. Il nécessite moins de décisions de la part du modèle et souvent moins d’appels d’outils. De plus, en cas d’échec, on peut reproduire ce dernier sans devoir demander à un LLM de répéter son raisonnement.

Tout cela ne signifie pas remplacer les agents par des scripts. Cela signifie choisir la bonne abstraction. Utilisez le modèle pour le jugement, par exemple pour déterminer quels projets seront probablement affectés par un changement architectural. Utilisez du code pour des algorithmes précis, comme pour lister les projets qui importent un paquet donné. L’agent orchestre les deux, et cette combinaison est supérieure à l’encodage d’un flux de travail entier en anglais.

Les outils et les compétences résolvent des problèmes différents

Un outil fournit à un agent une action, tandis qu’une compétence lui apprend quand et comment utiliser ces actions. Un outil en ligne de commande peut par exemple offrir un moyen de calculer les projets affectés :

tr project affected --base main

Le outil fournit la capacité. La compétence correspondante fournit les connaissances de l’organisation :

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

La CLI ne comprend pas pourquoi cinq applications affectées devraient paraître suspectes, et le skill n’a pas besoin de savoir comment fonctionne la parcours des dépendances. C’est une frontière claire. La même distinction s’applique lorsque la capacité est fournie par une commande shell, une API web, un serveur MCP ou toute autre interface : ne cachez pas les politiques dans des outils de bas niveau sauf si c’est vraiment nécessaire, et n’écrivez pas d’algorithmes déterministes sous forme de texte narratif à moins que ce ne soit indispensable.

Avoir plus de skills n’est pas automatiquement mieux

Une approche tentante pour le développement d’agents consiste à collecter des skills qui semblent utiles, à les installer toutes et à supposer que l’agent devient ainsi plus capable. Les preuves suggèrent qu’il vaut beaucoup mieux être plus sélectif.

SkillsBench couvre 86 tâches réparties sur 11 domaines. Selon la première version de leur étude, les compétences sélectionnées ont augmenté en moyenne le taux de réussite de 16,2 points de pourcentage, avec de grandes différences entre les domaines. L’ingénierie logicielle n’a vu son taux s’améliorer que de 4,5 points, et 16 des 84 tâches ont obtenu de moins bons résultats une fois ces compétences ajoutées. Les compétences générées automatiquement par les modèles eux-mêmes n’ont apporté aucune amélioration moyenne.

SWE-Skills-Bench a examiné 49 compétences publiques appliquées à des tâches réelles d’ingénierie logicielle. Trente-neuf d’entre elles n’ont entraîné aucune amélioration du taux de réussite, et l’amélioration moyenne n’a été que de 1,2 point. Un petit nombre de compétences hautement spécialisées, au total sept, ont amélioré les résultats de jusqu’à 30 points. Trois autres ont eu un effet négatif, avec une baisse allant jusqu’à 10 points, car leurs indications visaient une version différente de celle utilisée dans le projet.

Cela correspond à ce que l’architecture pourrait prédire. Une compétence générale concurrence ce que le modèle connaît déjà, tandis qu’une compétence très spécifique peut fournir précisément le fait manquant :

When our generated API clients change, regenerate schemas before running typecheck.

Cela a de la valeur. Celui-ci en a beaucoup moins :

Always think carefully before modifying APIs.

Règle générale : ne créez pas de compétence simplement parce qu’une tâche existe. Créez-en une lorsque l’agent manque constamment de connaissances procédurales.

Les compétences nécessitent des tests

Ce pourrait être le plus grand changement conceptuel. Comme modifier SKILL.md a un impact sur le comportement, les conséquences ressemblent à celles des modifications de code :

• En supprimant une instruction, l’agent pourrait omettre une vérification obligatoire.
• En élargissant la description, la compétence pourrait s’activer lors d’une tâche non liée.
• En ajoutant un document de référence volumineux, l’utilisation des tokens pourrait augmenter sans améliorer les résultats.
• En réécrivant une procédure, le taux de réussite pourrait diminuer.

Il faut donc la tester. Pour une compétence gérant les migrations Angular, un ensemble d’évaluation pourrait inclure une tâche telle que :

Upgrade application A from Angular 20 to Angular 21.

avec de telles attentes :

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Une deuxième tâche :

Upgrade a shared library consumed by applications A and B.

avec ses propres attentes :

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

Et un troisième :

Modify a React application in the same monorepo.

dont le résultat attendu est l’absence d’activation :

Expected:
- Angular migration skill is NOT activated

Ce cas final compte autant que n’importe quelle exécution réussie, il faut donc tester les deux directions : la compétence devrait s’activer ici et ne pas s’activer là. Un outil nommé SkillGrade s’appuie sur cette idée. Définissez des tâches, exécutez l’agent à plusieurs reprises, puis évaluez chaque exécution en utilisant des vérifications précises, une grille d’évaluation basée sur un LLM appliquée à la session enregistrée, ou les deux ensemble. Vous pouvez appliquer ce principe même sans cet outil. L’important est de considérer une compétence comme quelque chose qui peut dégrader. Modifiez une compétence sans pouvoir déterminer si la nouvelle version est supérieure à l’ancienne, et vous modifiez alors de la logique en production sans l’avoir testée.

Partez des échecs, pas d’un marché des compétences

Le moyen le plus simple de créer des compétences inutiles est de se demander quelles compétences un agent de codage devrait avoir. Vous obtiendrez une liste de tests, de débogage, d’analyse de code, de documentation, d’architecture, de workflows Git, d’accessibilité, de sécurité et de vingt autres sujets que le modèle comprend déjà assez bien.

Un meilleur point de départ est l’historique propre de l’agent. Cherchez des échecs répétés. Peut-être que l’agent :

• exécute toute la suite de tests dans un énorme monorepo au lieu de se concentrer sur le projet concerné
• continue à enfreindre les limites des dépendances dans le répertoire
• emprunte la voie de migration techniquement valide mais rate une étape de compatibilité interne
• édite des fichiers générés au lieu des schémas qui les créent
• passe cinq minutes à redécouvrir chaque fois la même procédure de débogage lorsque un service échoue

Ces éléments indiquent des compétences à développer. Le cycle de vie se déroule ainsi : observer un échec répété, identifier les connaissances procédurales manquantes, rédiger la compétence la plus utile possible, intégrer les étapes déterministes dans des scripts, créer des tâches d’évaluation représentatives, mesurer les résultats, puis conserver, améliorer ou supprimer cette compétence. L’amélioration mène à sa réécriture.

Faites attention à l’option finale, car la suppression est une solution légitime. Une compétence qui ne modifie pas le comportement n’est pas inoffensive : elle ajoute du contexte, alourdit la maintenance et introduit une instruction de plus qui pourrait entrer en conflit avec d’autres éléments par la suite.

L’abstraction réelle, c’est le contexte contrôlé

Les gens décrivent souvent les compétences comme un moyen d’élargir les capacités des agents. C’est vrai, mais cela cache un problème d’ingénierie bien plus intéressant : fournir des informations à un agent est facile, mais décider quelles informations deviennent pertinentes au cours d’une exécution donnée est la partie difficile.

Un environnement d’agent bien conçu ressemble moins à un seul prompt géant et plus à un système logiciel composé de plusieurs couches. On y trouve toujours des connaissances générales du modèle ainsi que de petites instructions globales. Seules les compétences spécifiques à la tâche, les références chargées conditionnellement, les outils déterministes et le contexte du répertoire en temps de exécution sont mobilisés lorsque c’est nécessaire. Chaque couche a sa propre fonction. Si ces responsabilités se mélangent, le contexte s’en trouve surchargé au point que le comportement devient difficile à comprendre. En les séparant, les compétences deviennent agréablement simples, ce qui est positif.

Une bonne compétence n’est pas un prompt spectaculaire. C’est un petit ensemble de connaissances procédurales qui s’active dans les situations appropriées, fait appel aux outils déterministes chaque fois que c’est possible, et est vérifié pour détecter les échecs qu’il est conçu pour éviter.