Créer votre premier skill

Nous allons écrire un skill qui apprend à Claude à rédiger des descriptions de pull request dans un format cohérent, puis le tester de deux façons, en le nommant et en laissant Claude le trouver. Au passage, vous verrez comment Claude Code fait correspondre une demande à un skill, ce qu’il affiche quand un skill s’applique, et ce qui se passe quand deux skills portent le même nom.

Construire le skill pas à pas

C’est un skill de projet : il vit dans le dépôt, se commite, et toute l’équipe l’obtient au prochain git pull. Créez le dossier :

mkdir -p .claude/skills/pr-description

Déposez-y un fichier SKILL.md, en deux parties séparées par les tirets de l’en-tête :

---
description: Rédige la description d'une pull request à partir du diff de la branche. À utiliser quand on demande une description de PR, un résumé des changements ou un texte pour ouvrir une pull request.
argument-hint: [branche de base]
---

## Changements de la branche

!`git diff --stat main...HEAD`

## Instructions

Rédige la description de la pull request avec trois sections :

**Quoi** : une phrase qui dit ce que fait la PR.
**Pourquoi** : le contexte, en deux ou trois lignes.
**Changements** : une liste à puces des modifications, regroupées par thème ; signale les fichiers renommés ou supprimés.

Quatre éléments méritent d’être distingués. La description indique à Claude quand utiliser le skill : c’est elle, et elle seule, qui sert de critère de correspondance, d’où sa formulation riche en tournures que vous emploieriez réellement. Le nom de la commande vient du dossier (/pr-description) ; un champ name dans l’en-tête peut le remplacer. argument-hint s’affiche dans l’autocomplétion. La ligne !`git diff --stat main...HEAD` est une injection de contexte dynamique : Claude Code exécute la commande avant d’envoyer le skill et remplace la ligne par sa sortie, de sorte que Claude reçoit le diff réel, pas ce qu’il aurait deviné des fichiers ouverts. Tout ce qui suit constitue les instructions, ici un gabarit de sortie.

Vérifier que le skill vit

Inutile de redémarrer : Claude Code surveille les dossiers de skills et prend en compte un ajout ou une modification dans la session en cours. Si vous venez de créer le dossier .claude/skills/ lui-même, tapez /reload-skills une fois. Tapez ensuite /pr : le menu propose /pr-description avec sa description.

/skills liste tous les skills de la session, avec leur source, qui peut les déclencher et leur poids en tokens :

Le vrai test vient ensuite. Faites quelques modifications sur une branche, puis demandez simplement « écris une description de PR pour mes changements ». Claude indique qu’il utilise le skill pr-description, reçoit le diff et rédige la description selon votre gabarit. Refaites l’exercice la semaine suivante : même format, sans que vous ayez eu à le rappeler. Pour forcer l’usage, tapez /pr-description au début de votre message ; placé après du texte (« vas-y et /pr-description »), le nom ne lance rien directement mais autorise Claude à s’en servir dans sa réponse.

Comment se fait la correspondance

Au démarrage, Claude Code construit une liste des noms et des descriptions de tous les skills que Claude peut invoquer, et la met dans son contexte. Quand vous envoyez une requête, Claude confronte votre message à ces descriptions et cherche un recouvrement de sens, pas une correspondance littérale : « explique ce que fait cette fonction » peut déclencher un skill décrit comme « explique du code avec des diagrammes ». Un détail compte : Claude ne consulte un skill que si la tâche dépasse ce qu’il sait faire seul. « Lis ce fichier » ne déclenchera pas un skill de lecture, même parfaitement décrit.

Quand Claude charge un skill de lui-même, il passe par son outil Skill, soumis à votre mode de permission : en mode Auto, le classifieur l’examine comme les autres actions ; en mode Manual, Claude Code vous demande confirmation. Dans les deux cas, la conversation affiche quel skill a été chargé. Une fois chargé, le contenu du skill reste dans la conversation pour les tours suivants ; Claude Code ne relit pas le fichier à chaque message.

Quand deux skills portent le même nom

Vous clonez un dépôt qui contient un skill nommé comme l’un des vôtres. Lequel s’applique ? Pour un même nom de dossier, la documentation fixe l’ordre : organisation (réglages gérés) avant personnel, et personnel avant projet. Avec deploy à la fois dans ~/.claude/skills/ et dans .claude/skills/ du projet, /deploy lance le vôtre. Un skill qui porte le nom d’un skill fourni avec Claude Code le remplace (code-review remplace /code-review), mais pas ses alias (/review lance toujours l’original). Les skills de plugin, eux, ne rentrent jamais en collision : ils sont préfixés, /mon-plugin:deploy. Et un skill de sous-dossier dans un monorepo cohabite avec celui de la racine sous le nom /apps/web:deploy.

Cette hiérarchie permet à une organisation d’imposer des standards non contournables, tout en laissant chacun personnaliser le reste. Elle a une conséquence pratique : nommez précisément. Un skill baptisé review entrera tôt ou tard en collision ; frontend-review et backend-review cohabiteront et se déclencheront plus justement.

L’entretien courant tient en deux gestes : modifiez SKILL.md pour mettre à jour un skill (la session le relit), supprimez son dossier pour le retirer.

À vous de jouer

1. Créez le skill pr-description ci-dessus dans un projet Git, vérifiez avec /pr puis /skills.
2. Sur une branche avec quelques commits, demandez « écris la description de la PR » sans nommer le skill. Observez le chargement et le résultat.
3. Créez un second skill pr-description dans ~/.claude/skills/ avec une description différente, tapez /pr-description et notez lequel s’applique. Supprimez-le ensuite.
4. Choisissez la tâche que vous répétez le plus et écrivez seulement sa description, avec les mots que vous emploieriez vraiment pour la demander.

Sources officielles : Extend Claude with skills · Tools reference · Choose a permission mode

Points clés à retenir

• Un skill = un dossier .claude/skills/<nom>/ avec un SKILL.md ; le nom du dossier devient /nom
• La description est le seul critère de déclenchement ; !`commande` injecte des données réelles avant l’envoi
• Pas de redémarrage : la session détecte les ajouts et les modifications ; /reload-skills pour un nouveau dossier
• Même nom : organisation > personnel > projet ; les skills de plugin sont préfixés et ne rentrent pas en conflit
• Le contenu d’un skill chargé reste dans la conversation ; Claude ne relit pas le fichier à chaque tour