Écrire sa propre skill Claude : structure, SKILL.md et description qui déclenche

Une skill, c’est un dossier que tu écris pour apprendre à Claude un savoir-faire précis, une bonne fois pour toutes, au lieu de retaper les mêmes instructions à chaque conversation. Contrairement à un simple message, une skill se déclenche toute seule quand elle est pertinente, et elle peut embarquer des fichiers de référence ou des scripts que Claude va lire seulement s’il en a besoin. Voici comment en construire une, uniquement à partir de ce que confirme la documentation officielle d’Anthropic.

L’anatomie d’un dossier de skill

Une skill est un dossier contenant, au minimum, un fichier SKILL.md. Dans Claude Code, ce dossier se place à l’un de ces deux endroits :

• ~/.claude/skills/<nom-de-la-skill>/SKILL.md pour une skill personnelle, disponible sur tous tes projets ;
• .claude/skills/<nom-de-la-skill>/SKILL.md pour une skill de projet, commit dans le dépôt et donc partagée avec ton équipe.

Une skill peut rester à ce seul fichier, ou grandir avec des fichiers additionnels à côté : un REFERENCE.md pour la documentation détaillée, un FORMS.md pour un cas particulier, un dossier scripts/ avec des scripts exécutables. Rien de tout ça n’est obligatoire au départ : commence petit, un seul fichier SKILL.md suffit pour une première skill utile.

Le frontmatter : les deux champs qui comptent

SKILL.md commence toujours par un frontmatter YAML, entre deux lignes ---, avec deux champs :

---
name: ta-skill
description: Ce que fait la skill, et quand l'utiliser.
---

La documentation officielle est précise sur les règles de validation de chacun :

• name : 64 caractères maximum, uniquement des lettres minuscules, des chiffres et des tirets, aucune balise XML, et ne peut pas contenir les mots réservés « anthropic » ou « claude ».
• description : ne peut pas être vide, 1024 caractères maximum, aucune balise XML, et doit décrire à la fois ce que fait la skill et quand l’utiliser.

Sur claude.ai, les skills personnalisées s’installent sous forme d’archive zip contenant le dossier de la skill à sa racine (pas de sous-dossier intermédiaire), puis s’activent depuis Customize > Skills. Le format du fichier et les deux champs de frontmatter restent les mêmes qu’en local.

Bien choisir le nom de la skill

Le name mérite un peu plus de soin qu’une étiquette rapide. La documentation officielle recommande d’utiliser une forme verbale en « -ing » (par exemple processing-pdfs, analyzing-spreadsheets, managing-databases), ou à défaut un nom composé clair (pdf-processing). À l’inverse, elle déconseille explicitement les noms trop vagues ou trop génériques comme helper, utils, tools ou data : ils ne disent rien sur ce que fait réellement la skill, ni à toi quand tu en auras dix, ni à Claude au moment de choisir entre plusieurs skills disponibles. Un nom cohérent avec le reste de tes skills facilite aussi bien la maintenance que la simple conversation avec Claude à leur sujet.

Écrire une description qui déclenche vraiment la skill

C’est le champ le plus important de toute la skill : Claude compare ta demande à la description de chaque skill disponible pour décider laquelle utiliser, potentiellement parmi des dizaines. La documentation officielle recommande trois règles simples. D’abord, toujours écrire à la troisième personne : « Traite les fichiers Excel et génère des rapports » plutôt que « Je peux t’aider à traiter des fichiers Excel » ou « Tu peux utiliser ça pour traiter des fichiers Excel » — un point de vue incohérent perturbe la détection. Ensuite, être concret et inclure les mots-clés que l’utilisateur emploierait vraiment. Exemple donné par Anthropic pour une skill de traitement de PDF :

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

À l’inverse, des descriptions comme « Aide avec des documents », « Traite des données » ou « Fait des choses avec des fichiers » sont explicitement citées comme des exemples à éviter : trop vagues pour que Claude sache quand les déclencher.

Le chargement progressif : pourquoi une skill ne coûte presque rien tant qu’elle ne sert pas

Une skill fonctionne en trois niveaux, et c’est ce qui permet d’en installer beaucoup sans saturer le contexte de la conversation. Le name et la description de toutes les skills disponibles sont chargés dès le départ, pour un coût d’environ 100 tokens par skill. Le corps de SKILL.md n’est lu que lorsque la skill se déclenche réellement, pour un coût recommandé de moins de 5000 tokens (idéalement sous les 500 lignes). Les fichiers additionnels et les scripts ne sont, eux, chargés ou exécutés que si les instructions de SKILL.md y renvoient explicitement — un script tourne via une commande, et seul son résultat entre dans le contexte, jamais son code.

Concrètement, ça veut dire que si ta skill grossit, mieux vaut découper le contenu avancé dans des fichiers séparés référencés depuis SKILL.md, plutôt que de tout garder dans un seul fichier. La documentation recommande aussi de ne pas empiler les renvois (un fichier qui renvoie vers un fichier qui renvoie vers un autre) : garde toutes tes références à un seul niveau de profondeur depuis SKILL.md, sans quoi Claude risque de ne lire qu’un extrait des fichiers les plus profonds.

Tester ta skill

Pour une skill Claude Code, la vérification est directe :

mkdir -p ~/.claude/skills/ma-skill

Écris ton SKILL.md, puis lance Claude Code (claude) depuis un projet et essaie une demande qui correspond à ta description, pour voir si la skill se déclenche toute seule. Tu peux aussi la forcer explicitement avec /ma-skill. Sur claude.ai, après l’avoir activée dans Customize > Skills, la documentation officielle recommande d’essayer plusieurs formulations de prompt et de relire le raisonnement de Claude pour confirmer qu’elle se déclenche au bon moment.

Partager ta skill

Une skill de projet, placée dans .claude/skills/ et commit dans le dépôt, est automatiquement partagée avec toute personne qui clone le projet : aucune étape supplémentaire. Pour une distribution plus large, Anthropic republie ce même format sous une spécification ouverte (Agent Skills, hébergée sur agentskills.io), ce qui veut dire qu’une skill bien écrite reste lisible et réutilisable en dehors des seuls produits Anthropic.

Un dernier point de prudence, rappelé explicitement par la documentation : une skill peut faire exécuter des commandes ou des scripts à Claude, donc n’installe que des skills que tu as toi-même écrites ou qui viennent d’une source de confiance, et relis leur contenu avant de leur faire confiance, exactement comme tu le ferais avant d’installer un paquet ou une extension.

Si tu comptes utiliser une skill (la tienne ou une autre) pour t’aider sur un travail noté, vérifie d’abord les règles d’usage de l’IA de ton établissement : ça reste vrai même quand l’aide passe par une skill plutôt que par une conversation classique.

À retenir

• Une skill = un dossier avec au minimum un SKILL.md, placé dans ~/.claude/skills/ (personnel) ou .claude/skills/ (projet, partagé via le dépôt).
• Frontmatter obligatoire : name (64 caractères max, minuscules/chiffres/tirets, sans « anthropic » ni « claude ») et description (1024 caractères max, jamais vide).
• La description doit dire quoi ET quand, s’écrire à la troisième personne, et éviter les formulations vagues.
• Chargement progressif : métadonnées toujours chargées, corps de SKILL.md chargé seulement au déclenchement, fichiers annexes et scripts seulement si référencés.
• Teste avec une vraie demande qui correspond à ta description, ou force-la avec /nom-de-la-skill.
• N’installe que des skills que tu as écrites ou dont tu connais la source, et vérifie les règles d’usage de l’IA de ton établissement avant de t’en servir pour un travail noté.