Anthropic a enfin publié leur méthodologie interne des compétences

J’ai lu un article de blog écrit par l’équipe d’Anthropic intitulé « Lessons from building Claude Code: How we use skills ». C’est probablement la synthèse pratique la plus approfondie que j’aie vue jusqu’à présent sur le sujet des Skills.

Les Skills ne sont en réalité pas très compliqués, mais je pense que faire un bon Skill n’est pas si simple.

Je me souviens qu’à l’époque où les Skills ont commencé à devenir populaires, tout le monde aimait créer des Skills de style littéraire, de rédaction. On aurait dit qu’en y insérant simplement son propre style d’écriture, le modèle pouvait produire de manière stable dans ce style.

Mais après avoir expérimenté moi-même, j’ai constaté que souvent, ce n’était pas du tout faisable.

Car un Skill de style littéraire peut contenir quelques milliers, voire des dizaines de milliers de mots. Lorsqu’un Skill est chargé, le contexte occupe une grande partie de la mémoire. Avec un contexte lourd, la capacité de réflexion du modèle diminue souvent.

Il arrive fréquemment que : le style est bien appris, mais le contenu devient superficiel, et la capacité d’analyse s’affaiblit.

Il y a aussi un autre cas courant.

Beaucoup de gens, lorsqu’ils écrivent un Skill, aiment y insérer toutes sortes d’instructions opérationnelles : la première étape à faire, la deuxième, la troisième. Mais en pratique, cela rend l’exécution instable.

J’ai compris peu à peu que beaucoup de ces tâches répétitives sont en réalité mieux adaptées à être consolidées en scripts, plutôt que d’écrire de longues instructions.

Après avoir lu cet article d’Anthropic, ma plus grande impression est que beaucoup utilisent en fait des Skills, mais ne comprennent pas forcément leur véritable nature.

Au fond, un Skill consiste en une forme d’ingénierie du contexte. Quand faut-il mettre des connaissances dans un Skill, quand faut-il les diviser en références, quand faut-il écrire un script, quand faut-il utiliser des Gotchas pour contraindre le modèle, il y a beaucoup d’expériences derrière tout cela.

Une fois que l’on comprend le fonctionnement des Skills, en regardant ceux qui sont bien conçus, on se rend compte qu’ils ne résolvent pas tant le problème des prompts, mais plutôt celui du contexte, de la consolidation de l’expérience et de la réutilisation des capacités.

Si vous souhaitez approfondir la recherche sur les Skills, je recommande particulièrement deux articles :

#01 Ne pas écrire de bavardages inutiles

L’essence d’un Skill est la consolidation du « savoir tacite » au sein d’une organisation. Donc, dans un Skill, il ne faut pas répéter des connaissances évidentes déjà connues. Ce qui a vraiment de la valeur, ce sont les informations que le modèle ne connaît pas du tout.

Chez Anthropic, ils insistent souvent sur le fait que ce qu’il faut vraiment écrire dans un Skill, ce sont des Gotchas, c’est-à-dire des pièges courants.

Par exemple :

1. Ce tableau ne doit pas être trié par created_at

2. Un retour 200 de staging ne signifie pas forcément succès

3. request_id et trace_id sont la même chose

Car ces informations proviennent souvent de l’expérience des employés. Il faut donc bien se rappeler que la véritable nature d’un Skill est cela.

Un Skill, c’est simplement écrire l’expérience d’un maître expérimenté.

Grâce au Skill, on peut faire en sorte que l’expérience dispersée dans la tête de différentes personnes soit consolidée.

#02 Le Skill est en réalité de l’ingénierie du contexte

C’est probablement l’un des points de vue les plus profonds d’Anthropic.

Un Skill n’est pas un simple fichier markdown, mais un dossier. Pour ceux qui ont déjà utilisé des Skills, cela peut sembler évident ou même trivial.

Mais en y réfléchissant ces derniers jours, je me rends compte qu’ils veulent justement utiliser la structure de dossier pour exprimer leur concept d’ingénierie du contexte.

Reprenons la structure typique d’un Skill :

skill/  ├── SKILL.md  ├── references/ (détails, API, conditions limites)  ├── scripts/ (scripts exécutables)  ├── examples/ (exemples)  ├── assets/ (modèles, images, ressources fixes)

Lorsqu’on invoque un Skill, le modèle lit d’abord le fichier SKILL.md. Si on met toutes les informations dans ce seul fichier, cela peut rapidement faire exploser le contexte.

Supposons qu’il s’agisse d’un Skill de dépannage de paiement, contenant à la fois la description des codes erreur Stripe, des cas de panne historiques, des scripts de diagnostic et des modèles de rapport final.

Si tout cela est empilé dans SKILL.md, chaque fois qu’on invoque ce Skill, Claude doit tout relire.

Même si l’utilisateur veut simplement confirmer la signification d’un code erreur ou vérifier pourquoi un paiement n’a pas été mis à jour, beaucoup d’informations inutiles seront aussi chargées dans le contexte.

La philosophie d’Anthropic est totalement différente.

SKILL.md agit comme une page de navigation. Sa tâche est d’indiquer au modèle, lorsqu’il rencontre une erreur Stripe, d’aller consulter la référence appropriée dans le dossier references.

Quand il faut consulter des cas historiques, on regarde dans examples. Pour exécuter une action de diagnostic, on lance un script dans scripts. Et pour générer un rapport final, on utilise un modèle dans assets.

Tout ce processus est progressif et exposé de manière graduelle.

