Skills Claude Code : créer et partager des compétences

Créer un skill Claude Code prend dix minutes : un dossier, un fichier SKILL.md et deux champs d'en-tête obligatoires. Le faire déclencher au bon moment, le garder lisible après un compactage de la conversation et le partager sans que la copie d'un collègue diverge demande davantage de méthode. Nous faisons tourner 62 skills personnels sur le serveur où travaillent nos agents de développement, comptés le 18 octobre 2026, et la plupart de nos erreurs sont venues de ces trois points, presque jamais du format lui-même.

Ce tutoriel s'adresse aux développeurs et aux équipes techniques qui utilisent déjà Claude Code et veulent transformer leurs procédures répétées en compétences réutilisables. Nous avons rejoué chaque étape le 18 octobre 2026 sur Claude Code 2.1.302, dans un dépôt jetable, y compris deux contrôles qui annoncent un succès alors que rien n'a été vérifié.

Ce qu'un skill coûte en contexte, et à quel moment Claude Code le charge

Un skill ne coûte presque rien tant qu'il ne sert pas, puis tout son texte au moment où il sert. Claude Code le charge en trois temps, ce qu'Anthropic appelle la divulgation progressive. Au démarrage de la session, seuls le nom et la description de chaque skill entrent dans le contexte, environ 100 jetons par skill selon la présentation officielle des Agent Skills. Quand Claude décide d'utiliser le skill, ou quand vous tapez son nom, le corps du fichier SKILL.md rejoint la conversation. Les autres fichiers du dossier (références, modèles, scripts) ne sont lus que si les instructions y renvoient, et un script exécuté ne fait entrer que sa sortie, jamais son code.

Deux plafonds découlent de cette mécanique, et la documentation des skills de Claude Code les chiffre. La liste des skills disponibles dispose d'un budget égal à 1 % de la fenêtre de contexte du modèle, et chaque entrée, description et champ when_to_use réunis, est coupée à 1 536 caractères. Quand la liste déborde, Claude Code retire d'abord les descriptions des skills que vous appelez le moins : leur nom reste visible, mais les mots qui permettaient de les reconnaître disparaissent. Le second plafond intervient au compactage automatique. Claude Code rattache la dernière invocation de chaque skill, mais n'en garde que les 5 000 premiers jetons, dans une enveloppe commune de 25 000 jetons remplie à partir du skill le plus récent.

Deux règles d'écriture en sortent. La description porte tout le déclenchement, puisque c'est le seul texte que Claude lit avant de décider. Le haut du fichier compte davantage que le bas, puisque c'est lui qui survit quand une longue session se compacte. Le corps d'un skill n'est pas non plus relu aux tours suivants : une consigne écrite comme si elle ne valait que pour la première réponse sera oubliée ensuite, d'où la recommandation de la documentation de formuler « lance les tests après chaque modification » plutôt que « lance les tests ».

Créer un skill Claude Code pas à pas, avec un exemple testé

Un skill est un dossier qui porte son nom et contient au minimum un fichier SKILL.md. Placé dans ~/.claude/skills/, il sert dans tous vos projets. Placé dans .claude/skills/ à la racine d'un dépôt, il sert à tous ceux qui travaillent sur ce dépôt. En cas de doublon de nom, la documentation des skills fixe l'ordre de priorité : entreprise, puis personnel, puis projet. Les anciennes commandes personnalisées, fusionnées dans les skills, continuent de fonctionner.

Le skill ci-dessous rédige un message de commit à partir des changements en cours. Nous l'avons placé dans .claude/skills/message-commit/SKILL.md d'un dépôt de test qui contenait une fonction Python modifiée et pas encore commitée.

---
name: message-commit
description: Rédige un message de commit en français à partir des changements en cours du dépôt. À utiliser quand on demande « écris le message de commit », « prépare le commit » ou « résume mes changements ».
argument-hint: "[numéro de ticket]"
allowed-tools: Bash(git diff *) Bash(git status *)
---

Ticket lié : $ARGUMENTS

Fichiers modifiés :
!`git diff HEAD --stat`

1. Lire le détail avec `git diff HEAD`.
2. Écrire une première ligne de moins de 70 caractères, préfixée par le type (feat, fix, docs) et suivie du ticket.
3. Ajouter un paragraphe court qui explique pourquoi le changement est fait.
4. Ne citer que ce que le diff montre : jamais un test qui n'a pas tourné.

