Compétences Code Claude : Les fichiers SKILL.md que le modèle utilise

Dernière mise à jour: June 28, 2026

Une Claude Code Skill est un dossier contenant un fichier SKILL.md que l'agent récupère dans le contexte uniquement lorsqu'une tâche correspond à sa fonction. J'ai créé ma première skill pour arrêter de coller la même liste de contrôle de migration de base de données de 200 mots dans chaque session. Ce seul fichier me fait gagner environ une heure par semaine.

Voici la version courte, puis l'anatomie pratique : ce qu'est une skill, comment rédiger le frontmatter et le corps du SKILL.md, comment le modèle décide d'invoquer une skill, et quand une skill est excessive comparée à un simple prompt. Si vous utilisez déjà Claude Code, vous pouvez déployer votre première skill en moins de cinq minutes.

Réponse rapide : qu'est-ce qu'une Claude Code Skill ?

Une skill est une capacité réutilisable invoquée par le modèle et stockée sous forme de SKILL.md (plus des scripts de support optionnels). Contrairement à un prompt système qui est toujours chargé, une skill est chargée à la demande lorsque le modèle estime qu'elle est pertinente pour votre requête. Vous rédigez un nom, une description de quand l'utiliser, et les instructions du corps. La description est le champ le plus important, car c'est ce que le modèle lit pour décider s'il doit déclencher la skill. Les skills vivent localement dans .claude/skills/ ou sont déployées à partir d'un registre, permettant ainsi à une équipe de partager une manière canonique de réaliser des migrations, des revues de code ou des publications.

Si vous souhaitez un contexte plus large sur le CLI lui-même, consultez mon guide ultime Claude Code pour 2026. Pour savoir en quoi les skills diffèrent des sous-agents toujours actifs, lisez comment j'ai automatisé mon flux de travail avec les sous-agents Claude Code.

Qu'est-ce qu'une skill concrètement, et de quoi est-elle composée ?

Une skill est un répertoire. Le minimum requis est un fichier SKILL.md. Optionnellement, elle peut regrouper des scripts, des modèles ou des documents de référence qui accompagnent la skill. La documentation des agent-skills d'Anthropic décrit une skill comme un ensemble empaqueté d'instructions et de ressources que le modèle peut charger lorsqu'elles sont pertinentes (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Je considère une skill comme une sous-routine nommée et versionnée pour le modèle. Trois choses la différencient d'un long prompt :

1. Elle est optionnelle. Le modèle ne la charge que lorsqu'une tâche semble correspondre à la description.
2. Elle est délimitée (scoped). Vous pouvez y attacher des fichiers et des scripts qui n'ont de sens que pour cette capacité spécifique.
3. Elle est partageable. Le dossier est portable entre les projets et les coéquipiers.

Le CLI lui-même est open source et la convention des skills y est documentée sur GitHub (github.com/anthropics/claude-code), où je vérifie les changements de comportement entre les versions.

Comment structurer un fichier SKILL.md ?

Le fichier a deux parties : le frontmatter YAML et un corps Markdown. Le frontmatter indique au modèle quand exécuter ; le corps lui dit quoi faire. Voici l'anatomie que j'utilise.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

Le corps est du Markdown simple. Je garde trois sections : un objectif en une ligne, une procédure numérotée et une porte explicite de "stop and confirm". Le name doit correspondre au nom du dossier. La description doit être rédigée pour le modèle, pas pour un humain, elle doit donc ressembler à une condition de déclenchement.

J'ai testé cela directement. Avec une description vague comme "aide avec les bases de données", la skill se déclenchait sur des questions SQL sans rapport. Après l'avoir réécrite en "Use when the user asks to create, modify, or roll back a database migration", la précision d'invocation est passée d'environ 60 pour cent à fiable. C'est la description qui fait le routage, donc passez votre temps de modification là-dessus.

Quand faut-il transformer quelque chose en skill ?

C'est la question que l'on me pose le plus souvent. Ma règle : si j'ai collé le même bloc d'instructions trois fois en deux semaines, et qu'il fait plus qu'un paragraphe, cela devient une skill. Ci-dessous est la matrice de décision que j'utilise réellement.

L'axe secondaire est le coût. Chaque skill chargée ajoute des tokens au contexte, un bloc d'instructions volumineux et toujours pertinent est donc préférable comme mémoire de niveau projet ou commande personnalisée plutôt que comme skill. Les skills excellent pour l'expertise conditionnellement pertinente.

Un cas concret où j'ai rédigé une skill : notre processus de publication exige la mise à jour d'un journal des modifications (changelog), l'incrémentation de trois fichiers de version, le taggage et la publication d'un résumé sur Slack. Je l'ai écrit une fois comme skill, et maintenant je dis "cut a release" et le modèle exécute toute la liste de contrôle dans l'ordre. Un cas concret où je ne l'ai pas fait : un refactoring ponctuel d'un fichier de configuration. Cela est resté un prompt.

