Écrire sa première Skill Claude
Un dossier, un fichier, une description qui déclenche au bon moment. Et les pièges qui font qu'une Skill ne part jamais.
Une Skill, c'est un dossier avec un fichier Markdown dedans. Rien de plus. Ce qui la rend utile, c'est qu'elle ne pèse rien tant qu'on n'en a pas besoin : seule sa description reste en mémoire, et le contenu n'est chargé que si la tâche du moment y correspond.
C'est la différence avec un CLAUDE.md, qui est relu intégralement à chaque session. Une Skill peut faire quinze pages sans coûter quinze pages.
Anatomie
.claude/skills/
revue-de-code/
SKILL.md
references/
checklist.md
Le SKILL.md commence par un en-tête YAML :
---
name: revue-de-code
description: Relit un diff et signale les regressions, les cas non couverts et les fuites d'erreur. A utiliser avant d'ouvrir une pull request ou apres avoir termine une fonctionnalite.
---
# Revue de code
## Ce qu'il faut regarder, dans cet ordre
...
La description fait 90 % du travail
C'est le seul texte que le modèle voit en permanence. Il doit dire ce que la Skill fait et quand s'en servir. Une description qui décrit sans donner de déclencheur produit une Skill qui ne part jamais.
Avant de commencer
- Claude Code installé
- Un projet sous la main, avec une tâche que tu répètes souvent
- Dix minutes
1Choisir une tâche répétitive
Une bonne candidate a trois signes :
- tu la refais au moins une fois par semaine ;
- tu redonnes à chaque fois les mêmes consignes ;
- le résultat est décevant quand tu oublies une de ces consignes.
Une revue de code, un format de commit, une checklist de mise en production, la génération d'un rapport. Mauvaises candidates : ce qui change à chaque fois, et ce que le modèle fait déjà très bien seul.
2Créer le dossier
mkdir -p .claude/skills/revue-de-code
Un dossier par Skill, le nom du dossier reprend le name. Placé dans
.claude/skills/, la Skill suit le projet et se partage avec l'équipe. Dans
~/.claude/skills/, elle te suit toi, sur tous tes projets.
3Écrire la description avant le contenu
Contre-intuitif, mais c'est l'ordre qui marche. Écris d'abord la ligne qui décide du déclenchement, tu sauras ensuite quoi mettre dedans.
Compare :
| Description | Résultat |
|---|---|
Aide a la revue de code | Ne part presque jamais |
Relit un diff et signale les regressions, les cas non couverts et les fuites d'erreur. A utiliser avant d'ouvrir une pull request. | Part au bon moment |
Le deuxième dit ce qui entre (un diff), ce qui sort (trois familles de problèmes) et le moment (avant une PR).
4Écrire le corps
Le corps est une procédure, pas un cours. Ce qui fonctionne :
- des étapes numérotées, dans l'ordre où on veut qu'elles soient faites ;
- des exemples concrets, en particulier des contre-exemples ;
- ce qu'il ne faut pas faire, aussi explicite que le reste.
## Procedure
1. Lire le diff en entier avant de commenter quoi que ce soit.
2. Pour chaque bloc modifie, chercher dans cet ordre :
- une regression sur un cas existant
- une erreur avalee (catch vide, valeur par defaut silencieuse)
- un cas limite non couvert par les tests
3. Ne pas commenter le style. Le formateur s'en occupe.
4. Rendre une liste, du plus grave au moins grave, avec fichier et ligne.
Découper quand ça dépasse deux pages
Au-delà, mets les détails dans references/ et renvoie-y depuis le SKILL.md.
Le modèle ouvrira ces fichiers seulement s'il en a besoin.
5Tester le déclenchement
Le vrai test n'est pas « est-ce que la Skill est bonne » mais « est-ce qu'elle part ». Relance Claude Code, puis formule ta demande sans nommer la Skill :
J'ai fini la fonctionnalite de recherche. Tu peux relire avant que j'ouvre la PR ?
Si la Skill se déclenche, la description est bonne. Sinon, elle est trop vague : ajoute le vocabulaire que tu emploies réellement (« relire », « avant la PR »).
Les pièges classiques
- Une Skill fourre-tout. « assistant-projet » ne se déclenche jamais correctement parce qu'elle correspond à tout et donc à rien. Une Skill, une tâche.
- Du contexte au lieu d'une procédure. Décrire l'architecture du projet n'aide pas ; ça, c'est le rôle du CLAUDE.md. La Skill dit quoi faire, pas quoi savoir.
- Des consignes négociables. « essaie de » et « si possible » se font ignorer. Écris à l'impératif.
- Oublier de relancer. Les Skills sont lues au démarrage de la session. Un fichier créé pendant une session n'existe pas pour elle.
Quelques prompts pour aller plus loin
| Objectif | Prompt à adapter |
|---|---|
| Partir d'un existant | Transforme les consignes que je te repete a chaque revue de code en une Skill dans .claude/skills/. |
| Corriger un déclenchement | Ma Skill [NOM] ne se declenche pas quand je demande [DEMANDE]. Reformule sa description. |
| Découper | Ce SKILL.md fait quatre pages. Propose un decoupage avec des fichiers dans references/. |
| Auditer | Relis mes Skills et dis-moi lesquelles se recouvrent ou ne se declencheront jamais. |
Tu as d’autres ressources comme ça ?
Ce que tu viens de lire est entièrement gratuit. Une nouvelle ressource part chaque semaine dans la newsletter : guides, modèles à copier et liens triés, sans compte à créer.
Me contacter
Une question, un projet, une envie de collaborer ? Écris-moi.
Cette page est en accès libre, n’hésite pas à la partager.