L'en-tête tient en quatre champs, tous décrits dans la référence des champs de Claude Code. name devient la commande /message-commit et reprend par défaut le nom du dossier. description dit ce que fait le skill et quand s'en servir. argument-hint s'affiche dans le menu pour rappeler l'argument attendu, que le corps récupère par $ARGUMENTS, ou par $0 et $1 pour des positions précises. allowed-tools pré-autorise les deux commandes git pendant le tour qui invoque le skill. La ligne qui commence par un point d'exclamation suivi d'une commande entre accents graves est une injection de contexte : Claude Code exécute git diff HEAD --stat avant que le modèle ne lise le texte, puis remplace la ligne par la sortie de la commande.

Lancé par claude -p "/message-commit TCK-42", le skill a rendu une première ligne de 57 caractères, un paragraphe qui précise qu'aucun test n'a tourné, et une remarque que nous n'avions pas demandée : la fonction modifiée renvoie désormais 5.0 au lieu de 5 quand on ne passe pas de remise. Pour l'affirmer, Claude a exécuté la fonction en Python, alors que le skill ne pré-autorisait que deux commandes git, nos réglages de permissions l'y autorisant par ailleurs. La documentation le dit sans ambiguïté : allowed-tools accorde des permissions et n'en retire aucune. Pour interdire un outil pendant un skill, il faut le champ disallowed-tools, et pour l'interdire partout, une règle de refus dans les réglages de permissions.

Le nom mérite une précaution si vous comptez partager le skill. La spécification Agent Skills limite name à 64 caractères, en minuscules, chiffres et tirets, sans tiret au début, à la fin ni en double, et l'API Claude interdit en plus les mots « anthropic » et « claude ». Claude Code se montre plus tolérant : un dossier nommé Mauvais_Nom est passé sans la moindre remarque dans claude plugin validate --strict pendant notre test. Un skill nommé ainsi fonctionne chez vous et sort du standard dès qu'il voyage. Nous nommons donc les nôtres en minuscules avec des tirets, en commençant par ce qu'ils produisent : message-commit, diagnostic-panne, fix-racine.

Écrire une description qui déclenche le skill au bon moment

Une bonne description dit ce que fait le skill, quand l'utiliser, et contient les mots que vous tapez vraiment quand le besoin arrive. Les bonnes pratiques de rédaction d'Anthropic ajoutent une consigne qui surprend : l'écrire à la troisième personne (« Rédige un message de commit »), parce que la description est injectée dans le prompt système et qu'un « je peux vous aider » y mélange les points de vue. Elles citent aussi le contre-exemple à éviter, « Helps with documents », trop vague pour que Claude le préfère à un autre skill parmi plus d'une centaine de skills possibles.

Dans notre catalogue, la description sert d'index de déclencheurs. Le skill qui couvre les pièges du shell liste les messages d'erreur tels qu'ils s'affichent (« blocked by hook », « exit 144 ») et les phrases que nous écrivons dans ces moments-là, en français comme en anglais, puisque nous travaillons dans les deux langues. Le prix de cette méthode se mesure : nos 62 descriptions personnelles cumulent 35 952 caractères au 18 octobre 2026, et 7 d'entre elles dépassent les 1 024 caractères du standard ouvert. Claude Code les accepte jusqu'à 1 536, mais ces sept skills ne passeraient ni un validateur du standard ni un envoi par l'API Claude, dont la présentation des Agent Skills fixe la même limite. Placez le cas d'usage principal dans la première phrase, puisque c'est la fin qui saute en cas de coupure.

Deux symptômes trahissent une description ratée. Si le skill ne se déclenche jamais, la section de dépannage des skills conseille de vérifier qu'il apparaît quand on demande à Claude « What skills are available? », de reformuler la demande au plus près de la description, puis de l'appeler directement par /nom-du-skill. S'il se déclenche trop souvent, resserrez la description, ou ajoutez disable-model-invocation: true pour le réserver à l'appel manuel. Depuis la version 2.1.252, la commande /skill-doctor rend le coût en contexte de chaque skill et signale ceux qui n'ont jamais servi. Pour un skill rarement utilisé que vous voulez garder, le réglage skillOverrides accepte la valeur "name-only" : le skill reste dans la liste sans sa description, ce qui libère du budget pour les autres.