Comment fonctionne le modèle de skill invoquée par le modèle ?

Le mécanisme qui rend les skills magiques est que vous ne les appelez pas. Vous décrivez le travail, et le modèle lit les descriptions des skills disponibles et en récupère la correspondante. Ceci est documenté dans la documentation officielle Claude Code (docs.anthropic.com/en/docs/claude-code).

Le flux se présente ainsi :

1. Vous tapez une requête en langage naturel.
2. Le modèle voit le name et la description de chaque skill installée.
3. Il évalue la pertinence par rapport à votre requête.
4. Le corps (et les fichiers regroupés) de la skill gagnante entrent dans le contexte.
5. Le modèle exécute les instructions.

La conséquence pratique : vous devez rédiger la description comme si vous écriviez une entrée de moteur de recherche pour le modèle. Commencez par le verbe et le champ de déclenchement. Comparez ces deux descriptions :

• Faible : "A skill for handling git things."
• Forte : "Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite."

La description forte nomme les verbes déclencheurs et la garde-barrière. C'est ce qui rend l'invocation fiable. Si vous connectez des skills avec des outils, le guide d'intégration Claude Code MCP explique comment les serveurs d'outils externes s'intègrent aux bundles de skills. Pour le protocole sous-jacent qui les relie, consultez MCP et le contexte du modèle.

Comment déclencher et déboguer une skill ?

Le déclenchement est majoritairement automatique, mais j'ai trois techniques délibérées pour le contrôle et le débogage.

• Être explicite. Dire "use the safe-migration skill" (utiliser la skill safe-migration) force l'invocation. Utile lorsque la description est ambiguë.
• Lister les skills installées. Demander au modèle de lister les skills disponibles et leurs descriptions. C'est ainsi que je confirme qu'une nouvelle skill est enregistrée.
• Inspecter la trace (trace). Lorsqu'une skill se déclenche par erreur, je lis quelle description a correspondu et j'affine le libellé du déclencheur.

Lorsqu'une skill ne se déclenche pas, la cause est presque toujours la description, pas l'emplacement du fichier. Je réécris la première phrase pour qu'elle commence par "Use when..." (Utiliser lorsque...) et j'ajoute les verbes spécifiques. Cela résout le problème neuf fois sur dix.

Voici la liste de contrôle de débogage que j'applique, dans l'ordre :

Skill versus sous-agent versus commande slash

Ces trois concepts se chevauchent, et les gens les confondent constamment. Je les distingue avec une simple distinction.

• Skill: instructions invoquées par le modèle plus fichiers optionnels. Idéal pour l'expertise conditionnelle.
• Sous-agent (Sub-agent): une instance Claude Code séparée effectuant un travail isolé. Idéal pour des tâches longues et parallèles. Mon article sur l'automatisation des sous-agents approfondit ce sujet.
• Commande slash (Slash command): un raccourci que vous tapez délibérément. Idéal pour les choses que vous voulez toujours à la demande.

Les skills sont les seuls parmi les trois que le modèle choisit pour vous. C'est leur superpouvoir et leur risque : une skill mal décrite gaspille du contexte en silence.

Comment partager des skills et utiliser un registre ?

Une skill n'est qu'un dossier, donc le partage est trivial en principe. Je dépose le dossier sous .claude/skills/ dans le repo et je le commite. Les coéquipiers l'obtiennent au clonage. Pour le partage inter-équipes, la communauté maintient des registres et les outils officiels pointent vers des emplacements communs.

Mon installation pratique :

1. Conserver les skills spécifiques à un projet dans le repo, sous contrôle de version.
2. Conserver les skills personnelles dans un repo dotfiles lié symoniquement à .claude/skills/.
3. Épingler les versions de skill lors du partage externe, car un changement de description peut modifier silencieusement le comportement.

La mise en garde honnête concernant le partage : une skill encode des hypothèses sur votre stack. Une skill de migration écrite pour Drizzle produira avec assurance un résultat incorrect dans un projet Prisma si la description ne garantit pas la portée. Indiquez toujours le framework et les garde-fous dans la description, et ajoutez une étape "stop and confirm" avant toute action destructrice. J'ai appris cela difficilement lorsqu'une skill partagée a exécuté une réécriture destructive sur la mauvaise branche, alors traitez chaque skill partagée comme non fiable jusqu'à ce que sa description prouve le contraire.

Crédits images

• Écran noir avec texte de code superposé sur un poste de travail de développeur — photo par Pixabay sur Pexels
• Gros plan de code de programmation sur un moniteur pendant le développement — photo par Christina Morillo sur Pexels
• Ordinateur portable affichant un éditeur de code pendant le développement logiciel — photo par luis gomes sur Pexels