Agent Skills et SKILL.md : la divulgation progressive, mesurée

Le chapitre 14 a posé la règle pour la seconde moitié de ce cours — connexions, tentatives et annulation sont en TypeScript — et a déclaré cinq exceptions. Celle-ci en fait partie, et la raison n’est pas une préférence.

Un skill est un fichier Markdown. Pas un fichier qui configure un programme, pas un fichier qu’un programme compile : un document que le modèle lit, de la même manière qu’il lit le message que vous avez saisi. Donner un langage de programmation à ce chapitre reviendrait à ne pas avoir compris le format, et cette incompréhension est la plus courante à propos des skills. Tout ce qui suit est en Markdown et YAML, plus un petit script shell qui existe précisément pour montrer où le code a sa place, ou non, dans un skill.

Voici une vraie instruction : la façon dont une entreprise rédige ses notes de publication. C’est une procédure, pas une préférence — elle a un ordre d’étapes, une taxonomie, une voix, un modèle et un script qui collecte la matière brute.

Mettez tout cela dans le system prompt, comme le font la plupart des équipes, et l’arithmétique du chapitre 16 prend le relais. Un system prompt est un préfixe, et un préfixe se paie à chaque appel. Mesuré avec o200k_base sur le dossier écrit pour ce chapitre :

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

Vingt-quatre fois moins cher quand il est utilisé, trente-sept fois moins cher quand il ne l’est pas. Les tarifs sont ceux du chapitre 16 : 2,00 $ par million de tokens d’entrée.

Voici maintenant l’objection honnête, car un chapitre qui l’ignorerait serait de la publicité. Le prompt caching comble presque l’écart financier. Un system prompt est stable et placé en premier, ce qui en fait le meilleur candidat au cache possible ; à 0,20 $ par million pour l’entrée mise en cache, les mêmes 68 640 tokens coûtent 0,0168 $ au lieu de 0,1373 $. Cela reste trois fois le skill, mais ce n’est plus un ordre de grandeur différent.

L’argent n’a jamais été l’argument le plus fort. Le voici :

Le caching rend un préfixe permanent moins cher. Il ne le rend pas plus petit.

Au tour 40, la version en system prompt contient toujours 1 716 tokens de politique de notes de publication dans la fenêtre pendant une conversation sur tout autre chose, en concurrence pour ce que le chapitre 24 appelait le budget d’attention du modèle. La version skill en a 46. Mettez en cache la mauvaise chose et vous avez acheté une remise sur une distraction.

Écrit sous forme de formule, avec $n$ tours, $L_1$ les métadonnées, $L_2$ le corps, $L_3$ l’ensemble du bundle et $R$ l’ensemble des fichiers du bundle effectivement lus :

Tout ce chapitre tient dans la différence entre multiplier le second terme par $n$ et le multiplier par un ou par zéro.

Un skill est un répertoire. La spécification est assez courte pour être énoncée intégralement :

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md doit commencer par un frontmatter YAML, et exactement deux champs sont requis : name et description.¹ Quatre autres sont facultatifs et aucun autre n’est défini :

Voici le skill de notes de publication, complet, avec son corps sous les trente lignes :

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

Lisez ce qu’est ce corps. Ce n’est pas la politique — c’est une table des matières avec un ordre d’opérations. La politique vit dans trois fichiers qu’il nomme et n’inclut pas. Et la première étape délègue le travail à un script, car le code d’un script n’entre jamais dans la context window : seule sa sortie y entre.²

Le modèle de chargement a un nom et trois étapes. La spécification les énonce avec un budget de tokens associé :¹

1. Métadonnées, environ 100 tokens : name et description, chargés au démarrage pour chaque skill installé.
2. Instructions, recommandées sous 5 000 tokens : le corps SKILL.md, chargé quand le skill est activé.
3. Ressources, selon les besoins : fichiers inclus, chargés seulement quand quelque chose les exige.

La documentation de référence ajoute une quatrième colonne au même tableau — quand chargé, coût en tokens, contenu — et la ligne qui compte est la troisième : aucun jusqu’à l’accès.³ La phrase qui résume tout le chapitre s’y trouve aussi :

Les fichiers ne consomment pas de contexte tant qu’ils ne sont pas consultés ; les Skills peuvent donc inclure une documentation API complète, de grands jeux de données ou de nombreux exemples. Le contenu inclus mais non utilisé n’entraîne aucune pénalité de contexte.³

Le tableau mesuré au début de ce chapitre vérifie cette affirmation sur cinq skills que personne n’a écrits pour cet article. Deux lignes méritent d’être lues l’une contre l’autre.