Les principes de notre guide du prompt engineering s'y appliquent, avec une différence : un prompt sert une fois devant vous, alors qu'une description travaille dans des sessions que vous ne regardez pas, et son échec ne produit aucun message d'erreur.

Skill, CLAUDE.md ou hook : où ranger chaque consigne

Une consigne qui doit tenir à chaque fois va dans un hook, une convention utile partout va dans le fichier CLAUDE.md, et une procédure qui ne sert qu'à certains moments va dans un skill. La documentation de Claude Code le formule dans sa section de dépannage : si Claude a sauté une règle qui doit tenir à chaque fois, déplacez-la dans un hook, que Claude Code exécute à chaque événement, que le modèle suive le skill ou non. Un skill transmet une intention, un hook impose une vérification. Nous avons détaillé la mémoire et les hooks dans notre méthode pour utiliser Claude Code, et ce partage s'applique d'abord au fichier de mémoire.

Notre fichier d'instructions global l'a appris à ses dépens. Il pesait 160 388 caractères à la mi-septembre 2026 et encore 123 407 début octobre, alors que Claude Code charge en entier tout CLAUDE.md de moins de 4 Mio à chaque session, et que sa documentation de la mémoire recommande de sortir vers un skill toute procédure en plusieurs étapes. Nous avons fixé une règle de tri : une phrase qui doit arrêter un geste reste dans le CLAUDE.md, une phrase qui l'explique part dans le skill du thème. Après la dernière passe, le 7 octobre, le fichier est descendu à 73 185 caractères, règles conservées. Les récits d'incident, les recettes et les parades vivent désormais dans des skills qui ne se chargent que lorsque le sujet se présente.

Les skills ont leur propre dette, et la nôtre se mesure aussi. Cinq de nos 62 skills dépassent les 500 lignes que recommandent les bonnes pratiques d'Anthropic et la spécification du standard, et le plus gros atteint 180 967 caractères. À chaque appel, il fait entrer plusieurs dizaines de milliers de jetons dans la conversation, et un compactage n'en garde que les 5 000 premiers. Nous en avons tiré une règle de structure : les interdits en tête du fichier, une phrase chacun, puis le détail rangé dans des fichiers annexes vers lesquels le corps renvoie, à un seul niveau de profondeur comme le conseillent les bonnes pratiques. Une référence imbriquée dans une autre référence risque d'être lue en partie seulement.

Deux champs complètent ce rangement. context: fork exécute le skill dans un sous-agent, du type indiqué par agent (Explore, Plan ou general-purpose), qui ne voit pas l'historique de la conversation et tourne en arrière-plan par défaut. La documentation des skills prévient qu'un tel skill doit contenir une tâche explicite, car un sous-agent qui ne reçoit que des principes ne produit rien. user-invocable: false retire le skill du menu tout en le laissant disponible pour Claude, ce qui convient à une connaissance de fond qu'aucun humain n'appellera par son nom.

Partager ses skills avec une équipe sans copies qui divergent

Pour une équipe qui travaille sur un même dépôt, le plus direct reste de committer le dossier .claude/skills/ : chaque clone reçoit les skills, et leur historique suit celui du code. Une précaution l'accompagne. Selon la documentation des skills, la confiance accordée à un espace de travail ne bloque pas le champ allowed-tools des skills de dépôt, donc relisez les skills d'un dépôt tiers avant d'y lancer Claude Code. Pour diffuser les mêmes skills dans plusieurs dépôts, l'outil prévu est le plugin : un dossier qui contient un manifeste .claude-plugin/plugin.json, dont le champ name est le seul obligatoire, et un dossier skills/ à sa racine. Ses skills sont préfixés par le nom du plugin, /outils-equipe:message-commit par exemple, ce qui évite les collisions avec les skills personnels.

Le cycle de diffusion tient en quatre commandes, que la documentation de création de plugins décrit en détail :

claude plugin validate ./outils-equipe
claude --plugin-dir ./outils-equipe
claude plugin marketplace add votre-org/catalogue-claude
claude plugin install outils-equipe@catalogue-claude

