Vous utilisez Claude depuis une semaine et vous tapez toujours la même chose. Chaque fois que vous commitez du code, vous recollez les trois mêmes règles sur votre format de commit. Chaque fois que vous rédigez un doc, vous réexpliquez votre style. Claude fait bien le travail, puis oublie tout dès que la session se termine, et demain vous retapez tout.
Une compétence (« skill ») résout ce problème. C'est un petit dossier que vous créez une fois pour enseigner à Claude un workflow permanent, qu'il applique à chaque session sans que vous ayez à le redemander.
Voici comment ça fonctionne, en un coup d'œil : une compétence est un dossier contenant un seul fichier. Claude garde en permanence un résumé d'une ligne visible, et charge les instructions complètes uniquement lorsque votre requête correspond. C'est tout le mécanisme.
Dans ce guide, nous construisons une compétence réelle à partir de rien : commit-messages, qui écrit les commits git dans votre format exact. Si vous avez Claude installé et rien d'autre, vous pouvez suivre chaque étape.
Ce que vous obtiendrez
Au cœur, une compétence est un dossier avec un seul fichier requis, SKILL.md. Trois dossiers optionnels s'ajoutent ensuite au fur et à mesure que la compétence évolue :
1votre-nom-de-competence/2├── SKILL.md # Requis - le fichier principal de la compétence3├── scripts/ # Optionnel - code exécutable4├── references/ # Optionnel - documentation5└── assets/ # Optionnel - modèles, etc.
SKILL.md lui-même comporte deux parties : un en-tête court qui indique à Claude quand utiliser la compétence, et des instructions en dessous qui disent à Claude quoi faire. La raison de cette séparation est importante. Claude lit l'en-tête en permanence, donc il sait toujours que la compétence existe, mais il ne charge les instructions que lorsque votre requête correspond. Gardez cette distinction à l'esprit, car presque tout le reste de ce guide en découle.
Créez-la
Les compétences résident dans un dossier appelé .claude/skills dans votre répertoire personnel, que Claude Code et l'application de bureau lisent tous les deux. Il est caché et n'existe probablement pas encore, donc le moyen le plus rapide de le créer, ainsi que le dossier de votre compétence, est une seule commande.
Sur Mac, ouvrez Terminal et exécutez :
1mkdir -p ~/.claude/skills/your-skill-name
Sur Windows, ouvrez PowerShell et exécutez :
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"
Le nom du dossier n'est pas cosmétique. Claude l'utilise comme identifiant de la compétence, et une règle de formatage fait trébucher plus que toute autre :
- Utilisez le kebab-case : notion-project-setup ✔
- Pas d'espaces : Notion Project Setup ✖
- Pas de underscores : notion_project_setup ✖
- Pas de majuscules : NotionProjectSetup ✖
Dans ce dossier, créez un fichier nommé exactement SKILL.md et ouvrez-le dans n'importe quel éditeur de texte. Tout ce qui suit est ce qui va dans ce fichier.
Concevez-la avant de l'écrire
Les compétences qui marchent commencent par deux décisions, prises avant d'écrire une ligne du fichier. Les deux semblent sautables et aucune ne l'est.
D'abord, décidez exactement quand la compétence doit se déclencher. Notez deux ou trois situations réelles dans les mots qu'un utilisateur taperait réellement :
- « commit ces changements »
- « écris un message de commit pour ce diff »
- « stage et commit »
Ce n'est pas du travail inutile. Ces phrases deviennent la matière première de votre description et de vos tests plus tard, et une compétence conçue sans elles a tendance à être vague, précisément de la manière qui l'empêche de se déclencher.
Ensuite, décidez comment vous saurez qu'elle fonctionne. Le critère qui importe par-dessus tout est de savoir si la compétence se charge toute seule, sans que vous ayez à la nommer. Si vous devez l'invoquer manuellement à chaque fois, la compétence s'exécute techniquement mais a échoué dans sa tâche réelle. Il vaut aussi la peine de surveiller si elle termine la tâche sans que vous ayez à la corriger en cours de route, et si elle vous donne le même résultat à chaque session.
La description fait tout ou casse tout
De tout ce qui se trouve dans le fichier, la description dans l'en-tête fait le plus de travail, car c'est la seule partie que Claude lit pour décider s'il doit charger la compétence. Vos instructions pourraient être impeccables, cela n'aurait pas d'importance, puisque Claude n'y arrive jamais si la description ne correspond pas. C'est là que la plupart des compétences qui « ne marchent pas » échouent en réalité.
Une bonne description répond à deux questions en une phrase : ce que fait la compétence, et quand Claude doit l'utiliser. Cette seconde moitié est celle que les gens oublient.
Voici la différence :
1# faible - dit ce que c'est, ne donne rien à Claude pour faire correspondre une requête2description: Aide avec les commits git.34# forte - nomme les moments où elle doit se déclencher5description: Écrit les messages de commit git au format Conventional Commits. À utiliser lorsque l'utilisateur demande de commiter des changements, d'écrire un message de commit, ou de stage et commit des fichiers.
La version faible indique à Claude que la compétence existe mais ne la connecte jamais à quoi que ce soit que vous pourriez dire. La version forte nomme les phrases réelles, de sorte que lorsque vous tapez « commit ces changements », Claude a quelque chose à faire correspondre. Nommez les mots qu'un utilisateur utiliserait vraiment, gardez le tout sous 1024 caractères, et ne mettez pas de < ou > à l'intérieur.
Quand une compétence ne se déclenche pas, la correction est presque toujours ici. Ajoutez les formulations que vous utilisez réellement. Si vous dites « sauvegarder mon travail » mais que la description ne mentionne que « commit », Claude n'a aucun moyen de faire le lien. Et si le contraire se produit et que la compétence se déclenche alors qu'elle ne devrait pas, réduisez la description ou ajoutez un déclencheur négatif :
1description: Écrit les messages de commit git au format Conventional Commits. À utiliser lors du commit de changements. Ne pas utiliser pour écrire des commentaires de code ou de la documentation.
Il y a un moyen rapide de vérifier votre travail avant de vous y fier. Demandez directement à Claude :
« Quand utiliserais-tu la compétence commit-messages ? »
Claude vous relira votre description dans ses propres mots. Si cela ne correspond pas au moment où vous voulez réellement que la compétence se déclenche, vous avez trouvé votre problème, et il est dans la description, pas dans les instructions en dessous.
Rédigez des instructions que Claude suit vraiment
En dessous de l'en-tête vient le corps, en Markdown simple. C'est là que votre vrai workflow vit, et deux habitudes séparent les instructions que Claude suit de celles qu'il ignore tranquillement.
La première est d'être spécifique. Claude agit sur des instructions concrètes et passe sur les vagues, donc plus vous êtes précis, plus son comportement est fiable :
1# Mauvais2Valide le commit avant de finaliser.34# Bon5Exécute `python scripts/validate.py "<message>"`.6Si ça échoue, corrige ces points :7- Type invalide : utilise feat, fix, docs, refactor, test, chore8- Résumé de plus de 60 caractères : raccourcis-le
La seconde est l'ordre. Claude donne plus de poids à ce qu'il lit en premier, donc une règle enterrée en bas d'un long fichier est une règle oubliée. Mettez tout ce qui ne doit absolument pas être cassé en haut, sous un titre qui le signale :
1## Important2- Ligne de résumé sous 60 caractères, toujours3- Temps présent uniquement : « ajoute », pas « ajouté »
Il y a aussi une limite à ce que le langage peut garantir. Les instructions sont interprétées, ce qui signifie que Claude les suit bien mais pas de manière identique à chaque fois. Quand une vérification doit vraiment passer à chaque exécution, ne la décrivez pas en prose, déplacez-la dans un script et faites exécuter ce script par les instructions. Le code fait la même chose à chaque fois ; une phrase, non. (C'est à cela que sert le dossier scripts/, comme nous le verrons plus loin.)
Une structure qui tient la route pour la plupart des compétences ressemble à ceci :
1# Nom de la compétence23## Important4Règles critiques à ne pas manquer.56## Instructions7Étape par étape, spécifiques et actionnables.89## Exemples10Entrée et sortie concrètes. Claude copie les exemples plus fiablement qu'il ne suit les règles.
Gardez le fichier léger. Dès qu'il commence à dépasser ses instructions principales, c'est le moment de déplacer les détails supplémentaires ailleurs, ce qui est exactement le rôle des dossiers optionnels.
Scripts, références, ressources
Jusqu'ici, tout ce qui précède produit une compétence qui donne des instructions à Claude. Les trois dossiers optionnels la transforment en une compétence qui donne des outils à Claude, et c'est là qu'une compétence fait des choses qu'une simple invite ne peut pas faire.
scripts/ contient du code que Claude exécute, pour tout ce qui doit être exact. Plutôt que de faire confiance à Claude pour vérifier à l'œil si un commit est bien formaté, vous lui donnez un script qui vérifie :
1# scripts/validate.py2import sys3msg = sys.argv[1]4types = ("feat", "fix", "docs", "refactor", "test", "chore")56if msg.split(":")[0] not in types:7 print(f"Type invalide. Utilisez : {', '.join(types)}")8elif len(msg.split("\n")[0]) > 60:9 print("Résumé trop long (plus de 60 caractères)")10else:11 print("OK")
Ensuite, vous dites à Claude de l'utiliser dans SKILL.md :
1Avant de finaliser, exécute `python scripts/validate.py "<message>"`2et corrige tout ce qu'il signale.
Maintenant, la règle de formatage est appliquée par un code qui s'exécute de la même manière à chaque fois, au lieu de dépendre de la mémoire de Claude.
references/ contient de la documentation qui ne se charge que lorsque c'est nécessaire. Disons que vos conventions de commit s'étendent sur deux pages de portées, pieds de page et cas particuliers. Mettez tout cela dans SKILL.md et il se charge à chaque commit, même pour une ligne. Déplacez-le plutôt dans un fichier de référence :
1votre-nom-de-competence/2├── SKILL.md3└── references/4 └── conventions.md
Et pointez-y depuis le fichier principal :
1Pour la liste complète des conventions, voir references/conventions.md
Claude n'ouvre ce fichier que lorsque la tâche le demande. C'est toute la raison pour laquelle les compétences restent peu coûteuses à exécuter : les détails lourds restent sur le disque jusqu'à ce qu'ils soient réellement pertinents, au lieu de voyager dans le contexte à chaque fois.
assets/ contient des fichiers que la compétence utilise dans sa sortie plutôt que de les lire pour des conseils, comme un modèle, un fichier de configuration ou un logo. Une compétence de commit n'en a pas besoin, mais une compétence qui génère des rapports pourrait garder un template.md ici et le remplir à chaque fois, de sorte que chaque rapport ait la même structure.
Pris ensemble, ces trois dossiers font la différence entre une compétence qui dit à Claude comment vous travaillez et une qui donne à Claude les outils exacts pour faire le travail à votre manière.
La seule chose à retenir
Une compétence n'enseigne pas une nouvelle capacité à Claude. Il sait déjà écrire un commit. Ce que fait la compétence, c'est lui faire faire le travail à votre manière, à chaque fois, sans que vous ayez à le répéter.
Et quand une compétence ne marche pas, la cause n'est presque jamais les instructions sur lesquelles vous avez peiné. C'est la description. Claude décide s'il doit charger la compétence à partir de cette seule ligne, avant même de lire le travail en dessous. Faites la bonne description et tout ce qui se trouve en dessous sera enfin utilisé.
Si cela vous a été utile, rendez-vous sur mon profil et suivez-moi. J'écris sur la tech, l'IA et les systèmes qui fonctionnent vraiment.