next-best-practices a un corps de 966 tokens qui pointe vers dix-neuf fichiers contenant 19 374 tokens. Demandez-lui de corriger une erreur d’hydratation et l’agent lit le corps plus hydration-error.md : 1 409 tokens sur 20 340, un facteur quatorze, et les dix-huit autres fichiers ne sont jamais ouverts.

next-cache-components a un corps de 2 334 tokens et aucun fichier inclus. C’est un skill valide et bien écrit, mais il n’a pas de niveau 3 à divulguer. C’est la limite honnête de la technique : la divulgation progressive n’économise quelque chose que s’il y a quelque chose à différer. Un skill dont la connaissance ne se décompose pas paie tout son corps à l’activation, et le seul levier restant est de ne pas l’activer.

Le niveau 1 est une décision de routage prise à partir d’une phrase. Rien d’autre dans un skill n’influence le fait qu’il soit un jour ouvert — ni la qualité du corps, ni les exemples, ni les scripts. La description n’est donc pas une documentation. C’est la surface de requête, et elle peut être fausse.

La spécification le dit sous la forme d’un bon exemple et d’un mauvais, et le mauvais tient en quatre mots : description: Helps with PDFs.¹ Cela mérite d’être mesuré plutôt qu’accepté.

Six skills, chacun avec une description plausible qui dit ce qu’il fait et quand l’utiliser. Vingt-quatre requêtes, quatre par skill, formulées comme une personne les formulerait et sans jamais nommer le skill. Le modèle voit les six lignes dans son system prompt et doit répondre par un nom ou par NONE. Décodage greedy, donc il reproduit. Puis les mêmes vingt-quatre requêtes avec les mêmes six skills, mais les descriptions réduites à leur sujet brut.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

Lisez d’abord les intervalles, comme l’a exigé le chapitre 4 et comme le chapitre 29 l’exigera encore : ils se chevauchent, et vingt-quatre cas ne peuvent pas classer deux systèmes sur leurs seuls agrégats. La comparaison appariée tranche, avec l’instrument du chapitre 15 : sur les dix cas où les deux bras divergeaient, neuf sont allés aux descriptions riches et un aux descriptions minces. C’est établi au seuil habituel.

Lisez maintenant la dernière ligne, qui est le véritable résultat. Avec des descriptions minces, le modèle a répondu NONE à neuf requêtes sur vingt-quatre. Pas le mauvais skill : aucun skill. En voici quatre, verbatim :

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

Un skill sql-review parfait était installé, avec un corps, des exemples et une checklist, et il n’a jamais été ouvert, trois fois d’affilée, sur les trois questions pour lesquelles il avait été écrit. Les niveaux 2 et 3 sont sans pertinence pour un skill que le niveau 1 n’atteint jamais.

Le coût de la correction : 214 tokens, la différence entre 295 et 81, répartie sur six skills. C’est le résultat du chapitre 18 qui arrive par l’autre côté. Là-bas, modifier seulement la description d’un outil a fait passer le formatage de dates de 2 bonnes réponses sur 24 à 24 sur 24. Ici, modifier seulement la description d’un skill fait passer l’activation de 10 sur 24 à 18. Dans les deux cas, la correction la moins chère du système est une phrase, et dans les deux cas cette phrase doit nommer le déclencheur, pas seulement le sujet : non pas ce qu’est la chose, mais ce que l’utilisateur viendra de dire quand elle s’applique.

Une réserve que ce chapitre doit à ses propres standards. Il s’agit d’un modèle d’un demi-milliard de paramètres, et un modèle frontier route bien mieux que 75 %. Retenez le mécanisme, pas l’ampleur : le signal de routage fait une phrase quel que soit le modèle qui la lit, et aucun modèle ne peut sélectionner à partir d’une information que vous n’avez pas mise dans cette phrase.

Le second échec est l’inverse du premier. Le skill est trouvé, les niveaux sont correctement séparés, et l’agent lit quand même tout.

vercel-react-best-practices est un skill réellement bien construit. Son corps de 1 670 tokens est une table de priorités de huit catégories et une référence rapide nommant 70 fichiers de règles, une ligne chacun. Les règles sont sur disque à côté : 70 fichiers, le plus petit à 132 tokens, médiane 319, le plus grand à 1 052. Posez-lui une question sur les barrel imports et le coût honnête est le corps plus un fichier — moins de 2 400 tokens face à un bundle de 53 670.

Puis la dernière ligne du corps dit ceci :

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md fait 26 362 tokens. C’est la concaténation des 70 fichiers de règles : leur somme est 25 784, et la différence vient des titres entre eux. Le skill offre donc à l’agent le choix entre lire une règle médiane à 319 tokens et lire le même contenu, en entier, à quatre-vingt-trois fois le prix — et il propose ce choix dans une phrase sans coût attaché et sans condition indiquant quand le prendre.

