Skills Claude Code : comment fonctionnent les compétences, SKILL.md et quand l'agent les charge

Ce que sont les skills dans Claude Code

Un skill (compétence) est un dossier contenant un fichier SKILL.md, dans lequel on décrit une instruction pour un type de tâche précis : comment déployer le projet, comment mener une revue de code, comment publier une version. L'agent connaît l'existence du skill dès le début de la session, mais ne le lit en entier que lorsque la tâche l'exige vraiment.

Les skills de Claude Code résolvent un problème familier à tous ceux qui maintiennent longtemps un CLAUDE.md : le fichier d'instructions grossit. La procédure de déploiement de 80 lignes n'est nécessaire qu'une fois par semaine, mais elle occupe de la place dans le contexte de chaque session, y compris lorsqu'on corrige une faute de frappe dans le README. Le skill sort ces procédures du contexte permanent et ne les charge qu'à la demande.

De quoi se compose un skill

Un skill minimal, c'est un dossier et un fichier. Les skills de projet se trouvent dans le dépôt, les skills personnels dans le répertoire de l'utilisateur :

.claude/skills/deploy/SKILL.md      # skill du projet, partagé par l'équipe via git
~/.claude/skills/review/SKILL.md    # skill personnel, disponible dans tous les projets

À côté de SKILL.md, vous pouvez placer des fichiers d'accompagnement : modèles, scripts, documentation de référence. L'agent ne les ouvrira que si le texte principal du skill y renvoie et qu'ils sont nécessaires :

.claude/skills/deploy/
├── SKILL.md           # instruction principale
├── checklist.md       # check-list détaillée, lue par renvoi
└── rollback.sh        # script de retour arrière

Frontmatter : name et description

Le fichier commence par un bloc YAML encadré de lignes ---. Deux champs sont plus importants que les autres : name, le nom court du skill, et description, qui décrit ce que fait le skill et quand l'appliquer.

---
name: deploy
description: Déploiement du site sur l'hébergement par FTP. À utiliser lorsqu'il faut envoyer des modifications sur le serveur, vérifier les écarts avec le serveur ou annuler un déploiement.
---

# Déploiement

1. D'abord un essai à blanc : `./deploy.sh -n`.
2. Vérifier la liste des fichiers : elle ne doit contenir ni secrets ni scripts de test.
3. Envoyer : `./deploy.sh`.
4. Ouvrir les pages modifiées et vérifier qu'elles répondent 200.

Pour le retour arrière, voir rollback.sh dans ce dossier.

Sous le frontmatter, il y a du Markdown ordinaire : étapes, commandes, restrictions, renvois vers les fichiers voisins. Rédigez-le comme vous rédigeriez une instruction pour un nouveau collègue qui fait cette tâche pour la première fois.

Quand l'agent charge un skill

Au début de la session, seuls le nom et la description de chaque skill disponible entrent dans le contexte. Cela représente quelques lignes par skill, on peut donc en garder plusieurs dizaines. Lorsque la demande de l'utilisateur ou l'étape en cours correspond à la description, l'agent invoque le skill, et ce n'est qu'alors que le texte complet de SKILL.md est chargé.

Il en découle une règle pratique essentielle : le skill se déclenche d'après sa description. L'agent ne voit pas le corps du skill tant qu'il n'a pas décidé de l'ouvrir. Si la description dit « Skill auxiliaire », l'agent ne comprendra pas quand il est nécessaire. Si elle dit « Déploiement sur l'hébergement ; à utiliser lorsqu'il faut envoyer des modifications sur le serveur ou annuler un déploiement », il comprendra.

Outre le choix automatique, on peut invoquer un skill explicitement par son nom, avec une barre oblique, par exemple /deploy. C'est pratique lorsque vous savez précisément quelle procédure il faut, et que vous ne voulez pas compter sur la correspondance automatique entre la demande et la description.

Comment écrire une description qui déclenche le skill

• Ce que fait le skill — en une phrase, avec un verbe : « Déployer le site », « Revoir les modifications avant le commit ».
• Quand l'utiliser — listez les formulations avec lesquelles l'utilisateur demande réellement cette tâche : « envoie sur le serveur », « mets en ligne », « annule ».
• Quand ne pas l'utiliser, si le skill se confond facilement avec un voisin : « pas pour le déploiement du bot, uniquement pour le site ».
• Évitez les formules vagues comme « skill utile » ou « aide au travail » : elles ne transmettent aucun signal.

Divulgation progressive

Les skills reposent sur le principe de la divulgation progressive (progressive disclosure) : l'information est fournie par couches, et chaque couche suivante n'est chargée que lorsqu'elle est nécessaire.

C'est la même idée qu'un routeur plutôt qu'un pavé dans le fichier d'instructions : une courte carte toujours à portée de main, et les détails par renvoi. La différence est que le skill fait de ce chargement un mécanisme standard, au lieu de compter sur le fait que l'agent ouvrira de lui-même le bon document. Autre avantage : le script de la troisième couche peut simplement être exécuté par l'agent sans que tout son code soit chargé dans le contexte.

Skills, CLAUDE.md et commandes slash : quelle différence

Ces trois mécanismes transmettent des instructions à l'agent, mais à des moments différents et avec un coût différent pour le contexte.

La règle de choix est simple. Si une instruction est nécessaire dans presque toutes les tâches, elle a sa place dans CLAUDE.md. Si elle est nécessaire dans les tâches d'un type donné, c'est un skill. Si vous tapez vous-même à chaque fois la même longue requête, c'est un candidat pour une commande ou pour un skill appelé manuellement.

