La doc d'Anthropic est claire : un SKILL.md, c'est moins de 500 lignes. Leur propre skill
docx en fait 590. J'ai lu les 17 skills officiels publiés par Anthropic,
frontmatter par frontmatter, en construisant mon propre marketplace à côté. À chaque fois,
le même écart : la doc dit une chose, le corpus en fait une autre. Et c'est le corpus qui
a raison.
Voici ce qui ressort vraiment quand on lit le code au lieu de la doc.
La description, c'est 90 % du skill
Un skill ne sert à rien s'il ne se déclenche pas au bon moment. Et ce qui décide du
déclenchement, ce n'est pas le corps du SKILL.md, c'est sa description dans
le frontmatter. Claude lit la liste des skills disponibles (juste nom + description) et
choisit. Tout le « quand l'utiliser » doit donc vivre dans la description, pas dans le corps.
Le contre-intuitif, qu'Anthropic répète dans son propre skill-creator : Claude sous-déclenche les skills bien plus qu'il ne les sur-déclenche. Il ne consulte un skill que pour une tâche qu'il ne sait pas faire trivialement. « Lis ce PDF » ne déclenchera jamais le skill PDF, même avec une description parfaite. D'où une consigne explicite : écrire des descriptions un peu pushy.
On le voit dans le code : le skill xlsx dit « Use this skill any time
a spreadsheet file is the primary input or output », pptx « any time a .pptx is
involved in any way ». Pas de timidité. On pousse le déclenchement, on ne le
retient pas.
La règle des 500 lignes que personne ne respecte
« Garde le SKILL.md sous 500 lignes » est l'une des règles les plus citées. Dans les faits,
docx fait 590 lignes, et la doc elle-même ajoute « feel free to go longer if
needed ». Les autres vont de 32 à 404 lignes. La vérité : 500 est une cible, pas une loi.
Le vrai principe derrière n'est pas la longueur, c'est le budget de contexte. Le corps du SKILL.md se charge à chaque déclenchement. S'il est gros parce qu'il contient l'essentiel, tant pis, on dépasse. S'il est gros parce qu'il traîne du détail qui pourrait vivre ailleurs, là c'est une faute. La taille seule n'est pas le péché.
Progressive disclosure : surtout des scripts, rarement des references
Le pattern central des skills, c'est le chargement en cascade : les métadonnées (nom +
description) toujours en contexte, le corps chargé au déclenchement, et les ressources
(scripts/, references/) seulement à la demande. Un script peut même
s'exécuter sans être chargé en contexte.
Sauf que dans le corpus, 11 skills sur 17 sont un seul SKILL.md, sans aucun
sous-dossier. Le découpage n'est pas la norme, c'est l'exception qu'on sort quand le
domaine le justifie. Et quand on découpe, c'est surtout des scripts/ :
pdf, docx, xlsx, pptx sont d'abord des
boîtes à scripts pour les opérations déterministes. Les references/ (de la doc
chargée à la demande) n'apparaissent que sur deux skills. La leçon : sors le déterministe en
code exécutable bien avant de sortir de la prose dans un fichier annexe.
Le « NOT for » qu'Anthropic n'écrit jamais
En écrivant mes propres skills, je mettais systématiquement une clause « NOT for X » dans la description, pour éviter les faux déclenchements. En lisant les officiels, surprise : ils ne le font quasiment jamais. Leurs descriptions listent des inclusions (« this includes… »), pas des exclusions.
La raison tient en un mot : leurs domaines ne se chevauchent pas. Le skill PDF et le skill Excel ne risquent pas d'être confondus, donc aucune exclusion n'est nécessaire, et ils préfèrent maximiser le déclenchement. Mon cas est différent : mes skills se touchent (relire un diff, livrer une feature, clôturer une branche sont adjacents). Le « NOT for » me sert à désambiguïser entre mes propres skills. Ce n'est donc pas une règle universelle, c'est une réponse au chevauchement. Si tes skills ne se concurrencent pas, n'en mets pas : tu ne ferais que réduire ton déclenchement, le pire des défauts.
Comment ils optimisent vraiment une description
La partie la plus instructive du skill-creator officiel, c'est qu'ils ne devinent pas une bonne description : ils la mesurent. Le protocole, déroulé :
- 20 requêtes d'éval : 8 à 10 qui doivent déclencher, 8 à 10 qui ne doivent pas. Réalistes et bordéliques, comme un vrai utilisateur taperait (chemins de fichiers, contexte perso, fautes, minuscules).
- Les négatifs sont des near-misses, pas des évidences. « Écris une fonction fibonacci » comme négatif d'un skill PDF ne teste rien. Les bons négatifs partagent des mots-clés avec le skill mais réclament autre chose.
- Chaque requête lancée 3 fois pour un taux de déclenchement fiable, puis une boucle d'amélioration sur 5 itérations.
- On choisit la description par son score sur un jeu de test tenu à l'écart (60 % entraînement, 40 % test), pour ne pas sur-apprendre les requêtes connues.
C'est un pipeline d'éval, pas du doigt mouillé. La plupart des gens écrivent une description au feeling et passent à autre chose. Anthropic la traite comme le produit.
En un coup d'œil : l'idée reçue contre la pratique
L'écart, ligne par ligne, sur les 17 skills officiels :
| L'idée reçue | Ce que fait le corpus officiel |
|---|---|
| Un SKILL.md fait moins de 500 lignes | docx en fait 590, et la doc ajoute « go longer if needed » |
| La description sert juste à dire quand utiliser le skill | Elle doit être pushy : le vrai risque est le sous-déclenchement |
On découpe en references/ et scripts/ (progressive disclosure) | 11 skills sur 17 sont un seul fichier ; quand on découpe, surtout des scripts/ |
| On restreint la description (« NOT for ») pour éviter les faux déclenchements | Quasi jamais écrit : domaines distincts, ils maximisent le déclenchement |
| Une bonne description s'écrit au jugé | Elle se mesure : 20 requêtes, chacune lancée 3 fois, boucle sur 5 itérations, score sur un jeu de test tenu à l'écart |
Ce qu'il faut retenir
La vraie leçon n'est pas dans la liste des règles, elle est dans l'écart. La doc donne des heuristiques propres ; le corpus montre comment des gens compétents les plient quand le terrain l'exige. Lire les 17 skills apprend plus que lire la page de doc, parce qu'on y voit les arbitrages réels : dépasser 500 lignes quand le contenu le mérite, sauter le découpage les deux tiers du temps, pousser le déclenchement plutôt que le restreindre.
Si tu ne retiens qu'une chose : le risque, ce n'est pas que ton skill se déclenche trop, c'est qu'il ne se déclenche pas du tout. Écris la description pour être trouvé.
J'ai construit un marketplace de skills Claude Code à partir de mon vrai workflow, en appliquant ces patterns. Tu peux les parcourir et les installer sur la page Skills, dont un skill skill-builder qui condense ces principes. Pour cadrer un agent, vois aussi les contextes CLAUDE.md.
Questions fréquentes
Combien de lignes pour un SKILL.md ?
Vise moins de 500, mais ce n'est pas une loi : le skill officiel docx en fait 590. Ce qui compte, c'est que le corps ne traîne pas du détail qui devrait vivre dans un script ou un fichier de référence. Dépasse si le contenu essentiel le justifie, en ajoutant alors des pointeurs vers des fichiers annexes.
Pourquoi mon skill ne se déclenche pas ?
Presque toujours la description. Claude sous-déclenche par défaut et ne consulte un skill que pour une tâche non triviale. Rends la description plus inclusive et « pushy » (« utilise ce skill dès que… même si l'utilisateur ne dit pas… »), avec de vraies phrases-déclencheurs. Et teste : une tâche en une étape ne déclenchera jamais un skill, c'est normal.
Faut-il des dossiers references/ et scripts/ ?
Pas par défaut : 11 des 17 skills officiels sont un seul SKILL.md. On découpe quand le domaine est lourd, et alors surtout en scripts/ pour le déterministe (manipulation de fichiers, validation). Les references/ ne servent que pour de gros domaines multi-variantes.
Skill, CLAUDE.md ou hook ?
Skill = une compétence déclenchée par sa description quand la situation s'y prête. CLAUDE.md = contexte toujours chargé pour un projet précis. Hook = automatisation déterministe sur un événement, imposée par le harnais, pas par le modèle. Si c'est « toujours faire X », c'est un hook ou un CLAUDE.md, pas un skill.