Créer une Claude Skill : SKILL.md en 10 minutes

Nous testons des Claude skills à longueur de journée, des centaines à ce jour, et le constat est déprimant : la plupart des skills qui échouent à notre relecture n'échouent pas parce que l'auteur ne savait pas écrire des instructions. Elles échouent parce que la skill ne se chargeait jamais, ou se chargeait quand elle n'aurait pas dû, ou était trois skills déguisées en une seule. Tout cela se corrige au moment de l'écriture, rien ne se corrige après coup avec un README plus joli.

C'est le tutoriel que nous aurions aimé voir chaque auteur lire en premier. À la fin, vous aurez une skill fonctionnelle : une checklist de revue de code qui pousse Claude au-delà du « ça a l'air bien, peut-être renommer cette variable » pour vérifier les cas limites, les chemins d'erreur et le code mort. C'est un exemple réel, délibérément. La meilleure skill communautaire de notre catégorie code, Code Review Checklist, fait exactement cela et obtient 8/10 sur le résultat. La vôtre ne la battra pas le premier jour, mais vous comprendrez chaque décision prise par l'auteur de cette skill.

La promesse des 10 minutes est honnête, avec un astérisque. Écrire la première version fonctionnelle prend environ 10 minutes. La tester correctement en prend 30 de plus. Sautez la deuxième partie et vous rejoindrez la moitié des skills publiées qui ne survivent pas au contact d'une session neuve. Nous avons fait l'autopsie dans pourquoi la moitié des Claude skills ne marchent pas, et nous préférerions ne pas ajouter la vôtre au jeu de données.

Si vous n'avez jamais installé de skill et ne savez pas ce que c'est, lisez d'abord ce que sont les Claude skills et comment les installer. Cet article suppose que vous en avez déjà utilisé au moins une.

Étape 1 : la cantonner à un seul travail

Avant d'écrire une ligne, décidez ce que fait votre skill. Puis coupez ça en deux.

Le plus gros échec que nous constatons en test, ce sont les skills qui essaient de tout faire. « Aide à la qualité du code » a l'air d'un périmètre raisonnable. Ce n'en est pas un. Une skill de ce genre veut se déclencher sur les revues, les refactorisations, l'écriture de tests, les questions de linting et les débats d'architecture, ce qui en pratique signifie que Claude ne peut pas savoir quand la charger, donc elle se charge de façon imprévisible ou jamais. Les problèmes de déclenchement sont la première raison pour laquelle une skill obtient une note basse dans notre méthodologie, devant les mauvaises instructions et les installations cassées. Pas parce que le déclenchement est la partie la plus difficile de l'écriture d'une skill, mais parce qu'un périmètre trop large en amont rend le problème insoluble en aval.

Une skill, un travail. Voici le test : pouvez-vous terminer la phrase « utiliser cette skill quand l'utilisateur demande de ___ » avec une seule expression verbale concrète ? « Relire une pull request ou un diff » passe le test. « Améliorer son code » échoue. Si votre phrase contient « et » ou « ou » reliant des activités sans rapport, vous êtes en train d'écrire deux skills. Écrivez deux skills. Les dossiers ne coûtent rien.

Pour notre exemple, le périmètre est : relire un diff ou une PR pour des bugs de correction, avec une checklist fixe, en supprimant les remarques de style. Pas « aider aux revues ». Pas « relire et corriger ». Relire, rapporter, s'arrêter.

Étape 2 : le modèle de SKILL.md

Une skill est un dossier avec un seul fichier obligatoire. Le nôtre va dans ~/.claude/skills/ pour un usage personnel, ou .claude/skills/ dans un dépôt si toute l'équipe doit en bénéficier :

review-checklist/
  SKILL.md          ← obligatoire, et souvent tout ce dont vous avez besoin
  reference/        ← optionnel, chargé seulement quand Claude décide de le lire
  templates/        ← optionnel, fichiers vers lesquels pointent vos instructions

Voici le SKILL.md complet que nous allons construire, annoté. Copiez-le, puis lisez les annotations, car deux de ces lignes comptent bien plus que les autres :

---
# 'name' est un identifiant : minuscules, tirets, pas d'espaces.
# Claude le voit, mais il ne pilote PAS le déclenchement.
name: review-checklist

# 'description' est la SEULE chose que Claude lit pour décider
# de charger cette skill ou non. Tout ce qui suit le frontmatter
# est invisible tant que cette décision n'est pas prise. Écrivez-la
# comme une condition de déclenchement, pas un texte marketing.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

C'est toute la skill. Pas d'étape de build, pas de manifeste, pas d'enregistrement. Redémarrez votre session Claude et elle est active.

