Comment écrire un bon skill Claude Code : les 7 règles officielles d’Anthropic

TL;DR — les 7 règles en une minute

• Concision : le contexte est un bien commun. N’ajoute que ce que Claude ne sait pas déjà.
• Degré de liberté : instructions strictes pour le fragile, liberté pour le créatif.
• name + description : c’est ce qui déclenche le skill. Gérondif, 3e personne, mots-clés du « quand l’utiliser ».
• Progressive disclosure : SKILL.md court, détails dans des fichiers séparés, références à un niveau.
• Workflows + boucles de feedback : des checklists, et le pattern « valide → corrige → recommence ».
• Piloté par l’évaluation : écris les tests AVANT la doc ; fais créer le skill par Claude, teste-le avec un autre Claude.
• Anti-patterns : pas de chemins Windows, pas de constantes magiques, pas quinze options.

Écrire un skill Claude Code, tout le monde peut le faire en cinq minutes. En écrire un que Claude déclenche au bon moment et suit correctement, c’est un autre métier. Anthropic a publié ses best practices officielles — voici l’essentiel, distillé, avec les principes qui font vraiment la différence. (On avait vu comment créer un skill ; ici, comment en écrire un bon.)

1. La concision est reine

Le réflexe de débutant, c’est de tout expliquer. Erreur. Le contexte de Claude est un bien commun : ton skill le partage avec le system prompt, l’historique de conversation, les autres skills et la demande réelle. Chaque token que tu ajoutes en retire un ailleurs.

La règle d’Anthropic tient en une phrase : Claude est déjà très intelligent. N’ajoute que ce qu’il ne sait pas déjà. Pour chaque paragraphe, demande-toi : « Claude a-t-il vraiment besoin de cette explication ? ». Inutile de lui expliquer ce qu’est un PDF ou comment marche une librairie — donne directement l’instruction utile. Un skill de 50 tokens bien ciblé bat un skill de 150 tokens qui ré-explique l’évident.

Nuance technique rassurante : au démarrage, seuls le name et la description de chaque skill sont préchargés. Le corps de SKILL.md n’est lu que quand le skill devient pertinent. Mais une fois chargé, chaque token compte.

2. Le bon degré de liberté

Toutes les tâches ne se pilotent pas de la même façon. Anthropic propose une belle analogie : Claude est un robot sur un chemin.

• Pont étroit avec des précipices : une seule voie sûre. Donne des instructions exactes, des garde-fous stricts (peu de liberté). Exemple : une migration de base de données qui doit tourner dans un ordre précis → « Lance exactement cette commande, ne la modifie pas ».
• Champ ouvert sans danger : plein de chemins mènent au but. Donne une direction générale et fais confiance (beaucoup de liberté). Exemple : une revue de code, où le contexte dicte la meilleure approche.

Règle : plus la tâche est fragile et critique, plus tu es précis. Plus elle est ouverte et créative, plus tu laisses du mou.

3. name et description : ce qui déclenche le skill

C’est LE point le plus important, et le plus négligé. Au démarrage, Claude ne voit que le name et la description de tes skills — c’est là-dessus qu’il choisit lequel déclencher parmi 100 ou plus.

• name : en gérondif (verbe + -ing en anglais), minuscules, chiffres et tirets uniquement, 64 caractères max. Exemples : « processing-pdfs », « analyzing-spreadsheets ». Évite les noms vagues (« helper », « utils », « tools ») et les mots réservés (« claude », « anthropic »).
• description : à la 3e personne — jamais « je peux… » ni « tu peux… », car elle est injectée dans le system prompt et une mauvaise personne casse la détection. 1024 caractères max. Et surtout : dis ce que ça fait ET quand l’utiliser. Exemple efficace : « Extrait le texte et les tableaux de fichiers PDF, remplit des formulaires. À utiliser quand l’utilisateur travaille avec des PDF ou mentionne des formulaires. » Une description vague comme « Aide avec les documents » = un skill qui ne se déclenche jamais.

4. Progressive disclosure (dévoilement progressif)

