Claude Code skills : capitaliser au lieu de réexpliquer

Lundi, vous avez expliqué à l'agent comment on déploie chez vous, quelle commande ne doit jamais tourner sur la base de production, et pourquoi le dossier de tests a cette structure bizarre. Jeudi, nouvelle session, il repart de zéro et vous recommencez. La plupart des gens en concluent que l'IA a mauvaise mémoire. Je crois plutôt que la répétition pointe un trou dans ce que le projet a mis par écrit.

Un skill, c'est une procédure que vous écrivez une fois et que l'agent retrouve tout seul au moment où elle s'applique, au lieu que vous la redonniez à chaque session. L'intérêt n'est pas d'économiser quelques minutes de frappe : c'est de sortir un savoir-faire de la tête de ceux qui le détiennent pour le poser dans le projet, où il devient relisible, versionné et discutable.

Ce que vous réexpliquez chaque semaine n'est pas aléatoire

Si vous notez pendant deux semaines ce que vous redites à l'agent, vous allez tomber sur une liste courte et étonnamment stable. Comment lancer la suite de tests sans attendre quarante minutes. La commande qui a l'air inoffensive et qui ne l'est pas. Le fait que l'environnement de recette ment sur un point précis, et lequel. La convention de nommage que personne n'a jamais écrite mais que tout le monde respecte. Ces quelques éléments reviennent parce qu'ils sont indispensables et qu'ils ne sont écrits nulle part : ni dans le code, qui ne porte que le résultat, ni dans la documentation, qui décrit l'outil générique et pas votre usage. Le détail qui m'a fait changer de regard sur le sujet, c'est que cette liste est presque exactement celle qu'on redit à une nouvelle recrue pendant son premier mois. L'agent n'a donc pas un problème de mémoire particulier : il révèle un problème de transmission que vous aviez déjà, et que vous payiez jusqu'ici en temps humain. Il le révèle chaque jour au lieu de deux fois par an, et ça finit par se voir.

Un skill est une procédure, pas un prompt bien tourné

La confusion la plus courante consiste à voir un skill comme un prompt qu'on aurait rangé quelque part. Ce n'est pas la même nature d'objet. Un prompt s'adresse à une situation : vous l'écrivez au moment où vous avez le problème, avec en tête tout le contexte que vous ne prenez pas la peine d'expliciter parce qu'il est évident pour vous. Une procédure s'écrit avant d'avoir le problème, pour quelqu'un qui n'a pas ce contexte. Elle décrit une séquence qu'on peut suivre, des points de contrôle, et un résultat qu'on peut vérifier. Si deux personnes qui l'appliquent n'obtiennent pas la même chose, ce n'est pas encore une procédure. Je ne détaille pas ici la forme exacte de ces fichiers, et c'est volontaire : le format a déjà bougé plusieurs fois, et une page qui donne la syntaxe du mois sera fausse avant d'être utile. Ce qui ne bougera pas, c'est la question de fond : qu'est-ce que votre projet sait de lui-même, et où est-ce écrit ?

Pourquoi ça se joue à l'échelle de l'équipe

C'est le point qu'on rate quand on découvre le sujet seul devant son écran. Un skill vous fait gagner du temps, c'est vrai, et c'est la raison la moins intéressante de s'y mettre. La vraie bascule est ailleurs : une procédure écrite est un objet qu'on peut relire, commenter, corriger et refuser. Elle a un auteur, une date, un historique de modifications. Quand deux développeurs ne sont pas d'accord sur la bonne façon de faire une chose, le désaccord devient une discussion en revue, avec un arbitrage et une trace, au lieu de rester deux pratiques divergentes qui cohabitent sans que personne ne le remarque pendant un an.

Et puis elle survit au départ de celui qui l'a écrite. C'est la différence entre un savoir-faire qui vit dans la tête de trois personnes et un savoir-faire qui appartient au projet. Les trois personnes finissent toujours par partir, changer d'équipe ou oublier, et ce qu'elles emportent n'est jamais visible au moment où elles l'emportent : ça se découvre six mois plus tard, quand plus personne ne sait pourquoi on fait les choses comme ça. C'est exactement la logique que je décris dans le monorepo comme mémoire du projet, appliquée ici à un grain plus fin : les procédures plutôt que les décisions.

Ce qui fait un bon skill, et ce qui en fait un mort-né

Trois choses, de terrain. La première : il décrit une procédure vérifiable, pas une intention. « Fais attention à la qualité » ne produit rien, parce que ça ne donne aucun moyen de savoir si c'est fait. La commande à lancer et ce qu'elle doit rendre, ça produit quelque chose. La deuxième : il dit ce qu'il ne faut pas faire autant que ce qu'il faut faire, et c'est souvent la partie la plus précieuse, parce que les interdits sont des cicatrices. Quelqu'un a payé pour chacun d'eux. La troisième : il porte les pièges rencontrés plutôt que la théorie du domaine.

Le mort-né le plus fréquent, c'est le skill qui paraphrase la documentation officielle. Il ne coûte pas rien : il occupe de la place dans le contexte de l'agent, il donne l'illusion que le sujet est traité, et il se périme pendant que la vraie documentation, elle, reste à jour. Si vous pouvez remplacer un skill par un lien, remplacez-le par un lien. Ce qui mérite d'être écrit chez vous, c'est précisément ce qui n'est écrit nulle part ailleurs, parce que c'est spécifique à votre code, à votre infrastructure et à vos habitudes.

Ce qu'une procédure écrite ne remplacera pas

Il faut dire la limite, parce qu'elle arrive vite. Une procédure capitalise une mécanique ; elle ne transmet pas un jugement. Le jour où vous commencez à figer dans un fichier des arbitrages qui demandent de comprendre le contexte, vous ne diffusez pas une compétence, vous installez un plafond : ceux qui appliquent n'ont aucune raison de comprendre pourquoi, et ils bloquent au premier cas imprévu. La règle que j'applique est simple à énoncer et pénible à tenir : on automatise ce qui est mécanique, on forme sur ce qui relève du jugement.

L'autre limite est une question d'entretien. Une procédure fausse est pire qu'une procédure absente, parce qu'elle sera suivie. Ce qui est écrit doit vieillir avec le projet, donc passer en revue quand le code change, et surtout être supprimé quand ça ne tient plus. Un lot de fichiers que plus personne ne relit redevient très vite du folklore, et je préfère cinq procédures tenues à jour que trente qui décrivent l'équipe d'il y a deux ans. La bonne nouvelle, c'est que la suppression coûte un geste et qu'elle se voit dans l'historique.

Le mot « skill » changera, le format aussi, probablement plusieurs fois avant la fin de l'année. Ce qui restera, c'est le constat qu'un agent ne peut utiliser que ce qui est écrit, et que ce critère est devenu un bon révélateur de la santé documentaire d'une équipe. Si vous cherchez le panorama complet, de la nature même de ce qu'est un agent IA jusqu'à la méthode de déploiement, le guide de l'IA agentique en entreprise rassemble tout au même endroit.