Le frontmatter a exactement deux champs qui comptent. name est de la comptabilité. description décide de tout, et voici pourquoi : Claude ne garde en contexte que le nom et la description de chaque skill installée. Le corps de votre SKILL.md n'existe pas, du point de vue du modèle, tant qu'il n'a pas lu votre description, décidé « ça correspond à ce que veut l'utilisateur », et chargé le reste. Une checklist brillante de 200 lignes derrière une description vague est une checklist brillante de 200 lignes que personne n'exécutera jamais. Dans notre barème de notation, le déclenchement pèse aussi lourd que la qualité du résultat, précisément pour cette raison. Une skill qui se déclenche 40 % du temps est un pile-ou-face avec des étapes en plus.

Étape 3 : écrire la description de déclenchement

Puisque la description est une condition de déclenchement, écrivez-la comme telle. Nommez les formulations qu'un vrai utilisateur taperait. Incluez l'espace négatif, c'est-à-dire les demandes voisines où la skill doit rester silencieuse.

Côte à côte, issues de vraies soumissions que nous avons testées (légèrement anonymisées) :

Mauvais :

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Bon :

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

Le mauvais exemple décrit le bénéfice. Le bon décrit le moment. Claude ne lit pas votre description pour être convaincu ; il fait du pattern-matching avec les mots réels de l'utilisateur. « Relis cette PR » ne partage aucun vocabulaire avec « aide à améliorer la qualité du code », donc la skill dort à travers son propre cas d'usage. Nous avons testé une soumission presque identique à ce mauvais exemple : elle se déclenchait sur 1 prompt de revue sur 8. Après réécriture de la description pour nommer les formulations, avec le même corps, elle se déclenchait sur 8 sur 8.

Une autre paire, sur l'espace négatif cette fois :

Mauvais :

description: Use for anything related to testing.

Bon :

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

« Tout ce qui touche aux tests » est la meilleure façon de détourner une session de débogage. Le sur-déclenchement est plus discret que le sous-déclenchement, et tout aussi dommageable : l'utilisateur reçoit des réponses au goût de checklist à des questions qui demandaient autre chose, blâme le modèle, désinstalle la skill.

Des règles mécaniques qui tiennent sur tout ce que nous avons testé : nommez trois à cinq formulations concrètes d'utilisateur, incluez au moins une clause « ne PAS utiliser », restez sous environ 500 caractères, et n'utilisez jamais les mots « puissant », « complet » ou « aide à ». Ces mots sont corrélés à des notes de déclenchement en échec de façon si constante dans nos données que nous sursautons désormais rien qu'à les voir.

Étape 4 : écrire un corps que Claude suit vraiment

Une fois la skill chargée, le corps est le jeu d'instructions. Le mode d'échec ici est plus subtil que le déclenchement mais tout aussi fréquent : des instructions qui inspirent au lieu de contraindre. « Écris une revue approfondie et réfléchie » est une affiche de motivation. Claude veut déjà être approfondi et réfléchi ; c'est le comportement par défaut que vous essayez de façonner, pas la forme à lui donner.

Les skills en tête de nos classements sont des listes de contraintes. Test-Driven Development interdit toute implémentation avant l'existence d'un test qui échoue, point final. Notre skill d'exemple plafonne les remarques à 10 et bannit purement les remarques de style. Remarquez combien de ses lignes commencent par « ne pas ». C'est délibéré. Les modèles sur-génèrent par défaut, donc les instructions à plus forte valeur sont généralement soustractives.

Règles empiriques pour le corps :

1. Les procédures numérotées battent la prose. « Traite ceci dans l'ordre » donne une colonne vertébrale à Claude ; les paragraphes lui donnent des vibrations.
2. Énoncez la condition d'arrêt. Notre skill dit : rapporte les remarques, ne corrige pas. Sans cette ligne, Claude se mettra utilement à réécrire le code, ce que personne n'a demandé.
3. Légiférez sur le format de sortie. Nombres maximums, champs requis, à quoi ressemble un résultat propre. « Si le diff est propre, dis-le » évite d'inventer des remarques, un échec que nous constatons constamment dans les skills de type revue.
4. Placez les détails rarement nécessaires dans des fichiers reference/. Si votre skill a un guide de style de 300 lignes qui s'applique une fois par mois, ne le collez pas dans SKILL.md où il brûle du contexte à chaque activation. Enregistrez-le comme reference/style-guide.md et écrivez « quand l'utilisateur pose une question sur X, lis d'abord reference/style-guide.md ». Claude le charge à la demande.