La première vérifie le manifeste et l'en-tête de chaque skill, la deuxième charge le plugin pour une seule session sans l'installer. Une fois testé, le plugin rejoint un catalogue de plugins : un dépôt git, privé si vous le souhaitez, qui contient un fichier .claude-plugin/marketplace.json avec un name, un owner et la liste des plugins. Vos collègues ajoutent ce catalogue une fois, installent le plugin par son nom et reçoivent ensuite vos mises à jour. Installé avec la portée projet, le plugin s'active pour tous les membres du dépôt via le fichier .claude/settings.json commité, chacun l'installant ensuite sur sa machine. Les skills activés sur un compte claude.ai suivent un autre chemin : selon la documentation des skills, depuis la version 2.1.273, ils se téléchargent dans ~/.claude/skills/synced/, en lecture seule, environ toutes les dix minutes pendant le travail.

Le standard ouvert élargit la portée du partage. Développé à l'origine par Anthropic puis ouvert sous le nom Agent Skills, le format est repris par d'autres agents : le site du standard affichait 46 outils compatibles le 18 octobre 2026, dont Codex, GitHub Copilot, Cursor et Gemini CLI. Nous utilisons Claude Code et Codex sur les mêmes projets, et la documentation de Codex sur les skills indique qu'il lit ~/.agents/skills et suit les liens symboliques. Nous gardons donc une seule source par skill, et l'autre catalogue pointe vers elle : 13 skills de notre dossier Claude Code sont des liens vers le catalogue partagé avec Codex, et 4 font le chemin inverse. Deux copies d'un même skill finissent par diverger, et l'agent qui lit la mauvaise n'a aucun moyen de s'en apercevoir.

Tester un skill sans se fier à un faux vert

Un skill se teste à trois niveaux : son format, son déclenchement et son effet. Le format se contrôle avec claude plugin validate, que la documentation des skills recommande aussi sur un simple dossier de skills. Sur un en-tête cassé par un guillemet non refermé, la commande a échoué chez nous avec un code de sortie 1 et un message explicite : selon ce message, à l'exécution, ce skill se charge avec des métadonnées vides, donc sans description, donc sans déclenchement automatique. Sans ce contrôle, rien ne l'aurait signalé, puisque l'appel manuel par /nom-du-skill continue de fonctionner. Un validateur ne juge que pour l'outil qui l'exécute : sept de nos en-têtes passent celui de Claude Code et sont refusés par un parseur YAML strict comme PyYAML, à cause de la typographie française. Une description écrite « Émission : devis et factures » contient un deux-points suivi d'une espace, qu'un YAML strict lit comme une nouvelle clé. Si le skill doit voyager, mettez la description entre guillemets.

Le même contrôle peut aussi rassurer à tort. Lancé sur notre dossier personnel, il a affiché « Validation passed » avec un code de sortie 0, en précisant dans un avertissement que 13 entrées étaient des liens symboliques et n'avaient pas été lues, alors qu'une session Claude Code les charge bien. Le validateur ne suit pas les liens, la session si : un skill partagé par lien symbolique se valide à son chemin réel. Le deuxième piège touche l'injection de contexte en mode non interactif. Nous avons écrit un skill dont la commande injectée, git diff --stat origin/main...HEAD, échoue faute de dépôt distant. Lancé par claude -p, il a rendu un résultat vide, avec le statut success, zéro tour de modèle et un code de sortie 0. En remplaçant seulement la référence par main...HEAD, le modèle s'est bien lancé et a enchaîné trois tours. Dans une tâche planifiée ou une CI, vérifiez donc que la réponse n'est pas vide au lieu de vous fier au code de sortie.

Le déclenchement et l'effet demandent des cas d'usage réels. Les bonnes pratiques d'Anthropic recommandent d'écrire au moins trois scénarios d'évaluation avant de rédiger une longue documentation, de mesurer Claude sans le skill puis avec, et de tester chaque modèle visé, Haiku n'ayant pas besoin du même niveau de détail qu'Opus. Pour un skill livré en plugin, claude plugin eval exécute ces cas avec et sans le plugin et note l'écart, selon la documentation des plugins, et la documentation des skills décrit un correcteur tool_used: Skill qui mesure la fréquence de déclenchement après chaque retouche de la description.

Reste la sécurité. La présentation des Agent Skills conseille de n'utiliser que des skills écrits par vous ou fournis par Anthropic, et d'auditer chaque fichier d'un skill tiers comme un logiciel qu'on installe, scripts compris, en cherchant les appels réseau inattendus et les accès à des fichiers sans rapport avec l'objet annoncé. Le réglage "disableSkillShellExecution": true, décrit dans la documentation des skills, désactive l'injection de commandes pour les skills qui ne sont ni intégrés à Claude Code ni gérés par votre organisation.

