Les skills Claude Code : écrire la vôtre pas à pas

01À quoi sert une skill

Chaque fois que vous publiez un article, vous rappelez à Claude le ton, la structure, les vérifications. Mettre tout ça dans CLAUDE.md alourdit chaque session, même celles qui n'ont rien à voir avec un article. Le recoller à la main, c'est l'oublier une fois sur deux.

Une skill est un mode opératoire rangé à part. Claude sait qu'elle existe, mais il ne la lit que lorsque votre demande correspond. Le reste du temps, elle ne coûte presque rien.

02Un dossier, un fichier

Une skill est un dossier qui contient un fichier SKILL.md. Le nom du dossier devient la commande : le dossier publier-article se lance avec /publier-article.

Le fichier commence par un en-tête entre deux lignes de tirets, puis vient la procédure en Markdown. La skill est disponible dès l'enregistrement.

---
name: publier-article
description: Prépare un article de blog pour la publication (relecture, balises SEO, images). À utiliser quand l'utilisateur veut publier, finaliser ou mettre en ligne un article.
---

1. Relis l'article et corrige l'orthographe sans changer le style.
2. Vérifie qu'il y a un seul H1 et des H2 qui décrivent chaque partie.
3. Propose un title de 60 caractères maximum et une meta description de 150.
4. Vérifie que chaque image a un texte alternatif.
5. Termine par la liste de ce que tu as modifié.

03Comment Claude la charge

Le chargement se fait par étages, ce qui permet d'avoir des dizaines de skills sans encombrer la session.

Une skill se déclenche de deux façons : vous tapez /nom, ou Claude la choisit seul parce que la description correspond à votre demande. Une fois lue, elle reste dans le contexte jusqu'à la fin de la session. D'où l'intérêt d'un corps court.

04Skill, CLAUDE.md ou message

Les anciennes commandes personnalisées, rangées dans .claude/commands/, fonctionnent toujours. Les skills les remplacent avec plus d'options.

05Soigner la description

C'est la seule partie que Claude lit avant de décider. Une description vague donne une skill qui ne se déclenche jamais, ou qui se déclenche n'importe quand. Elle doit dire ce que fait la skill, puis quand l'utiliser, avec les mots que vous employez vraiment. Mettez l'essentiel au début : les descriptions trop longues sont coupées.

La dernière phrase trace la frontière avec une skill voisine, par exemple une skill de rédaction.

06Écrire le corps

• Court. Claude sait déjà écrire, coder, relire. N'expliquez que ce qui est propre à votre façon de faire.
• Des étapes numérotées, avec une vérification à la fin.
• Un choix par défaut plutôt qu'une liste d'options : « utilise WebP », pas « WebP, AVIF ou JPEG selon le cas ».
• Un exemple du résultat attendu quand le format compte.
• Les mêmes mots partout. Si vous dites « fiche produit », ne passez pas à « page article » trois lignes plus bas.

---
name: [nom-en-minuscules]
description: [Ce que fait la skill]. À utiliser quand [formulations réelles de la demande]. Pas pour [cas voisin].
---

## Avant de commencer
- [Ce qu'il faut vérifier ou demander]

## Étapes
1. [Étape]
2. [Étape]
3. Vérifie : [test, commande ou contrôle visuel]

## Pièges connus
- [Ce qui a déjà raté, et comment l'éviter]

07Scripts et références

Quand la procédure grossit, déplacez le détail dans des fichiers voisins. Claude ne les lit que si une étape les cite.

Chaque annexe doit être mentionnée dans le SKILL.md, avec ce qu'il faut en faire : « exécute scripts/verifier-liens.py » ou « lis references/charte.md avant d'écrire ». Gardez un seul niveau de renvoi : une référence ne renvoie pas vers une autre.

08Les options utiles

L'en-tête accepte d'autres champs que name et description. Ceux-ci suffisent dans la plupart des cas.

09La méthode en quatre gestes

N'écrivez pas une skill à froid. Faites le travail une fois avec Claude, puis transformez la session en procédure.

Transforme ce qu'on vient de faire en skill dans .claude/skills/[nom]/SKILL.md.
Garde seulement les étapes qui ont servi, dans l'ordre, avec la vérification finale.
Ajoute une section « Pièges connus » avec ce qui a raté pendant la session.
Écris une description qui dit ce que fait la skill et quand l'utiliser.

La skill [nom] vient de rater : [ce qui s'est passé].
Corrige le fichier SKILL.md pour que ça n'arrive plus, sans l'allonger inutilement.
Montre-moi le changement.

L'étape [numéro] de la skill [nom] refait le même travail à chaque fois.
Écris un script dans scripts/ qui la fait, avec des messages d'erreur clairs,
puis remplace l'étape par l'appel au script.

Le SKILL.md de [nom] devient long.
Déplace le détail qui ne sert pas à chaque fois dans references/,
et laisse dans le SKILL.md une ligne qui dit quand lire chaque fichier.

10Tester une skill

Trois vérifications, dans une session neuve pour ne pas fausser le résultat :

• Elle est reconnue. Tapez / : elle doit apparaître dans la liste. Sinon, l'en-tête est mal formé.
• Elle se déclenche au bon moment. Formulez la demande sans la nommer. Puis faites une demande voisine qui ne doit pas la lancer.
• Elle fait mieux que sans. Comparez le résultat avec et sans la skill sur la même tâche.

Si elle se déclenche trop souvent, précisez la description ou passez-la en disable-model-invocation: true.

11Les erreurs fréquentes

• Une description vague. La skill ne se déclenche jamais.
• Un en-tête mal formé. Un tiret manquant, et la skill n'existe pas.
• Écrire la skill avant d'avoir fait le travail. Elle décrit ce que vous imaginez, pas ce qui marche.
• Expliquer ce que Claude sait déjà. Chaque ligne inutile coûte du contexte.
• Des références qui renvoient vers d'autres références. Claude s'y perd.
• Installer une skill trouvée en ligne sans la lire. Vérifiez ce qu'elle fait et quels outils elle s'autorise.