Quand ajouter des scripts et des modèles ? Seulement quand les instructions ne peuvent pas faire le travail. Une skill qui génère un fichier de configuration spécifique devrait fournir un templates/config.yaml et dire « copie ceci, puis modifie ». Une skill qui a besoin d'un comportement déterministe, disons analyser un format de lockfile, devrait fournir un script et demander à Claude de l'exécuter plutôt que de le réimplémenter de mémoire à chaque fois. Mais la plupart des skills n'ont besoin ni de l'un ni de l'autre. Notre exemple n'en a besoin d'aucun. Chaque fichier du dossier est quelque chose que vous devez désormais maintenir, donc méritez chacun d'eux.

Étape 5 : la tester en local

Vous n'avez pas terminé quand ça fonctionne une fois. « Ça a marché quand j'ai essayé » est le standard de test de chaque skill cassée que nous avons jamais fait échouer. Voici la batterie minimale, qui correspond de près à ce que fait tourner notre méthodologie sur les soumissions :

1. Session neuve. Redémarrez complètement Claude Code. Les skills se chargent au démarrage de la session ; les tester dans la session où vous les avez écrites ne prouve rien.
2. Test de déclenchement, positif. Essayez trois formulations différentes qu'un vrai utilisateur taperait : « relis cette PR », « peux-tu vérifier ce diff avant que je merge », « regarde mes changements ». Les trois devraient activer la skill. Vous pouvez savoir qu'elle s'est déclenchée parce que le résultat suit vos règles (une liste de remarques plafonnée et triée par sévérité ne ressemble en rien à une revue par défaut). En cas de doute, demandez directement à Claude s'il a utilisé la skill.
3. Test de déclenchement, négatif. Essayez trois demandes voisines qui ne devraient PAS la déclencher : « corrige ce bug », « écris une fonction qui parse des dates », « pourquoi ce test échoue-t-il ? ». Si votre checklist de revue apparaît dans une session de débogage, votre description a besoin d'une clause « ne PAS utiliser ».
4. Comparaison de base. Exécutez le même prompt de revue dans une session avec la skill et une sans. Si vous ne pouvez pas distinguer les résultats, la skill ne mérite pas son contexte et vous devriez affûter les contraintes. C'est notre test préféré car il est impitoyable. Environ un tiers des skills que nous relisons échouent à ce test.
5. Test d'installation propre. Si vous prévoyez de publier : copiez le dossier sur une autre machine (ou supprimez et re-clonez), suivez votre propre README à la lettre, et voyez si ça fonctionne. Les notes de dépendances manquantes meurent ici.

Toute la batterie prend 30 minutes. Elle filtre environ 80 % des échecs que nous constatons, ce qui est un excellent retour sur une demi-heure.

Étape 6 : la passer dans le validateur

Avant de publier, collez votre SKILL.md dans notre validateur de skill gratuit. Il note selon le même barème que nos revues : longueur et spécificité de la description, présence de formulations de déclenchement concrètes, clauses d'espace négatif, densité de contraintes dans le corps, légifération du format, anti-patterns évidents comme « puissant » et « tout ce qui touche à ».

C'est de l'analyse statique, donc à traiter comme telle. Il repère les erreurs visibles dans le texte, ce qui d'après notre expérience en couvre la plupart, mais il ne peut pas faire tourner votre skill sur des prompts réels. Un passage réussi au validateur plus la batterie de l'étape 5, voilà la vraie barre. Un passage réussi au validateur seul, c'est une skill lintée qui pourrait quand même ne jamais se déclencher.

Si vous préférez une aide interactive à un simple vérificateur, le Skill Creator d'Anthropic est l'outil que nous recommandons. Il a obtenu 9,6 dans nos tests, échafaude le dossier, et son étape d'optimisation de la description a mesurablement amélioré le déclenchement de nos propres skills internes. Utiliser une skill pour écrire des skills a l'air d'une blague et ça marche quand même.

Étape 7 : publier et soumettre

Publier, c'est un dépôt GitHub ordinaire. Convention de structure :

your-repo/
  README.md           ← ce que ça fait, la commande d'installation, un exemple
  review-checklist/
    SKILL.md
    reference/

Mettez la commande d'installation dans le README sous forme de bloc à copier-coller, le schéma standard étant git clone plus cp -r review-checklist ~/.claude/skills/. Ajoutez ensuite le tag de topic claude-skills au dépôt. Ce n'est pas de la décoration : le tag de topic est ce qui permet à notre crawler et à tout autre répertoire de découvrir les nouvelles skills. Un dépôt de skill sans tag est invisible en pratique.

