Écrire une « skill » pour Claude : les règles du guide officiel d'Anthropic

Une « skill » regroupe, dans un dossier, un fichier SKILL.md et éventuellement des documents de référence et des scripts. Elle sert à transmettre à Claude une procédure propre à l'entreprise : la façon de remplir un formulaire, les règles d'un rapport, le schéma d'une base de données. La documentation d'Anthropic publie un guide de rédaction détaillé. En voici les règles principales.

Le principe : n'écrire que ce que le modèle ignore

Le guide part d'un constat : la skill partage la fenêtre de contexte avec le prompt système, l'historique de la conversation et la demande en cours. Au démarrage, seuls le nom et la description de chaque skill sont chargés. Le fichier SKILL.md n'est lu que lorsque la skill devient pertinente, et les fichiers annexes seulement en cas de besoin.

La consigne qui en découle est de supprimer toute explication que le modèle connaît déjà.

Les limites à respecter

• Nom : 64 caractères au maximum, uniquement des minuscules, des chiffres et des tirets. Les mots anthropic et claude sont réservés.
• Description : 1 024 caractères au maximum, non vide. Elle dit ce que fait la skill et quand l'utiliser, à la troisième personne. C'est elle qui permet à Claude de choisir la bonne skill, parfois parmi plus d'une centaine.
• Corps de SKILL.md : moins de 500 lignes. Au-delà, le contenu se répartit dans des fichiers séparés.
• Fichiers de référence : liés directement depuis SKILL.md, sans renvoi en cascade. Au-delà de 100 lignes, ils commencent par une table des matières.
• Chemins : toujours avec des barres obliques, y compris sous Windows.

Doser la liberté laissée au modèle

Trois niveaux sont décrits. Des consignes en texte libre conviennent quand plusieurs approches sont valables, par exemple une relecture de code. Un modèle de script paramétrable convient quand une méthode est préférée. Une commande exacte, à ne pas modifier, s'impose pour les opérations fragiles comme une migration de base de données.

Pour les tâches à étapes, le guide recommande une liste de contrôle que le modèle recopie et coche, ainsi qu'une boucle de validation : exécuter un contrôle, corriger, recommencer. Il conseille aussi de fournir des scripts prêts à l'emploi plutôt que de laisser le modèle les réécrire, et d'éviter les informations datées, vouées à devenir fausses.

Tester avant de documenter

La méthode proposée inverse l'ordre habituel :

1. faire travailler Claude sans skill sur des tâches représentatives et noter les échecs ;
2. construire trois scénarios d'évaluation qui ciblent ces échecs ;
3. mesurer le résultat sans skill ;
4. écrire le minimum d'instructions pour réussir les scénarios ;
5. recommencer.

Le guide demande aussi de vérifier le comportement avec chaque modèle utilisé, Haiku, Sonnet et Opus : ce qui suffit au plus puissant peut manquer de détail pour le plus économique.

Les limites à connaître

• Anthropic précise qu'il n'existe pas, à ce jour, d'outil intégré pour exécuter ces évaluations. Il faut les lancer soi-même.
• L'environnement d'exécution diffère selon le produit : d'après le guide, claude.ai peut installer des paquets depuis npm et PyPI, alors que l'API n'a ni accès réseau ni installation à l'exécution. Une skill avec scripts doit donc lister ses dépendances.
• Si la skill appelle des outils MCP, leur nom doit être complet, au format NomDuServeur:nom_outil.

Notre lecture

Pour une petite structure, la skill la plus utile est souvent la plus courte : les quelques règles que l'on répète à chaque conversation. Un seul fichier SKILL.md de quelques dizaines de lignes suffit pour commencer.

Deux points méritent de l'attention. La description décide du déclenchement : une skill bien écrite mais mal décrite ne sera pas chargée. Et les trois scénarios de test, même tenus dans un simple tableur, évitent d'empiler des consignes dont personne ne sait si elles servent.