Skills Claude Code : créer, organiser et déclencher les siens

Guide vérifié le 2 octobre 2026 avec Claude Code 2.1.280 et la documentation officielle des skills. Les noms de fichiers, de champs et d’emplacements cités ici viennent de cette documentation ; elle évolue souvent et fait foi en cas d’écart.

Un skill est un fichier SKILL.md qui contient des instructions, rangé dans un dossier que Claude Code sait lire. Claude le charge de lui-même quand la demande correspond à sa description, ou on l’appelle directement en tapant /nom-du-skill. La documentation recommande d’en créer un dans deux situations : quand on colle sans cesse les mêmes instructions, la même check-list ou la même procédure dans la conversation, et quand une section du fichier CLAUDE.md est devenue une procédure plutôt qu’un fait.

Ce qu’est un skill et quand Claude le charge

La différence avec CLAUDE.md tient au moment du chargement. Le contenu de CLAUDE.md entre dans le contexte à chaque session. Pour un skill, seule sa description est présente en permanence dans la liste que Claude consulte ; le corps du fichier n’est lu qu’au moment où le skill est invoqué. Une longue procédure ne coûte donc presque rien tant qu’elle ne sert pas.

Une fois invoqué, le contenu du skill entre dans la conversation sous forme d’un message unique et y reste pour les tours suivants. Claude Code ne relit pas le fichier ensuite. Lorsque la conversation est compactée pour libérer de la place, Claude Code rattache la dernière invocation de chaque skill, mais n’en garde que les 5 000 premiers tokens, dans une enveloppe totale de 25 000 tokens pour l’ensemble des skills. Les consignes les plus importantes ont donc intérêt à figurer en haut du fichier.

Les anciennes commandes personnalisées ont été fusionnées dans les skills. Un fichier .claude/commands/deploy.md et un skill .claude/skills/deploy/SKILL.md créent tous les deux la commande /deploy et fonctionnent de la même façon. Le format en dossier ajoute des fichiers annexes, des réglages d’invocation et le chargement automatique. Claude Code embarque aussi ses propres skills, dont /code-review, /debug, /loop et /claude-api.

Les skills de Claude Code suivent le standard ouvert Agent Skills, utilisé par d’autres outils. Claude Code y ajoute des fonctions propres, comme le contrôle de l’invocation, l’exécution dans un sous-agent et l’injection de contexte dynamique.

Skill, CLAUDE.md, sous-agent ou commande : lequel pour quoi

Mécanisme	Quand il est chargé	Usage adapté
`CLAUDE.md`	À chaque session, en entier	Faits stables : commandes du projet, conventions, pièges connus
Skill	Description toujours visible, contenu chargé à l’invocation	Procédure ou référence utile seulement pour certaines tâches
Sous-agent	Lancé par Claude dans un contexte séparé	Tâche isolée qui ne doit pas encombrer la conversation principale
Fichier dans `.claude/commands/`	À l’appel de `/nom`	Ancien format, toujours reconnu ; le skill est préféré pour tout nouveau travail

Les deux derniers se combinent. Avec context: fork dans son en-tête, un skill s’exécute dans un sous-agent qui ne voit pas l’historique de la conversation : ses instructions doivent alors se suffire à elles-mêmes. Dans l’autre sens, un sous-agent peut précharger des skills, et leur contenu complet lui est injecté au démarrage. Le guide sur ce qu’il faut mettre dans CLAUDE.md détaille le premier mécanisme.

Anatomie d’un skill

Un skill est un dossier dont le nom devient, par défaut, la commande à taper. Ce dossier contient au minimum un fichier SKILL.md en deux parties : un en-tête YAML entre deux lignes ---, puis les instructions en Markdown. L’en-tête n’est lu que si le premier --- est sur la toute première ligne du fichier.

Tous les champs de l’en-tête sont facultatifs. La documentation en recommande un seul, description, parce que c’est lui qui permet à Claude de décider quand utiliser le skill. Les champs les plus utiles :

Champ	Rôle
`description`	Ce que fait le skill et quand l’utiliser. Sans lui, Claude prend la première ligne non vide du contenu.
`when_to_use`	Phrases déclencheuses ou exemples de demandes, ajoutés à la description.
`name`	Nom affiché dans le menu `/`. Par défaut, le nom du dossier.
`disable-model-invocation`	À `true`, seul l’utilisateur peut lancer le skill. Pour tout ce qui a des effets : déploiement, commit, envoi de message.
`user-invocable`	À `false`, le skill disparaît du menu et seul Claude peut l’utiliser. Pour du savoir de fond.
`allowed-tools`	Outils autorisés sans demande de permission pendant le tour qui invoque le skill.
`argument-hint`	Indication affichée à l’autocomplétion, par exemple `[numéro-de-ticket]`.
`paths`	Motifs de fichiers : le chargement automatique ne se fait que sur les fichiers correspondants.
`context` et `agent`	`context: fork` fait tourner le skill dans un sous-agent, du type indiqué par `agent`.
`model` et `effort`	Modèle et niveau d’effort à utiliser pendant que le skill est actif.

