Demandez à une équipe pourquoi l'un de ses skills IA se comporte mal, et la réponse porte habituellement sur la formulation : l'instruction était trop vague, trop longue, trop insistante. Le guide d'Anthropic sur la rédaction de skills Claude, Skill authoring best practices (bonnes pratiques de rédaction de skills), consacre l'essentiel de son contenu à autre chose. Il traite de l'emplacement des fichiers d'un skill, de ce que le modèle charge à partir de SKILL.md et à quel moment, et des vérifications que le skill applique à sa propre sortie. Le 1er octobre 2026, nous avons audité nos 82 skills à l'aide de la liste de contrôle de ce guide. Presque tout ce qu'il y avait à corriger relevait de la structure, et le seul correctif qui valait la peine d'être automatisé est maintenant un hook (un déclencheur qui lance automatiquement un script après chaque modification).
Un skill (le nom de produit d'Anthropic est Agent Skills) est un dossier que le modèle charge pour une tâche précise : un fichier SKILL.md avec un nom, une description et des instructions, plus les fichiers de référence et les scripts dont la tâche a besoin. Les skills Claude s'exécutent dans Claude Code, sur claude.ai et par l'API, avec des limites différentes selon l'environnement.[1] Si votre équipe utilise plutôt des prompts enregistrés ou des assistants personnalisés, l'essentiel de ce qui suit s'applique quand même, à l'exception du dossier.
Le guide d'Anthropic sur les skills traite surtout de structure.
La page d'Anthropic sur la rédaction de skills repose sur un fait d'architecture : seuls le nom et la description de chaque skill sont chargés d'avance. Claude lit SKILL.md quand le skill devient pertinent, n'ouvre les autres fichiers qu'au besoin et exécute les scripts fournis sans en lire le code source : « Only the script's output consumes tokens. » (en anglais dans l'original, comme toutes les citations d'Anthropic ci-dessous, suivies d'une traduction libre : seule la sortie du script consomme des jetons).[1] Anthropic appelle cela la divulgation progressive (progressive disclosure). Presque chaque règle de structure de la page existe pour que cette lecture à la demande fonctionne.
SKILL.md lu quand le skill se déclenche · gardez-le sous 500 lignes, divisez avant d'y arriver SKILL.md, table des matières au-delà de 100 lignes · les scripts sont exécutés, pas lus : seule leur sortie coûte des jetons
Lisez la figure de haut en bas et les budgets s'expliquent d'eux-mêmes. La description est la seule chose que Claude voit avant de décider, et il décide parmi « potentially 100+ available Skills » (potentiellement plus de 100 skills disponibles) sur cette seule ligne.[1] Une fois le corps de SKILL.md chargé, chacun de ses jetons entre en concurrence avec la conversation, d'où la demande de le garder sous 500 lignes. Tout le reste attend sur le disque, « consuming zero context tokens until needed » (sans consommer aucun jeton de contexte tant qu'on n'en a pas besoin), ce qui ne fonctionne que si Claude peut le repérer à partir de SKILL.md.
La liste de contrôle qui clôt la page va dans le même sens, par sa forme. Nous avons trié ses 22 éléments selon ce que chacun vous demande de changer.
SKILL.md sous 500 lignes détails dans des fichiers distincts références à un seul niveau divulgation progressive barres obliques (/) seulement Six des 22 éléments portent sur les mots. Les seize autres portent sur l'emplacement des fichiers, sur ce que font les scripts et sur la façon dont le skill est testé. Le tri est le nôtre, et un lecteur pourrait déplacer un élément ou deux, mais aucun tri raisonnable ne fait de la formulation la majorité. La vidéo qui nous a menés à cette page se termine sur la même thèse : la plupart de ces correctifs touchent la structure et les vérifications, pas la formulation.[5]
Ce que la page dit des lectures partielles.
La page d'Anthropic fait un seul énoncé, restreint et prudent, sur les lectures partielles : lorsqu'un fichier est atteint par l'intermédiaire d'un autre fichier de référence plutôt que directement depuis SKILL.md, Claude peut en faire un aperçu avec une commande comme head -100 au lieu de le lire en entier. La version plus large qui circule, selon laquelle tout ce qui dépasse la ligne 100 n'est pas lu, ne figure pas sur la page; la vidéo qui nous y a menés s'ouvre là-dessus.[5] Voici la phrase de la page en entier :
head -100 to preview content rather than reading entire files, resulting in incomplete information. »[1] En français : Claude peut ne lire qu'une partie des fichiers lorsqu'ils sont référencés depuis d'autres fichiers référencés. Devant des références imbriquées, Claude pourrait recourir à des commandes comme
head -100 pour prévisualiser le contenu plutôt que de lire les fichiers en entier, d'où des informations incomplètes.
Trois formulations prudentes (« may », « might » et « like », soit « peut », « pourrait » et « comme ») et une seule portée : les fichiers atteints par l'intermédiaire d'un autre fichier de référence. Rien n'y dit que le contenu au-delà de la ligne 100 est ignoré, et rien n'y dit que cela arrive à tous les fichiers. Deux règles en découlent, et les deux valent la peine d'être suivies selon les termes mêmes de la page.
- Gardez les références à un seul niveau.
Faites un lien vers chaque fichier de référence directement depuis
SKILL.md, de sorte que rien ne se trouve au bout d'une chaîne où une prévisualisation partielle pourrait le tronquer. - Donnez une table des matières aux longs fichiers de référence.
Tout fichier de référence de plus de 100 lignes s'ouvre sur une table des matières. La raison d'Anthropic : « This ensures Claude can see the full scope of available information even when previewing with partial reads. » (cela garantit que Claude voit toute l'étendue de l'information disponible, même quand il prévisualise en lecture partielle).[1] Le seuil de 100 lignes est le chiffre de la page elle-même.
Le correctif est le même quelle que soit la version qu'on croit, de sorte que l'exagération fait peu de tort en pratique. Elle n'a d'importance que lorsqu'on cite l'affirmation comme venant d'Anthropic, ce qui n'est pas le cas.
Ce qu'a trouvé notre audit des SKILL.md.
Nous avons appliqué la liste de contrôle à notre propre boîte à outils le 1er octobre 2026 : 82 skills, en laissant de côté ceux qui sont synchronisés par la plateforme, que nous ne maintenons pas. Chaque constat ci-dessous est daté. La plupart portent sur la structure; les deux derniers portent sur les tests.
SKILL.md sous 500 lignes1 sur 82 dépasse : 682 lignes, dans un skill repris d'un projet externedivision à sa prochaine mise à jourSKILL.md sur 82 contiennent des chemins Windowslaissé tel quel, par choixLisez la colonne d'état avant les chiffres. Le constat qui a l'air le pire sur papier, 35 skills avec le mauvais type de chemin, est un constat que nous avons choisi de laisser. Celui qui a l'air le plus petit, un seul lien mort, pointe vers la lacune qui compte.
Le seul correctif à automatiser.
Le correctif de la table des matières a été adopté le 1er octobre 2026, jour de l'audit, et sous forme de code plutôt que de phrase. Nous avons ajouté rétroactivement une table aux 18 fichiers, corrigé la table périmée et écrit un petit script qui construit et vérifie la table des matières d'un fichier à partir de ses titres. Un hook l'exécute après chaque modification des fichiers de référence d'un skill et signale une table manquante ou qui n'est plus à jour (il avertit, il ne bloque pas). Le bilan de santé de notre boîte à outils exécute le même script, ce qui lui permet de détecter les modifications faites hors d'une session, comme une mise à jour en amont d'un skill repris d'un projet externe.[3]
Nous avons choisi un hook plutôt qu'une ligne dans le guide de style maison, parce qu'une règle qui doit tenir à chaque modification, dans chaque session, a sa place dans quelque chose qui s'exécute. C'est la leçon de notre note sur la documentation que les agents lisent vraiment : un fichier d'instructions est suivi souvent, pas toujours, et une vérification n'oublie pas. La page dit la même chose à l'échelle d'un skill. Son schéma de boucle de rétroaction est « Run validator → fix errors → repeat » (exécuter le validateur, corriger les erreurs, recommencer) et, dit-elle, « This pattern greatly improves output quality. » (ce schéma améliore grandement la qualité des résultats).[1]
Le lien mort est le prochain candidat. Un skill repris d'un projet externe avait été allégé pour ne garder que les fichiers que nous utilisons, et l'un des fichiers de référence restants pointait encore vers un fichier que l'allègement avait retiré. Rien ne l'a détecté, parce que rien ne vérifie les liens à l'intérieur des fichiers de référence. Un seul niveau de profondeur est une règle de structure, et la structure est exactement ce qu'un script peut vérifier.
Ce que nous avons choisi de ne pas corriger.
Deux constats sont restés ouverts exprès, et chacun a une raison que la page ne couvre pas.
Chemins Windows. Le 1er octobre 2026, 35 de nos 82 corps de SKILL.md contenaient des chemins de style Windows. La raison de la page pour les barres obliques est la portabilité : « Windows-style paths cause errors on Unix systems. » (les chemins de style Windows causent des erreurs sur les systèmes Unix).[1] Nos skills roulent sur un seul poste de travail Windows, où cette erreur ne se produit jamais. La règle commencera à compter le jour où un skill sera partagé, vendu à un client ou déplacé vers un serveur Linux, et c'est à ce moment que nous le convertirons. Réécrire 35 fichiers pour parer une défaillance qui ne peut pas se produire ici serait du travail pour rien.
Longueur de la description. Ici, nous sommes allés dans l'autre sens et sommes plus stricts que la page. La limite d'Anthropic pour le champ de description est de 1 024 caractères; notre plafond interne est de 400. Le maximum de la plateforme est une limite de validité, pas une longueur à viser. Le nom et la description de chaque skill installé sont chargés d'avance, et la page range « Other Skills' metadata » (les métadonnées des autres skills) parmi les éléments qui partagent la fenêtre de contexte avec chaque skill,[1] de sorte que chaque longue description prend la place de celle d'un autre skill. Quand nous l'avons mesuré le 6 août 2026, nos descriptions représentaient environ six fois la part de contexte que Claude Code accordait alors à la liste des skills.[4] Une description est une ligne d'index. Le corps peut être aussi long que la tâche l'exige.
Verrouillez les étapes qui touchent à l'argent.
La plus utile des idées de la page pour qui gère des opérations ne concerne pas du tout les fichiers. Elle porte sur le degré de précision avec lequel écrire chaque instruction, ce qu'Anthropic appelle les degrés de liberté (degrees of freedom), et elle lie la réponse à la fragilité de la tâche.
| Liberté | À quoi ressemble l'instruction | Exemple d'Anthropic | Où cela s'applique en entreprise |
|---|---|---|---|
| élevée | de la prose : un objectif et le contexte | une revue de code | rédaction, résumés de recherche |
| moyenne | un gabarit, ou un script avec paramètres | un rapport | un rapport client récurrent |
| faible | un script exact : « Do not modify the command or add additional flags. » (ne modifiez pas la commande et n'ajoutez aucune option supplémentaire)[1] | une migration de base de données | facturation, déploiements, tout ce qui envoie ou supprime |
L'analogie de la page oppose un pont étroit, avec des falaises de chaque côté, à un champ ouvert. Un même skill peut contenir les deux : l'étape de rédaction souple, l'étape qui publie ou qui facture verrouillée sur une commande exacte. La vidéo ajoute un test qui rend cela utilisable étape par étape : que se passe-t-il si Claude le fait autrement ?[5] S'il ne se passe pas grand-chose, assouplissez l'étape. Si l'écart coûte cher, verrouillez-la, de préférence dans un script plutôt que dans davantage de prose.
C'est aussi pourquoi une réécriture en lot des vieux skills est le mauvais réflexe, même quand une mise à niveau de modèle y pousse. Le guide de Fable 5 d'Anthropic dit bien que les anciens skills sont « often too prescriptive » (souvent trop prescriptifs); sa phrase suivante est « Review and consider removing older instructions if default performance is better. » (examinez les anciennes instructions et envisagez de les retirer si la performance par défaut est meilleure).[2] Le retrait attend une comparaison. Une passe qui retire chaque commande exacte et chaque étape d'approbation pour que les skills fassent plus moderne enlève les garde-fous sur les ponts étroits. Notre note sur la date de péremption des instructions couvre le volet formulation de cet audit; la présente note couvre la structure. Réécrivez un skill à la fois, en comparant une exécution avant et après.
La règle que nous avons le plus souvent sautée.
Le bloc des tests de la liste de contrôle est l'endroit où notre boîte à outils est la plus faible. La page est franche sur l'ordre : « Create evaluations BEFORE writing extensive documentation. » (créez les évaluations AVANT de rédiger une documentation étoffée).[1] Trouvez où Claude échoue sans le skill, construisez trois scénarios qui testent ces lacunes, mesurez la performance de Claude sans le skill comme base de comparaison, puis écrivez le minimum qui réussit. Peu de nos skills ont été construits ainsi.
La page associe les évaluations à une méthode de travail qui convient à une petite équipe. Une instance de Claude vous aide à rédiger le skill, une seconde l'utilise sur des tâches réelles, et vous rapportez les échecs de la seconde à la première. Elle demande aussi de tester sur chaque modèle que vous comptez utiliser, avec une question par palier : assez de consignes pour Haiku, clair et efficace pour Sonnet, pas sur-expliqué pour Opus. Et elle demande d'observer quels fichiers Claude ouvre réellement : « If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions. » (si Claude n'accède jamais à un fichier fourni, celui-ci est peut-être inutile ou mal signalé dans les instructions principales).[1] C'est aussi une vérification de structure, et peu coûteuse. Notre suite d'éval en 6 lignes est la même habitude, appliquée aux agents.
Ce que ceci ne prouve pas.
Notre audit compte la structure, pas les résultats. Nous savons quels fichiers enfreignaient quelles règles le 1er octobre 2026. Nous n'avons pas mesuré si leur correction a amélioré le travail des skills. La méthode de la page elle-même, des évaluations par rapport à une base de comparaison, est la façon de le savoir, et c'est l'étape que nous avons le plus souvent sautée.
Les chiffres sont datés. Ils décrivent notre boîte à outils au 1er octobre 2026. Des skills sont ajoutés et modifiés chaque semaine; remesurez avant de les citer.
La page n'a pas de date de révision. Rien n'y signale une règle comme nouvelle, de sorte que les affirmations du genre « Anthropic vient de changer les règles » ne peuvent pas être vérifiées à partir de la page. Ses questions par modèle ne nomment que Haiku, Sonnet et Opus, ce qui laisse penser, sans le prouver, qu'elle a été écrite avant la famille Claude 5. Ses règles de structure ne dépendent pas de la génération du modèle, et les guides de prompts de Claude 5 ne les contredisent pas.
Notre boîte à outils n'est pas la vôtre. 82 skills, une seule personne aux commandes, un seul poste de travail Windows. Une équipe qui aurait cinq skills partagés sur des machines variées classerait la règle des barres obliques bien plus haut que nous.
SKILL.md sous 500 lignes, chaque fichier de référence à un seul lien de celui-ci, et une table des matières sur tout fichier de référence de plus de 100 lignes. Verrouillez les étapes qui touchent à l'argent ou qui sont irréversibles. Transformez les règles qui doivent tenir en une vérification qui s'exécute. Et avant de réécrire quoi que ce soit, construisez trois cas de test et une base de comparaison : c'est la seule façon de savoir si la réécriture a aidé.
Si votre équipe fait rouler des skills IA, des prompts enregistrés ou des assistants personnalisés et que certains se comportent mal, le formulaire de contact est la voie la plus rapide. Dites-nous ce que vous faites rouler, et nous vous enverrons gratuitement un avis écrit sur l'endroit par où commencer.