Ton SKILL.md n’est pas un manuel : c’est une table des matières. Il donne l’essentiel et pointe vers des fichiers détaillés que Claude ne charge que si besoin. Concrètement :

• Garde le corps de SKILL.md sous 500 lignes. Au-delà, découpe en fichiers séparés.
• Range par domaine (reference/finance.md, reference/sales.md…) : quand on demande les ventes, Claude ne charge pas la finance. Zéro token consommé tant qu’un fichier n’est pas lu.
• Garde les références à un seul niveau de profondeur depuis SKILL.md. Si un fichier en référence un autre qui en référence encore un autre, Claude risque de ne lire que des bouts (un aperçu des 100 premières lignes) → information incomplète.
• Pour un fichier de référence long (plus de 100 lignes), mets une table des matières en haut.

5. Workflows et boucles de feedback

Pour les tâches complexes, découpe en étapes séquentielles claires — et donne à Claude une checklist qu’il copie dans sa réponse et coche au fur et à mesure. Ça l’empêche de sauter une étape critique (comme une validation).

Encore mieux : les boucles de feedback. Le pattern « valide → corrige → recommence » améliore énormément la qualité. Exemple : « rédige selon le guide de style → vérifie contre la checklist → si problème, corrige et re-vérifie → ne continue que quand tout est bon ». Le validateur peut être un script, ou simplement un document de règles que Claude relit.

6. Développer piloté par l’évaluation

Le conseil qui change tout : écris tes évaluations AVANT d’écrire la doc. Sinon tu documentes des problèmes imaginaires au lieu des vrais. La méthode :

1. Fais tourner Claude sur des tâches réelles sans skill → note les échecs concrets.
2. Crée trois scénarios de test sur ces trous.
3. Mesure la performance de base (sans skill).
4. Écris le minimum d’instructions pour combler les trous et passer les tests.
5. Itère.

Autre pépite : développe le skill avec Claude lui-même. Une instance (« Claude A ») t’aide à écrire et affiner le skill ; une instance fraîche avec le skill chargé (« Claude B ») le teste sur de vraies tâches. Tu observes où Claude B galère, tu reviens vers Claude A pour corriger. Pas besoin d’un skill spécial pour ça : Claude connaît nativement le format, demande-lui juste d’en créer un.

7. Les anti-patterns à éviter

• Chemins Windows : toujours des slashs avant (reference/guide.md), même sous Windows — les backslashs cassent sous Unix.
• Trop d’options : ne propose pas « tu peux utiliser X, ou Y, ou Z… ». Donne un défaut clair, avec une porte de sortie si vraiment nécessaire.
• Constantes magiques (« voodoo constants ») : pas de « TIMEOUT = 47 » sans justification. Si tu ne sais pas pourquoi cette valeur, Claude non plus. Documente : « 30 s pour couvrir les connexions lentes ».
• Information datée : évite « avant août 2025, utilise l’ancienne API ». Mets plutôt une section « anciens patterns » en repli.
• Supposer les outils installés : dis explicitement « installe le paquet, puis utilise-le » plutôt que « utilise la lib ».

La checklist avant de partager un skill

• Description spécifique, avec les mots-clés et le « quand l’utiliser ».
• SKILL.md sous 500 lignes ; les détails dans des fichiers séparés.
• Terminologie cohérente, exemples concrets (pas abstraits).
• Références à un seul niveau de profondeur.
• Workflows avec étapes claires + boucles de validation pour les tâches critiques.
• Scripts qui gèrent les erreurs eux-mêmes, sans constantes magiques, en slashs Unix.
• Au moins trois évaluations, testées sur Haiku, Sonnet et Opus.

En une phrase

Écrire un bon skill, ce n’est pas écrire beaucoup — c’est écrire juste : concis, bien rangé, testé. Si tu ne retiens qu’une chose : soigne le name et la description (c’est ce qui déclenche tout), garde SKILL.md court, et teste sur de vrais cas. Le reste, ce sont des raffinements — et la bonne nouvelle, c’est que Claude sait t’aider à écrire ses propres skills. Sers-t’en.