Le texte passé après la commande arrive dans le skill par la variable $ARGUMENTS. Une ligne de la forme !`git diff HEAD` exécute la commande avant que Claude lise le skill et remplace la ligne par son résultat : c’est l’injection de contexte dynamique.

Le dossier peut contenir d’autres fichiers : documentation de référence, exemples, scripts. Le SKILL.md les cite en indiquant ce que chacun contient, et Claude ne les ouvre que s’il en a besoin. La documentation conseille de garder SKILL.md sous 500 lignes et de déplacer le détail dans ces fichiers annexes.

Un skill construit pas à pas

L’exemple suivant est une version réduite et anonymisée d’un skill réel de la configuration de Jeremy Degryse, qui consigne les décisions dans un journal versionné. Il ajoute une ligne datée à docs/decisions.md.

1. Créer le dossier. Pour un skill propre à un projet, à la racine du dépôt :

mkdir -p .claude/skills/consigner-decision

2. Écrire le fichier .claude/skills/consigner-decision/SKILL.md :

---
description: Ajoute une décision datée au journal du projet, docs/decisions.md. À utiliser quand l'utilisateur tranche un choix technique, abandonne une option ou dit « c'est décidé », « on garde », « on laisse tomber ».
argument-hint: [décision en une phrase]
---

Ajoute une ligne à la fin de `docs/decisions.md`, en créant le fichier s'il n'existe pas :

`- AAAA-MM-JJ : <décision>`

- La date vient de la commande `date +%F`, jamais d'une estimation.
- La décision est celle passée en argument : $ARGUMENTS. Sans argument, reformule en une phrase le choix que l'utilisateur vient de faire.
- Une décision par ligne. Aucune ligne existante n'est modifiée.

Affiche ensuite la ligne ajoutée, rien d'autre.

La description dit à la fois ce que fait le skill et dans quelles situations l’utiliser, avec les mots que l’on emploie réellement. Les instructions donnent le format attendu et les règles, sans expliquer pourquoi. La documentation insiste sur ce point : une fois chargé, chaque ligne du skill reste dans le contexte et se paie à chaque tour.

3. Tester les deux modes d’invocation. Essai mené le 2 octobre 2026 en mode non interactif (claude -p), un seul passage par cas. Ce sont des observations, pas une mesure de fiabilité :

Appel direct avec Haiku 4.5, /consigner-decision On garde PostgreSQL pour la base de production : la ligne - 2026-10-02 : On garde PostgreSQL pour la base de production a été ajoutée au fichier.
Phrase naturelle avec Haiku 4.5, « Après réflexion, c’est décidé : on laisse tomber Redis, le cache en mémoire suffit. » : le skill n’a pas été chargé. Claude a répondu sans rien écrire.
Même phrase avec le modèle désigné par l’alias sonnet : le skill a été chargé et la ligne ajoutée.
Même phrase, description réduite à « Gestion du journal », avec l’alias sonnet : le skill du projet n’a pas été utilisé. Claude a choisi un autre skill, personnel celui-là, dont la description correspondait mieux, et a écrit dans un autre journal.

Le chargement automatique dépend donc du modèle comme de la rédaction de la description. Pour une action qui doit se produire à coup sûr, l’appel direct par /nom reste le seul chemin garanti. Le dernier cas montre aussi qu’un skill personnel est présent dans tous les projets de la machine, y compris un dossier de test.

Les pièges les plus courants

La description floue

C’est la première cause citée par la documentation quand un skill ne se déclenche pas : la description doit contenir les mots que l’utilisateur dirait naturellement. Les vérifications proposées : demander à Claude « What skills are available? » pour voir si le skill apparaît, reformuler la demande, ou l’appeler directement. À l’inverse, un skill qui se déclenche trop souvent se corrige par une description plus précise, ou par disable-model-invocation: true.

Le champ mal orthographié

Les noms de champs doivent correspondre exactement à la documentation, tirets compris, et Claude Code ignore sans message d’erreur un champ qu’il ne connaît pas. Dans la configuration de Jeremy Degryse, 9 skills sur 42 portent user_invocable: true, avec un tiret bas. Ce champ n’existe pas sous cette forme : il n’a aucun effet. Ici sans conséquence, puisque la valeur par défaut de user-invocable est déjà true, mais la même faute sur disable-model-invocation laisserait Claude lancer seul un skill de déploiement. Autre cas silencieux : si le YAML de l’en-tête ne se lit pas, le skill se charge sans aucun champ, l’appel direct fonctionne mais Claude ne peut plus s’appuyer sur la description. La commande claude plugin validate .claude/skills (Claude Code 2.1.233 et suivants) repère ces en-têtes illisibles.