Par quels skills commencer dans une équipe

Commencez par les procédures que vous dictez déjà à Claude chaque semaine, plutôt que par une bibliothèque téléchargée. Notre critère de bascule tient en une ligne : la troisième fois qu'une même consigne est retapée, elle devient un skill. Sur nos projets, les premiers qui rapportent sont ceux-ci :

• la rédaction des messages de commit et des descriptions de pull request, avec les conventions de l'équipe ;
• la checklist de mise en production, en appel manuel seulement avec disable-model-invocation: true ;
• le diagnostic d'une panne de service tiers, qui commence par la page de statut du fournisseur avant le code ;
• la relecture de sécurité d'une modification, avec ses scripts de contrôle rangés dans le dossier du skill.

Un skill qui pilote un outil externe gagne souvent à s'appuyer sur un serveur MCP plutôt que sur des appels improvisés en ligne de commande, et nous avons expliqué le fonctionnement du Model Context Protocol dans un article dédié. Pour une équipe qui démarre, la difficulté est rarement technique : il faut décider qui maintient le catalogue, comment une modification de skill est relue avant d'être diffusée, et où vit la version de référence. Former les développeurs à ces règles fait partie du chantier, et nous avons comparé les options dans notre article sur la formation Claude Code. Pour faire auditer un catalogue existant ou monter un plugin d'équipe, il suffit de contacter Noxcod.

Questions fréquentes sur les skills Claude Code

Quelle différence entre un skill et une commande slash ?

Dans Claude Code, il n'y en a presque plus : selon la documentation des skills, les commandes personnalisées ont été fusionnées dans les skills. Un fichier .claude/commands/deploy.md et un dossier .claude/skills/deploy/ créent tous les deux la commande /deploy, et les anciens fichiers continuent de fonctionner. Le dossier apporte en plus des fichiers annexes, le choix de qui peut déclencher le skill et le chargement automatique quand la demande correspond à la description. Pour un nouveau besoin, partez directement sur un skill.

Un skill écrit pour Claude Code fonctionne-t-il dans Codex ou Copilot ?

Le format de base, oui : un dossier avec un SKILL.md qui porte name et description suit le standard ouvert Agent Skills, que Codex et GitHub Copilot ont repris d'après le site du standard. Les champs propres à Claude Code, comme context: fork, l'injection de commandes ou la variable ${CLAUDE_SKILL_DIR}, ne figurent pas dans la spécification. Pour un skill portable, gardez un nom conforme, une description de moins de 1 024 caractères et des instructions en Markdown sans dépendance à un outil précis.

Combien de skills peut-on installer avant que Claude ne les ignore ?

Il n'existe pas de nombre fixe, mais un budget que la documentation des skills détaille : la liste des noms et descriptions ne peut occuper que 1 % de la fenêtre de contexte du modèle. Au-delà, Claude Code retire d'abord les descriptions des skills les moins utilisés, qui gardent leur nom dans la liste mais perdent les mots qui permettaient à Claude de les reconnaître. La commande /doctor estime ce coût, /skill-doctor repère les skills jamais invoqués, et le réglage skillListingBudgetFraction permet d'élargir le budget si vous acceptez d'y consacrer plus de contexte.

Un skill peut-il exécuter du code sur ma machine ?

Oui, de deux façons. Les scripts rangés dans le dossier du skill sont lancés par Claude avec ses outils habituels, et les lignes d'injection de contexte exécutent une commande shell avant même que le modèle lise le skill. Dans Claude Code, d'après la présentation des Agent Skills, un skill dispose du même accès réseau que n'importe quel programme de votre poste. Auditez donc un skill tiers comme un logiciel, et désactivez l'injection de commandes des skills non gérés avec disableSkillShellExecution si votre équipe en installe beaucoup.

Où trouver des skills prêts à l'emploi ?

Anthropic met à disposition des skills open source dans le dépôt anthropics/skills et des plugins dans son catalogue officiel, que Claude Code ajoute à la première session interactive selon la présentation des plugins, et que la commande /plugin permet de parcourir. Le plugin skill-creator de ce catalogue, cité par la documentation des skills, aide aussi à écrire puis améliorer vos propres skills. Pour tout le reste, appliquez la règle d'Anthropic : un skill dont vous ne connaissez pas l'auteur se relit fichier par fichier avant installation, scripts et liens externes compris.