Vous collez sans cesse les mêmes instructions dans Claude Code ? Un skill peut les garder pour vous. Ce guide explique ce qu’est un skill d’agent, où ranger les fichiers, et comment en écrire et en tester un petit. Il aborde aussi l’installation de skills depuis les marketplaces de plugins et les erreurs qui empêchent un skill de se charger.
Tout ce qui suit a été vérifié dans la documentation officielle d’Anthropic en novembre 2026. Claude Code évolue souvent : la documentation en lien fait foi.
Qu’est-ce qu’un skill d’agent ?
Un skill est un dossier qui contient un fichier nommé SKILL.md. Ce fichier se compose de deux parties. En haut, un frontmatter YAML entre deux marqueurs ---, avec un name et une description. En dessous, des instructions en Markdown simple que Claude suit quand le skill s’exécute.
Un dossier de skill peut aussi contenir d’autres fichiers, comme des notes de référence, des modèles ou des scripts.
Les skills se chargent par étapes, ce qu’Anthropic appelle la divulgation progressive (progressive disclosure). Au démarrage, Claude ne charge que le nom et la description de chaque skill. Les instructions complètes se chargent quand le skill est déclenché, et les fichiers joints seulement si Claude les ouvre. Vous pouvez donc installer de nombreux skills sans saturer la fenêtre de contexte.
Ce qu’il vous faut
- Claude Code installé, avec une session connectée
- Un terminal et un éditeur de texte
- Un projet git pour tester (le skill d’exemple rédige des messages de commit)
Étape 1 : choisir où placer le skill
L’endroit où vous enregistrez un skill détermine les sessions qui peuvent le voir. Les deux emplacements que vous utiliserez le plus sont :
- Personnel :
~/.claude/skills/<skill-name>/SKILL.md. Disponible dans tous vos projets sur cette machine. - Projet :
.claude/skills/<skill-name>/SKILL.mddans un dépôt. Disponible dans les sessions de ce dépôt. Committez-le et toute votre équipe en profite.
Il existe aussi des emplacements entreprise, imbriqués et liés aux plugins. Si un skill personnel et un skill de projet portent le même nom, c’est le skill personnel qui l’emporte.
Un piège : les skills personnels de ~/.claude/skills/ ne sont pas lus par les sessions cloud ni par Cowork. Dans ce cas, la documentation recommande d’activer le skill sur votre compte claude.ai ou de le committer dans le dépôt.
Étape 2 : créer le dossier
Nous allons créer un skill personnel appelé commit-message.
mkdir -p ~/.claude/skills/commit-message
Résultat attendu : la commande n’affiche rien. Le dossier vide existe désormais.
Étape 3 : écrire SKILL.md
Créez ~/.claude/skills/commit-message/SKILL.md et collez-y ce contenu. Le nom du fichier doit être exactement SKILL.md.
---
name: commit-message
description: Writes a clear git commit message from the staged changes. Use when the user asks for a commit message, wants to commit their work, or asks how to describe their changes.
---
# Commit message writer
1. Run `git diff --staged` to see what is staged.
2. If nothing is staged, say so and stop.
3. Write a subject line in the imperative mood, under 72 characters.
4. Leave one blank line, then add a short body that explains why the change was made.
5. Show the message in a code block. Do not run `git commit` unless the user asks.
Quelques remarques sur le frontmatter :
namedevient la commande que vous tapez. Si vous l’omettez, Claude Code utilise le nom du dossier.descriptionest ce que Claude lit pour décider s’il utilise le skill. Indiquez d’abord ce que fait le skill, puis quand l’utiliser.- Le
---d’ouverture doit être la toute première ligne du fichier. Sinon, Claude Code traite l’ensemble du fichier comme du contenu brut.
Claude Code accepte d’autres champs, comme disable-model-invocation et allowed-tools. Mais les envois sur claude.ai et la Skills API n’en acceptent que six : name, description, license, compatibility, metadata et allowed-tools. Vous en tenir à name et description rend votre skill portable.
Étape 4 : le tester
Indexez une petite modification dans n’importe quel projet git, puis lancez Claude Code.
git add .
claude
Vous pouvez déclencher le skill de deux façons. D’abord, demandez-le avec des mots simples et laissez Claude le reconnaître grâce à la description :
Can you write a commit message for what I've staged?
Ou appelez-le directement par son nom :
/commit-message
Résultat attendu : Claude exécute git diff --staged et répond avec une ligne de titre et un court corps de message dans un bloc de code.
Inutile de redémarrer après une modification. Claude Code surveille ~/.claude/skills/ et le dossier .claude/skills/ du projet, et prend en compte les changements dans la session en cours.
Étape 5 : ajouter des fichiers complémentaires (facultatif)
Quand un skill grossit, sortez les détails de SKILL.md. La documentation conseille de rester sous 500 lignes. Une arborescence possible :
commit-message/
├── SKILL.md
├── examples.md
└── scripts/
└── check-length.sh
Faites référence aux fichiers supplémentaires depuis SKILL.md pour que Claude sache quand les ouvrir. Les scripts sont exécutés, pas chargés dans le contexte.
Étape 6 : installer des skills depuis une marketplace de plugins
Pas besoin d’écrire chaque skill vous-même. Dans Claude Code, les skills peuvent être fournis dans des plugins, et les plugins proviennent de marketplaces. La marketplace officielle d’Anthropic, claude-plugins-official, est ajoutée automatiquement la première fois que vous lancez une session interactive.
Le dépôt public de skills d’Anthropic sur GitHub peut aussi être ajouté comme marketplace. Son README donne ces commandes :
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
Dans une session, /plugin install ouvre le panneau des plugins pour que vous puissiez examiner le plugin et choisir une portée avant l’installation. Les skills de plugins ont un espace de noms : un skill nommé review dans un plugin appelé my-plugin s’exécute sous la forme /my-plugin:review.
Skills, serveurs MCP ou CLAUDE.md ?
CLAUDE.md contient les faits et règles permanents, chargés à chaque session, comme « use pnpm » (utiliser pnpm) ou « tests live in tests/ » (les tests sont dans tests/). Gardez-le court, car il est toujours dans le contexte.
Les skills contiennent des procédures et des documents de référence qui ne servent que de temps en temps. Anthropic conseille de créer un skill quand une section de CLAUDE.md est devenue une procédure, ou quand vous collez sans arrêt la même checklist dans le chat.
Les serveurs MCP relient Claude à des outils et données externes, comme une base de données, un outil de suivi des tickets ou une application de design. Un skill peut expliquer à Claude comment bien utiliser ces outils, mais il ne fournit pas la connexion.
Les skills en dehors de Claude Code
Le même format fonctionne dans tous les produits Claude. D’après la présentation d’Anthropic, les skills personnalisés peuvent être créés dans Claude Code, envoyés via l’API Claude ou ajoutés dans les paramètres de claude.ai. Les skills envoyés sur claude.ai doivent être envoyés séparément sur l’API.
Un mot sur la sécurité
Un skill n’est pas qu’un simple texte. Il peut contenir des scripts et pousser Claude à exécuter des commandes et à appeler des outils. Anthropic recommande de n’utiliser que des skills de sources fiables, c’est-à-dire ceux que vous avez écrits ou qui viennent d’Anthropic. Si vous en testez un d’une autre origine, lisez d’abord chaque fichier, scripts compris, et cherchez les appels réseau ou accès aux fichiers inattendus.
Erreurs courantes et solutions
Claude n’utilise jamais le skill de lui-même
La cause habituelle est une description trop vague. « Helps with git » (aide pour git) ne donne presque rien à Claude pour faire le rapprochement. Décrivez ce que fait le skill et les formulations que les gens emploieraient vraiment. Vous pouvez aussi demander à Claude « What skills are available? » (quels skills sont disponibles ?) pour vérifier qu’il est chargé, et utiliser /skill-name pour le lancer directement.
Le skill n’apparaît pas du tout
Vérifiez le chemin et la casse. Il doit s’agir de ~/.claude/skills/<skill-name>/SKILL.md, avec le fichier dans son propre dossier, et non posé directement dans skills/. La documentation liste aussi les caractères interdits dans un nom, comme <, > ou une espace au début ou à la fin.
Le frontmatter est cassé
Si le YAML ne peut pas être analysé, Claude Code charge quand même le corps, mais avec des métadonnées vides. /skill-name fonctionne toujours, mais Claude ne peut pas s’appuyer sur votre description. Lancez Claude Code avec claude --debug pour voir l’erreur, ou exécutez claude plugin validate ~/.claude/skills pour repérer les fichiers défectueux.
Règles de format du nom
Pour claude.ai et l’API, name ne doit contenir que des minuscules, des chiffres et des tirets, faire 64 caractères au maximum et ne pas contenir les mots anthropic ou claude. La description peut atteindre 1 024 caractères. Évitez aussi de nommer un dossier synced, nom que Claude Code réserve aux skills téléchargés depuis claude.ai.
Les modifications ne sont pas prises en compte
Les modifications des skills existants se chargent sans redémarrage. Mais si vous avez créé un dossier de skills de premier niveau qui n’existait pas au démarrage de la session, lancez /reload-skills. Pour les nouveaux plugins, lancez /reload-plugins ou redémarrez Claude Code.
Le skill se déclenche trop souvent
Rendez la description plus précise. Si vous voulez uniquement le lancer à la main, ajoutez disable-model-invocation: true au frontmatter.
En résumé
Un skill, c’est un dossier, un fichier SKILL.md et une bonne description. Commencez par une tâche que vous répétez chaque semaine, notez les étapes, puis testez avec une demande en langage courant et avec /skill-name. Examinez tout ce que vous installez avant de lui faire confiance.
Plus sur Claude : retrouvez tous nos guides Claude et Anthropic, classés par tâche.
Sources et documentation officielle
Liens vérifiés pour la dernière fois le 15 novembre 2026.





Écrire une réponse