Un README qui mérite d'être écrit contient quatre choses : une phrase sur ce que fait la skill, le bloc d'installation, un exemple avant/après, et les dépendances éventuelles. L'exemple avant/après fait plus pour l'adoption que tout le reste réuni, car c'est la seule partie qui montre plutôt qu'elle n'affirme.

Puis soumettez-la à SkillProof. Le test et le référencement sont gratuits. Nous passons la soumission par le même processus que tout le reste du catalogue : installation neuve depuis votre README, batterie de déclenchement, comparaison de base, notation du résultat. Si elle passe, elle est référencée avec une note, et vous pouvez intégrer un badge « SkillProof tested » dans votre README. Pour un auteur inconnu avec un dépôt vieux de deux jours, un verdict de test indépendant fait toute la différence entre « un SKILL.md au hasard sur internet » et quelque chose qu'un inconnu installera vraiment. Si elle ne passe pas, vous recevez les notes d'échec, vous corrigez, et vous resoumettez. De nombreuses skills référencées sont passées par deux tours.

Erreurs courantes que nous voyons dans les soumissions

Après quelques centaines de relectures, les cinq mêmes reviennent sans cesse.

Descriptions vagues. Toujours en première place, et de loin. Si votre description pourrait décrire trois autres skills, elle n'en décrit aucune.

La skill fourre-tout. Un seul SKILL.md gérant revues, commits, refactorisations et documentation. Chaque rôle dilue le déclenchement des autres. Séparez-les.

Reformuler les comportements par défaut du modèle. Un corps qui dit « sois clair, sois précis, réfléchis étape par étape » n'ajoute rien. Claude le fait déjà de toute façon. Si supprimer une ligne ne change pas le résultat, supprimez la ligne.

Aucune contrainte négative. Des skills qui disent seulement quoi faire, jamais quoi arrêter de faire. Les lignes « ne pas » sont là où réside la majeure partie du changement de comportement.

Instructions d'installation non testées. Le README dit de copier un dossier ; la skill dépend silencieusement d'une deuxième skill ou d'un paquet Python. Meurt systématiquement à notre étape d'installation propre, et c'est l'échec le plus évitable de cette liste.

FAQ

Dois-je savoir coder pour créer une Claude skill ? Non. Un SKILL.md est du markdown avec un en-tête YAML. Si votre skill fournit des scripts d'aide, il faudra les écrire, mais les skills purement instructionnelles, qui sont la majorité, ne sont que de l'écriture. La skill de cet article ne contient aucun code.

Quelle doit être la longueur d'un SKILL.md ? Aussi court que possible tout en contraignant le comportement, typiquement 30 à 150 lignes. En dessous d'environ 20 lignes, il n'ajoute généralement rien au-delà des défauts ; au-delà de quelques centaines, vous devriez déplacer le détail vers des fichiers reference/. La longueur est un coût payé à chaque activation, pas un signal de qualité.

Pourquoi ma skill ne se déclenche-t-elle pas ? La description, presque toujours. Vérifiez qu'elle nomme des formulations qu'un utilisateur taperait réellement plutôt que de décrire des bénéfices, et confirmez que vous avez redémarré la session après installation, puisque les skills se chargent au démarrage de la session. Si elle se déclenche sur certaines formulations et pas d'autres, ajoutez explicitement celles qui manquent à la description.

Quelle est la différence entre une skill et un serveur MCP ? Une skill, ce sont des instructions : du markdown qui façonne le comportement de Claude, aucun code qui s'exécute nulle part. Un serveur MCP est un programme qui donne à Claude de nouvelles capacités, comme interroger votre base de données. Si votre idée est « Claude devrait aborder X différemment », c'est une skill. Si c'est « Claude a besoin d'accéder à Y », c'est du MCP. Version détaillée dans Claude skills vs MCP.

Puis-je faire payer une Claude skill ? Il n'existe aucun mécanisme de paiement intégré ; les skills sont des fichiers, et l'écosystème public fonctionne sur des dépôts ouverts. Certains auteurs vendent des packs de skills privés à des équipes comme prestations de conseil, ce qui fonctionne parce que la valeur réside dans l'expertise encodée, pas dans le fichier. Tout ce qui est destiné au catalogue public devrait être sous licence ouverte, car personne n'installe une skill qu'il ne peut pas lire.

Cantonnez-vous à un seul travail, écrivez le déclencheur comme une regex en prose, contraignez au lieu d'inspirer, et testez dans une session neuve avant d'en parler à qui que ce soit. C'est tout le métier. Le reste n'est qu'itération, et la file de soumission est ouverte.