Les descriptions coupées

La description et le champ when_to_use sont tronqués ensemble à 1 536 caractères dans la liste des skills. Cette liste a en plus un budget global d’environ 1 % de la fenêtre de contexte du modèle. Quand il y a trop de skills, Claude Code retire d’abord les descriptions des moins utilisés : leurs mots-clés disparaissent et ils ne se déclenchent plus. D’où la consigne de placer le cas d’usage principal en tête de description. /doctor estime le coût de cette liste, et la commande /context en affiche la taille réelle.

Les skills qui se recouvrent ou ne servent plus

Chaque skill listé pèse sur le contexte à chaque tour, qu’il serve ou non. La commande /skill-doctor (Claude Code 2.1.252 et suivants) indique le coût et la fréquence d’usage de chaque skill, et signale ceux qui n’ont jamais été invoqués. Un skill gardé mais rarement utile peut passer à "name-only" dans le réglage skillOverrides : son nom reste listé, sans sa description. Deux skills aux descriptions voisines se font concurrence, comme dans le dernier essai ci-dessus. Le tri de ces instructions, et le prompt qui aide à le faire, sont traités dans le guide pour trier ses instructions et ses skills.

La règle qui doit s’appliquer à chaque fois

Un skill reste une consigne que Claude applique avec jugement. Quand une règle doit tenir sans exception, par exemple avant chaque modification de fichier, la documentation renvoie vers un hook, exécuté par Claude Code à chaque événement, que Claude suive le skill ou non. Le hook peut être déclaré dans l’en-tête du skill, avec le champ hooks.

Où ranger ses skills et comment les versionner

Emplacement	Chemin	Disponible
Personnel	`~/.claude/skills/<nom>/SKILL.md`	Dans tous les projets de la machine
Projet	`.claude/skills/<nom>/SKILL.md`	Dans ce dépôt, pour toute l’équipe une fois versionné
Sous-dossier	`<sous-dossier>/.claude/skills/<nom>/SKILL.md`	Dès que Claude travaille sur des fichiers de ce sous-dossier
Entreprise	Répertoire des réglages gérés	Pour tous les utilisateurs de l’organisation
Plugin	`<plugin>/skills/<nom>/SKILL.md`	Là où le plugin est activé, sous la forme `/plugin:nom`

À nom égal, l’emplacement entreprise l’emporte sur le personnel, et le personnel sur le projet. Un skill créé par l’utilisateur remplace un skill fourni avec Claude Code qui porte le même nom. Les skills personnels ne sont pas disponibles dans les sessions Cowork ou cloud : il faut pour cela les activer sur le compte claude.ai, avec un en-tête limité aux six champs du standard (name, description, license, compatibility, metadata, allowed-tools), faute de quoi l’envoi échoue.

Pour le versionnement, un skill de projet se commite avec le code. Pour les skills personnels, la documentation précise que chaque entrée de ~/.claude/skills/ peut être un lien symbolique vers un dossier situé ailleurs. C’est le montage retenu dans la configuration de Jeremy Degryse : le dossier de skills vit dans un dépôt Git et ~/.claude/skills pointe vers lui, ce qui le synchronise entre plusieurs machines. Au 2 octobre 2026, ce dossier compte 42 skills, 17 au format dossier et 25 au format ancien de fichier de commande.

Pour supprimer un skill personnel ou de projet, il suffit d’effacer son dossier : Claude Code le retire de la session en cours. Pour le garder sans que Claude le lance seul, disable-model-invocation: true suffit.

Questions fréquentes

Faut-il savoir programmer pour écrire un skill ?

Non. Un skill est un fichier texte en Markdown avec quelques lignes d’en-tête. Seuls les skills qui exécutent des scripts ou injectent des commandes demandent de connaître ces commandes.

Combien de skills peut-on installer ?

La documentation ne fixe pas de nombre. La limite pratique vient du budget de la liste des skills, environ 1 % de la fenêtre de contexte : au-delà, des descriptions sont retirées et les skills concernés ne se déclenchent plus d’eux-mêmes.

Un skill écrit pour Claude Code fonctionne-t-il dans claude.ai ?

Oui si son en-tête se limite aux six champs du standard Agent Skills. Les fonctions propres à Claude Code, comme l’injection de commandes, ne fonctionnent ni dans le chat claude.ai ni par l’API.

Pour aller plus loin

Pour apprendre à structurer ses instructions, ses procédures et leurs déclencheurs dans un outil d’IA, DjeremIA propose des formations.

Sources consultées le 2 octobre 2026 : Claude Code, « Extend Claude with skills » ; standard Agent Skills. Essais réalisés avec Claude Code 2.1.280.