Ce n’est pas un bug et le fichier n’est pas faux ; un document compilé est réellement utile à un humain, et à un agent auquel on a demandé d’auditer tout un codebase. C’est un fichier de niveau 3 avec une invitation de niveau 2, et la leçon dépasse ce skill : chaque chemin sortant d’un SKILL.md devrait dire ce qu’il coûte et quand il vaut la peine, parce que le modèle n’a aucun moyen de savoir qu’un nom de fichier est quatre-vingt-trois fois plus cher que le nom de fichier au-dessus.

Le même dossier porte une leçon plus petite sur l’obsolescence. Le corps dit « 70 règles dans 8 catégories » et en liste 70 ; le répertoire rules/ contient 72 fichiers, dont deux sont du scaffolding (_template.md et _sections.md) ; et le sidecar metadata.json dit « 40+ règles ». Trois décomptes du même ensemble dans un même dossier, l’un juste, l’un arithmétique, et l’un hérité d’une version antérieure. Un skill est un document, et les documents pourrissent exactement comme un commentaire de code qui s’est écarté du code qu’il accompagne — à ceci près que celui-ci est lu par une machine qui ne sourcillera pas.

La spécification ouverte définit six champs de frontmatter. L’implémentation de référence, Claude Code, en accepte vingt.² Cinq groupes méritent d’être connus par leur nom, car c’est là que le format cesse d’être seulement un document :

Arguments (arguments, argument-hint) permettent à une personne de passer des valeurs substituées dans le corps, ce qui rend un skill utilisable comme slash command. Scoping (paths) limite l’activation aux fichiers correspondant à un glob. Et l’injection dynamique de contexte est celle qui change le modèle mental : une ligne de la forme !`git diff HEAD` s’exécute avant l’envoi du corps, et sa sortie est substituée dans le texte. Le document est un template, et une partie est calculée au moment de la lecture.

Voici maintenant le piège, énoncé dans la même documentation : en dehors de Claude Code — dans le produit web, via la Skills API, dans le packaging — seuls les six champs spécifiés sont autorisés, et tout autre champ est une erreur bloquante à l’upload.² Un skill qui fonctionne parfaitement dans un produit échoue donc à s’installer dans un autre appartenant au même fournisseur, et il échoue au niveau du frontmatter plutôt qu’à quoi que ce soit que vous pourriez tester en lisant la prose. Si vous voulez qu’un skill soit portable, les six champs constituent tout le budget. Sinon, dites-le dans compatibility, qui existe exactement pour cela.

Quatre choses sont constamment confondues, et cette confusion n’est pas une pédanterie de vocabulaire : mal choisir coûte de l’argent à chaque tour, ou vous coûte une garantie que vous pensiez avoir.

Les deux lignes en gras sont toute la distinction. Un skill se lit ; un outil s’invoque. Un skill est de la prose qui arrive dans la context window et rivalise pour l’attention avec tout le reste ; le modèle peut la suivre, la mal lire ou l’ignorer, et rien dans le système ne le remarque. Un outil est un appel qui quitte entièrement les mains du modèle : votre code reçoit des arguments, les valide, vérifie les permissions et décide. Le chapitre 18 le formulait ainsi : le modèle propose et votre code dispose, et cette division est exactement ce qu’un skill n’a pas.

Donc, six cas réels, résolus :

L’histoire est courte, exceptionnellement bien datée, et c’est la partie que presque personne ne raconte.

Les Agent Skills ont été publiés le 16 octobre 2025 comme fonctionnalité d’un fournisseur, définis dans cette annonce comme des « dossiers organisés d’instructions, de scripts et de ressources que les agents peuvent découvrir et charger dynamiquement pour mieux accomplir des tâches spécifiques », avec les trois niveaux décrits par une analogie à conserver : « comme un manuel bien organisé qui commence par une table des matières, puis des chapitres précis, et enfin une annexe détaillée ».⁴

Le 18 décembre 2025, la même page a été mise à jour pour annoncer le format comme un standard ouvert, avec sa propre spécification à agentskills.io, une gouvernance ouverte aux contributions et un validateur de référence.³ Lu le 7 septembre 2026, le showcase client du standard liste quarante-six produits — éditeurs, terminaux, plateformes cloud et runtimes mobiles, y compris les coding agents first-party d’Anthropic, OpenAI, Google et Mistral — chacun pointant vers sa propre documentation de configuration.¹

La convergence avec MCP se fait au grand jour, avec des chiffres que vous pouvez vérifier :