Voici une illustration très recommandée à sauvegarder.

#03 Favoriser l’utilisation de scripts

Il ne faut pas gaspiller la capacité limitée du contexte et la puissance de raisonnement du modèle dans des tâches répétitives. Ces tâches doivent être déléguées aux scripts.

Par exemple, beaucoup de personnes écrivent des Skills de cette façon :

1. Interroger les données d’inscription ; 2. Interroger les données de paiement ; 3. Calculer le taux de conversion ; 4. Analyser les causes d’anomalies.

Ce genre d’approche n’est pas problématique en soi. Le modèle peut le faire. Mais à chaque exécution, il doit refaire tout le processus d’analyse.

Interroger, organiser, gérer les cas limites, ces tâches sont répétitives.

Puisque ces capacités ont été validées maintes fois, pourquoi laisser le modèle tout réinventer ? Mieux vaut fournir directement un script précis.

De plus, en utilisant des scripts, l’exécution du Skill devient plus précise et consomme moins de tokens.

D’un point de vue organisationnel, les Scripts dans un Skill représentent en fait la consolidation des capacités de l’équipe. Chaque script est souvent le fruit d’expériences et de pièges évités, de bonnes pratiques accumulées.

En les solidifiant, Claude pourra toujours s’appuyer sur ces expériences, plutôt que de repartir de zéro à chaque fois.

Je pense donc de plus en plus que, dans un Skill, Instructions et Scripts répondent à deux niveaux différents.

Les Instructions apportent de l’expérience et du jugement, les Scripts apportent des capacités et des actions concrètes.

Par exemple, dans un Skill de dépannage de paiement, on pourrait avoir cette instruction :

Si Stripe retourne 200, ne pas considérer le paiement comme réussi, il faut vérifier la table payment_events.

C’est une Instruction, car c’est une expérience. La fonction check_payment_events() est un Script, car c’est une capacité d’exécution.

Si on n’a que le Script, le modèle sait comment faire la vérification, mais pas pourquoi.

Si on n’a que l’Instruction, il sait quoi faire, mais doit tout réinventer à chaque fois. Les deux sont indispensables.

#04 La Description comme une règle de routage

Beaucoup de gens écrivent la Description d’un Skill de façon erronée dès le départ.

Ils ont tendance à décrire ses fonctionnalités. Par exemple : « PR Management Skill aide à suivre l’état des PR, gérer les problèmes de CI, faire des merges automatiques. »

Mais le problème, c’est que le modèle ne cherche pas un Skill par ses fonctionnalités, mais par son nom et sa description.

Lors du lancement de Claude Code, il scanne tous les noms et descriptions de Skills pour décider lequel charger en fonction de la question de l’utilisateur.

Donc, la partie la plus importante de la Description n’est pas ce que fait le Skill, mais dans quelles situations il doit être chargé.

La Description joue en réalité un rôle de routage pour le Skill.

Dans le monde réel, personne ne dira : « Aide-moi à utiliser un outil de gestion PR. » La plupart du temps, on dira plutôt : « Surveille ce PR, le CI a planté, etc. »

Un bon Description doit donc décrire l’intention de l’utilisateur, plutôt que de lister des fonctionnalités.

Je recommande même une méthode simple pour vérifier cela.

Après avoir écrit la Description, supprimez tout le Skill, ne laissez que cette ligne. Demandez-vous : en voyant la question de l’utilisateur, le modèle peut-il deviner quand charger ce Skill ?

Si ce n’est pas évident, il faut continuer à l’améliorer.

#05 Gestion et distribution des Skills

Il reste aussi la question de la gestion des Skills.

Pour un utilisateur individuel, c’est simple : écrire quelques Skills, les maintenir, les mettre à jour soi-même. Mais je pense que la majorité des équipes seront confrontées à un problème similaire.

Quand le nombre de Skills passe de quelques-uns à plusieurs dizaines, voire centaines, comment gérer cela ? Comment faire évoluer ces Skills ? Comment les distribuer aux membres de l’équipe ?

Chez Anthropic, leur expérience est très instructive.

Dans une petite équipe, les Skills suivent directement le dépôt de code. Ils sont dans le dossier .claude/skills du projet. Tout le monde partage la même collection de Skills, la même méthode de travail.

Mais avec l’augmentation du nombre de Skills, un nouveau problème apparaît.

Lors du lancement de Claude Code, il scanne tous les Skills pour décider lequel invoquer. Plus il y en a, plus la gestion du routage devient coûteuse.

C’est aussi pour cela qu’Anthropic a commencé à créer un Marketplace. Mais ce qui est encore plus intéressant, c’est leur façon de gérer ce Marketplace.

Beaucoup d’entreprises réagissent en créant un processus d’approbation : chaque Skill doit être soumis pour validation, puis intégré dans la bibliothèque officielle. Nous avons aussi expérimenté cela, mais c’est lourd. Trop de gestion pour peu de valeur.

Chez Anthropic, leur organisation est beaucoup plus légère.

Ils laissent d’abord un Skill se diffuser à petite échelle, pour que des collègues l’installent et l’essayent eux-mêmes.

Si de plus en plus de personnes l’utilisent, cela prouve qu’il répond à un vrai besoin. À ce moment-là, l’auteur peut le soumettre au Marketplace officiel.

Ils ne discutent pas d’abord de la valeur du Skill, mais laissent d’abord le tester dans des scénarios réels. Plus il est utilisé, plus il devient officiel. Les Skills retenus sont donc ceux qui répondent réellement aux besoins de l’équipe.