5 règles d'écriture du body SKILL.md cachées dans la doc Anthropic

Un Skill ne nécessite que deux lignes de YAML frontmatter pour exister. Mais la façon dont vous écrivez le body détermine entièrement la qualité du résultat.

Après avoir croisé la documentation officielle d’Anthropic et leur blog d’ingénierie, j’ai synthétisé les mécanismes de fonctionnement et les principes de rédaction du body en cinq règles. Ce travail de fond est parti d’un constat : mes propres Skills échouaient parfois au chargement, et j’ai profité d’un week-end prolongé pour tout vérifier depuis le début.

Sans comprendre l’ordre d’exécution des Skills, la conception du body déraille

Les Skills ne sont pas injectés dans la conversation comme un prompt. Au démarrage, seuls le name et la description sont chargés dans le prompt système.

Quand la requête de l’utilisateur correspond à la description, Claude utilise l’outil Bash pour lire l’intégralité du SKILL.md, puis charge les fichiers de référence et les scripts au moment où il en a besoin. Le blog d’ingénierie d’Anthropic appelle cette structure « divulgation progressive (progressive disclosure) ».

• Étape 1 : Seules les métadonnées (name + description) sont chargées en permanence. Environ 100 tokens par Skill.
• Étape 2 : Le body du SKILL.md entre dans la fenêtre de contexte uniquement lors du match.
• Étape 3 : Les fichiers des dossiers scripts et references sont chargés au moment de leur utilisation réelle.
• Lors de l’exécution d’un script, le code lui-même n’entre pas dans le contexte, seule la sortie est consommée.

Sans comprendre cette structure, vous remplirez le body d’informations inutiles tout en omettant ce qui compte vraiment.

Écrire « quand l’utiliser » dans le body gaspille des tokens

Beaucoup de gens ajoutent une section « When to Use This Skill » dans le body. Après avoir créé mes propres Skills, j’ai constaté que c’était totalement inutile. Le body n’est lu qu’après le déclenchement du Skill.

« Quand l’utiliser » doit figurer uniquement dans la description. Le repo officiel skill-creator d’Anthropic le précise explicitement.

• La description est le seul mécanisme de déclenchement (Claude ne consulte pas le contenu « quand utiliser » dans le body)
• La description est limitée à 1 024 caractères. Écrire à la troisième personne améliore la précision de détection.
• Le body doit contenir les règles de la tâche, les procédures et les formats de sortie attendus.
• Supprimez les phrases du type « Utilisez ce Skill quand… » du body.

Limiter le body à 500 lignes et séparer le reste

La première ligne du guide d’Anthropic affirme que la fenêtre de contexte est une ressource partagée. Une fois un Skill chargé, il partage les tokens avec l’historique de conversation et le prompt système.

La recommandation officielle est de garder le body sous 500 lignes et d’extraire le contenu détaillé dans des fichiers séparés. Le SKILL.md fait office de table des matières, et les fichiers de référence correspondent aux différents chapitres.

• Body inférieur à 500 lignes recommandé (indiqué dans les best practices d’Anthropic)
• Les fichiers de référence ne doivent être liés qu’à un seul niveau de profondeur depuis le SKILL.md
• Avec deux niveaux ou plus de références imbriquées, Claude risque de ne lire que les 100 premières lignes via head -100
• Ajoutez une table des matières en début de tout fichier de référence dépassant 100 lignes

Écrire en partant du principe que Claude est déjà intelligent

Expliquer ce qu’est un PDF dans le body gaspille des tokens. Il y a un principe que le guide d’Anthropic souligne à plusieurs reprises :

« N’écrivez pas ce que Claude sait déjà. »

Un exemple de code concis de 50 tokens surpasse une explication conceptuelle de 150 tokens. Sur la même tâche d’extraction PDF, le body concis a produit une précision nettement supérieure au body verbeux.

• Pour chaque phrase, demandez-vous : « Cette explication vaut-elle les tokens dépensés ? »
• Remplacez les explications conceptuelles par des exemples de code + formats de sortie attendus
• Classez la liberté de la tâche en trois niveaux (élevé/moyen/faible) pour calibrer l’intensité des instructions
• Fixez une liberté faible pour les tâches comme les migrations de base de données. Élevée pour les revues de code.

Intégrer des boucles de vérification dans le body pour améliorer la qualité

Exécuter → vérifier → corriger → re-vérifier. C’est le pattern de body le plus pratique recommandé par Anthropic. Intégrer des checklists dans le body réduit visiblement les chances que Claude saute des étapes.

Le guide officiel note également qu’un langage fort comme « MUST filter » obtient un meilleur taux de conformité que « always filter ».

• Détaillez les étapes en format checklist pour les tâches complexes
• Incluez des boucles vérification du script → correction d’erreur → re-vérification dans le body
• Utilisez « MUST » au lieu de « always », le taux de conformité de Claude s’améliore
• Rédigez des messages d’erreur spécifiques pour que Claude puisse s’auto-corriger

L’essentiel

La description détermine quand un Skill se déclenche. Le body détermine comment il s’exécute. Dès que vous mélangez ces deux rôles, le Skill ne se déclenche plus correctement et la qualité de sortie chute.

Un bon Skill est comme un bon document d’onboarding. Les documents les plus puissants partent du principe que le lecteur est déjà intelligent.