Ne déplacez pas les interdits stricts dans un skill. Le skill peut ne jamais être chargé, alors que la règle « ne jamais committer de secrets » doit valoir en permanence. Ces invariants restent dans CLAUDE.md et sont, si possible, appuyés par un mécanisme : hooks, droits d'accès, contrôles en CI.

Comment créer un skill pour Claude Code : pas à pas

1. Repérez une procédure qui se répète. Bon signe : vous avez déjà expliqué trois fois la même chose à l'agent, ou une section du CLAUDE.md ne sert que dans une tâche sur dix.
2. Créez le dossier .claude/skills/<nom>/ et le fichier SKILL.md à l'intérieur.
3. Rédigez le frontmatter avec name et description, en précisant clairement quand appliquer le skill.
4. Décrivez les étapes avec des commandes concrètes et des critères de réussite : ce qu'il faut vérifier, quel résultat compte comme un succès.
5. Sortez le contenu long dans des fichiers voisins et renvoyez-y depuis le texte principal.
6. Supprimez le doublon du CLAUDE.md en ne gardant qu'une ligne de renvoi : « Déploiement — skill deploy ».
7. Vérifiez : dans une nouvelle session, formulez la tâche avec vos propres mots, sans nommer le skill, et voyez si l'agent le prend en compte. Sinon, réécrivez la description.

Exemples de skills

Skill de déploiement

Le candidat classique : procédure rare, longue et risquée, où une erreur coûte cher. Le skill fixe l'ordre des étapes (d'abord l'essai à blanc, ensuite l'envoi), ce qu'il ne faut jamais publier, comment vérifier le résultat et comment revenir en arrière. L'agent n'a pas besoin de garder tout cela en tête à chaque modification du code, seulement au moment où il est question du serveur.

Skill de revue

---
name: review
description: Revue des modifications en cours avant le commit. À utiliser lorsqu'on demande de vérifier le diff, de trouver des erreurs dans les modifications ou de préparer les changements pour un commit.
---

# Revue des modifications

1. Obtenir le diff : `git diff` et `git diff --staged`.
2. Pour chaque fichier modifié, vérifier :
   - la saisie utilisateur est échappée à l'affichage ;
   - les requêtes SQL sont paramétrées ;
   - il ne reste ni sortie de débogage ni fichiers temporaires.
3. Lancer les tests et le linter du projet (les commandes sont dans CLAUDE.md).
4. Rapport : liste des problèmes avec le fichier et la ligne, des plus graves aux plus mineurs.
   S'il n'y a aucun problème, le dire clairement, sans remarques inventées.

Un tel skill transforme « regarde si tout est correct » en une vérification reproductible, avec le même ensemble de points à chaque fois.

Skill de fin de session

Un autre type utile : un rituel de fin de travail. Arrêter l'environnement local, supprimer les fichiers temporaires, compléter le journal de progression avec ce qui est fait et ce qui reste, faire un commit avec une description détaillée. Cela répond directement à la perte de contexte entre les sessions : la session suivante part de l'état réel du dépôt, et non de suppositions.

Erreurs fréquentes

• Description floue. Le skill existe, mais l'agent ne l'appelle pas. On corrige en réécrivant description avec des déclencheurs concrets.
• Skill-pavé. On a transféré dans SKILL.md toute une ancienne section de 400 lignes. Le problème du contexte surchargé revient, simplement plus tard. Gardez le texte principal court et placez les détails dans les fichiers voisins.
• Doublon avec CLAUDE.md. La même procédure est décrite à deux endroits, et les deux versions finissent par diverger. La source de vérité doit être unique.
• Skills qui se chevauchent. Deux skills aux descriptions proches : l'agent choisit l'un au hasard. Séparez-les par des formulations explicites « utiliser / ne pas utiliser ».
• Commandes obsolètes. Le script a été renommé, mais le skill renvoie à l'ancien nom. Le skill fait partie du code du projet : modifiez-le dans le même commit que la procédure.

Comment savoir qu'il est temps de sortir une section dans un skill

Il est utile de relire périodiquement le CLAUDE.md et de se demander, pour chaque section, dans quelle part des tâches habituelles elle sert réellement. Si elle sert presque toujours, elle est à sa place. Si elle ne sert que dans une tâche sur dix, c'est un candidat pour un skill.

Deuxième signal : la longueur. Une section qui ne tient pas sur un écran décrit presque toujours une procédure, et non une règle. Les procédures se lisent plus facilement en entier au moment de l'exécution, plutôt que d'être maintenues en arrière-plan pendant toute la session.

Troisième signal : les explications répétées. Si vous donnez encore et encore les mêmes précisions à l'agent pour la même tâche, notez-les une fois dans un skill. Une semaine plus tard, vérifiez si le nombre de corrections manuelles a diminué : c'est la preuve que le skill fonctionne.

En résumé

Les skills de Claude Code permettent de conserver les procédures à côté du projet sans payer leur coût en contexte à chaque session. La description du skill est toujours visible, le corps se charge au besoin, et les fichiers d'accompagnement encore plus tard. Le CLAUDE.md garde la carte du projet et les règles strictes, tandis que le déploiement, la revue, les publications et les autres tâches d'un type précis vont dans des skills. La structure des fichiers d'instructions et la divulgation progressive du contexte sont présentées en pratique dans le cours sur le harness engineering.