La partie intéressante est la clôture, pas les propositions. SEP-2076 demandait une quatrième primitive à côté des outils, ressources et prompts. Le working group qui en est issu a décidé que la réponse était non : les skills voyagent sur la primitive resources qui existe déjà, comme extension opt-in.⁵ Le chapitre 26 mesurait le même instinct dans le changelog du protocole lui-même, où sampling, roots et logging ont été dépréciés plutôt que conservés. Un organisme de standardisation qui retire une proposition dont il est l’auteur se comporte bien, et la raison de raconter cette histoire avec les chiffres sous les yeux est que les résumés que vous lirez ailleurs décrivent encore les skills comme une primitive MCP.

Vous pouvez maintenant écrire un SKILL.md, le diviser en trois niveaux qui se paient eux-mêmes, lire le frontmatter du skill de quelqu’un d’autre et savoir quels champs ne survivront pas à un upload ailleurs, et répondre à la question autour de laquelle tout le chapitre a été construit — system prompt, skill, outil ou serveur — avec une raison plutôt qu’une habitude.

Ce que vous ne pouvez pas faire, c’est dire si le vôtre fonctionne.

Chaque affirmation importante de ce chapitre était une mesure, et la plus importante était une précision : 18 sur 24 contre 10 sur 24, avec un intervalle sur chacune et un test apparié entre elles, parce que deux agrégats qui se chevauchent ne décident rien. Cet instrument a été emprunté. La description d’un skill est une clé de routage, son corps est une procédure que le modèle peut suivre ou non, et ces deux propriétés ne se découvrent qu’en exécutant la chose de nombreuses fois et en notant ce qui revient — ce qui exige un golden set, un grader écrit avant l’exécution, et la métrique qui demande si cela a fonctionné à chaque fois plutôt qu’au moins une fois.

Le chapitre 29 est cela, et il s’ouvre sur le nombre dont dépend la méthode de ce chapitre : un agent qui réussit sept fois sur dix ressemble à 70 %, et son pass^10 — la probabilité qu’il réussisse les dix — est zéro. Il mesure aussi trois graders sur les mêmes deux cents transcriptions et obtient 0 %, 13 % et 26 % sans régénérer un seul token. Avant de faire confiance à la phrase que vous venez d’écrire dans un description, il vous faut l’instrument capable de vous dire qu’elle est pire que celle que vous avez remplacée.

Chaque décompte de tokens dans ce chapitre a été produit localement avec tiktoken 0.14.0 et l’encodage o200k_base, le 7 septembre 2026 : sur les cinq skills tiers listés au début de ce chapitre, et sur le skill release-notes écrit pour ce chapitre, dont le texte complet est reproduit ci-dessus en partie. Le niveau 1 est mesuré comme la ligne unique - name: description qu’un hôte rend dans le system prompt ; le niveau 2 est le corps SKILL.md après le frontmatter ; le niveau 3 est tout autre fichier du dossier. Les coûts utilisent les tarifs mesurés au chapitre 16 pour gpt-5.6-terra, 2,00 $ par million de tokens d’entrée et 0,20 $ par million de tokens d’entrée mis en cache, appliqués à ces décomptes — c’est de l’arithmétique sur des tokens mesurés, pas l’observation d’une facture réelle. Aucune API payante n’a été appelée pour écrire ce chapitre.

L’expérience d’activation a exécuté Qwen/Qwen2.5-0.5B-Instruct en demi-précision sur un GPU grand public, décodage greedy, 24 requêtes sur six skills, deux fois — une fois avec des descriptions indiquant ce que fait le skill et quand il s’applique, une fois avec des descriptions réduites à un sujet brut dans le style du « mauvais exemple » de la spécification. Les intervalles sont Wilson à 95 % ; la comparaison appariée est un test exact des signes bilatéral sur les dix cas discordants ; l’intervalle de Wilson est celui du chapitre 4 et le test exact apparié des signes celui du chapitre 15, tous deux réutilisés sans changement. Lisez les amplitudes comme une propriété d’un très petit modèle et la méthode comme transférable.

Les cinq skills mesurés ici sont des packages tiers, pas écrits pour ce chapitre : next-best-practices et next-cache-components depuis vercel-labs/next-skills, et vercel-composition-patterns, vercel-react-best-practices et vercel-react-native-skills depuis vercel-labs/agent-skills. Leurs décomptes internes — 70 fichiers de règles, AGENTS.md à 26 362 tokens, metadata.json daté de janvier 2026 et affirmant « 40+ règles » — ont été lus dans les fichiers sur disque le 7 septembre 2026 et sont des propriétés de cette version publiée, pas des critiques de leurs auteurs : chacun d’eux est le type de dérive qui apparaît dans tout arbre de documentation modifié plus souvent qu’il n’est compté.