Claude Code Skills, expliquées depuis zéro

Tu l'as déjà vécu. Troisième conversation de la semaine, et tu réexpliques à Claude comment on déploie chez toi, comment tu veux tes messages de commit, où sont rangés les fichiers. Chaque conversation neuve repart de zéro : ce que tu as dit hier n'existe plus.

Il y a deux réflexes, et les deux sont mauvais. Le premier : recoller le même pavé au début de chaque session. C'est pénible, et tu oublies toujours un morceau. Le second : tout mettre dans CLAUDE.md, le fichier que Claude lit à chaque démarrage. Ça marche un temps, puis le fichier grossit, et Claude paye à chaque session pour des procédures qui ne servent qu'une fois par mois.

Une skill, c'est la troisième voie : un mode opératoire écrit dans un fichier, que Claude charge uniquement quand ta demande correspond. La doc officielle le dit en une phrase : crée une skill quand tu colles la même checklist pour la troisième fois, ou quand une section de ton CLAUDE.md est devenue une procédure plutôt qu'un fait.

L'image qui aide : un classeur de fiches de procédure. L'index du classeur est toujours sous les yeux de Claude. La fiche, il l'ouvre quand le travail le demande, et il la referme après.

Une skill, c'est un dossier qui porte le nom de la skill, avec un fichier SKILL.md dedans (en majuscules, exactement comme ça). Le fichier a deux parties :

• L'en-tête, entre deux lignes ---. On l'appelle le frontmatter. C'est du YAML, c'est-à-dire des lignes clé: valeur. Deux clés comptent : name (le nom) et description (ce qu'elle fait et quand l'utiliser). La première ligne du fichier doit être le premier ---, sinon Claude lit tout comme du texte. Une description longue s'écrit sur plusieurs lignes avec description: > puis les lignes indentées, comme dans l'exemple.
• Le corps, en Markdown, du texte normal avec des titres et des listes. C'est la procédure que Claude va suivre.

Le nom du dossier devient une commande : une skill dans deploiement/ se lance en tapant /deploiement.

Où la ranger. Deux endroits, et le choix est simple :

Pas besoin de redémarrer. Claude Code surveille ces dossiers : la skill est disponible dès que tu enregistres le fichier, même en pleine session. Pour vérifier, tape / et cherche son nom dans le menu, ou demande-lui « quelles skills sont disponibles ? ».

C'est le point à comprendre avant d'écrire, parce qu'il explique toutes les règles qui suivent. Une skill se charge en trois étages, et à chaque étage, ce qui entre dans le contexte de Claude n'a pas la même taille :

Et il y a deux façons de déclencher l'étage 2. Toi, en tapant /nom-de-la-skill. Ou Claude tout seul, quand ce que tu lui demandes ressemble à la description. Dans les deux cas, c'est la même skill qui se charge.

Pourquoi ça change tout : le contexte de Claude est limité, et plus il est chargé, moins Claude est bon (c'est la section 1 du kit). Grâce à ce chargement par étages, tu peux avoir cinquante skills installées : tant qu'elles ne servent pas, elles coûtent cinquante lignes d'index et rien d'autre. En revanche, une fois la fiche chargée, chaque ligne du corps est relue à chaque tour jusqu'à la fin de la session. C'est pour ça que le corps doit rester court, et que le détail vit dans les annexes.

Trois outils pour donner du contexte à Claude, et ils ne se remplacent pas :

Le test : « est-ce vrai à chaque session ? » Oui, c'est un fait, il va dans CLAUDE.md. Non, c'est une procédure qu'on lance de temps en temps, c'est une skill. Et si ton CLAUDE.md dépasse les deux cents lignes, il y a presque à coup sûr deux ou trois skills qui dorment dedans.

Deux mots sur le reste. Les anciennes « custom commands » (.claude/commands/) sont devenues des skills sans dossier : elles marchent encore, mais tout ce qui est nouveau s'écrit en skill. Et les sous-agents (un Claude à part, avec son propre contexte, qui te rend une conclusion) ne sont pas des concurrents : une skill peut très bien dire « délègue cette recherche à un sous-agent ». On y revient à la section 8.

Rappelle-toi l'étage 1 : au moment de décider, Claude n'a que l'index sous les yeux, donc la description. Il la compare à ta demande, parmi parfois des dizaines d'autres. Si elle dit « aide avec les documents », elle ne gagnera jamais.

La formule qui marche tient en deux parties :

1. Ce qu'elle fait, à la troisième personne. « Déploie le site », pas « je peux t'aider à déployer » ni « tu peux l'utiliser pour ». Le texte est injecté tel quel dans les instructions de Claude ; un « je » ou un « tu » brouille la lecture.
2. Quand l'utiliser, avec les mots que tu emploies vraiment. Pas les mots élégants : ceux que tu tapes. Si tu dis « déploie », « mets en prod », « balance en ligne », les trois vont dans la description. Les noms de fichiers et d'extensions aussi (.csv, « le tableau des stats »).

Deux règles de plus. Si tu as deux skills voisines, trace la frontière dans la description (« pour auditer un autre compte, voir tiktok-audit ») : sinon elles se battent pour la même demande. Et mets l'essentiel en premier : quand tu as beaucoup de skills, Claude Code raccourcit les descriptions trop longues, en partant de la fin.

Le test, avant de passer au corps : dans une session neuve, formule une demande comme tu la formulerais, sans nommer la skill. Elle doit se déclencher. Puis une demande voisine, qui ne doit pas la déclencher. Ajuste la description jusqu'à ce que les deux soient justes.

Le corps, c'est la fiche de procédure. Sept principes, tirés du guide d'écriture officiel, dans l'ordre d'importance :

1. Court, parce que Claude sait déjà. Il sait ce qu'est git, un fichier JSON, une base de données. N'écris que ce qu'il n'a pas : tes chemins, tes conventions, ton ordre, les pièges que tu as rencontrés. Pour chaque paragraphe, la question : « est-ce que Claude le sait déjà ? » Si oui, supprime.
2. Un défaut, pas un menu. « Utilise ffmpeg » vaut mieux que « tu peux utiliser ffmpeg, ou HandBrake, ou… ». Un choix par défaut, plus l'exception justifiée (« pour les fichiers de plus de 2 Go, passe par le script »).
3. Le bon degré de liberté. Une opération fragile (déployer, migrer une base) veut des étapes exactes, la commande exacte, et « ne change rien à cette commande ». Une tâche ouverte (relire un texte, revoir du code) veut des principes, et Claude choisit le chemin. L'image de la doc : un pont étroit au-dessus du vide demande des garde-fous ; un champ ouvert demande une direction.
4. Des étapes numérotées, et une vérification à la fin. Le pattern qui améliore le plus la qualité : produire, vérifier, corriger, recommencer jusqu'à ce que la vérification passe. Pour un long process, une checklist que Claude recopie et coche.
5. Des exemples quand la forme compte. Pour un message de commit ou un format de rapport, deux ou trois exemples entrée → sortie valent mieux que n'importe quelle description.
6. Un mot pour une chose. Toujours « le relevé », jamais « le relevé » puis « le rapport » puis « les chiffres ». Claude suit mieux un vocabulaire stable.
7. Pas de date. « Avant août, faire X » pourrit. Si une ancienne façon de faire existe, une section « ancien fonctionnement » avec sa date de fin.

Voilà à quoi ressemble un SKILL.md bien organisé. Les commentaires t'expliquent chaque bloc ; retire-les quand tu écris le tien.

Une skill débutante, c'est un fichier. Une skill qui a servi trente fois, c'est un dossier avec trois sous-dossiers. Chacun a un rôle précis, lié aux trois étages de chargement :

Quatre règles pour que ça tienne :

• Le SKILL.md reste sous 500 lignes. C'est la limite de la doc officielle. Au-delà, découpe.
• Chaque annexe est pointée depuis le SKILL.md, avec une ligne qui dit quand la lire : « les flags de tous les scripts sont dans references/api.md, à lire une fois au premier besoin ».
• Un seul niveau. SKILL.md → fichier, jamais fichier → autre fichier : Claude ne suit pas les chaînes, il survole. Une référence de plus de cent lignes commence par un sommaire.
• Un script gère ses erreurs lui-même. Un message clair (« fichier introuvable, voici ceux qui existent ») plutôt que planter en laissant Claude deviner. Et dis dans le SKILL.md ce qu'il doit faire : « lance scripts/releve.py » (exécuter), ou « lis scripts/releve.py » (comprendre la logique). Ce n'est pas la même chose.

Voilà à quoi ressemble une skill mûre, après un mois d'usage. Ici, une chaîne de montage vidéo : tout ce qui se calcule est en script, tout ce qui se consulte est en référence, et le SKILL.md ne garde que l'ordre des opérations. (La mienne a dépassé les mille lignes avant d'être découpée comme ça ; c'est le geste 4 de la partie 3.)

À l'autre bout, une skill de relevé de stats tient en cent lignes, avec un seul script et une règle qui résume tout le principe : « le script sort les chiffres ; ne jamais recalculer à la main ». Les pièges de calcul vivent dans le code, pas dans la prose. Claude ne peut pas les oublier.

Tout ce qui suit est optionnel. Le jour où tu en as besoin, tu sauras que ça existe :

La plus utile pour commencer, c'est !`commande`. Voilà la première skill de la doc officielle, traduite : elle résume tes modifications non commitées, et elle est utile dès le premier jour.

Il existe plus de cent mille skills à installer. Une skill installée, c'est la connaissance de quelqu'un d'autre, figée : elle n'apprend rien de toi. C'est exactement ce que tu veux là où tu ne sais pas. Tu n'y connais rien en SEO, en Postgres, en accessibilité ? Installe la skill d'un spécialiste : ton premier audit sera meilleur que ce que tu aurais fait seul, et tu apprendras en la lisant. Souvent, la skill suivante, c'est toi qui l'écris, avec ce qui manquait à la première.

Là où c'est ton métier, n'installe rien. Une skill que tu écris, tu la corriges à chaque fois qu'elle se plante, et au bout d'un mois c'est elle qui sait comment tu bosses. Sur les cent mille du catalogue, il n'y en a pas une qui sait ça. Et méfie-toi des skills « de goût » (design, style d'écriture) : elles promettent beaucoup, et la différence à l'arrivée est souvent invisible.

Avant d'installer une skill trouvée sur internet, ouvre son SKILL.md et regarde son champ allowed-tools : une skill peut s'autoriser toute seule des commandes que tu n'aurais pas validées.

Et même là, tu finis par écrire. Une skill installée donne le goût générique : ce qu'un bon design engineer ferait sur n'importe quel site. Tout ce qui est propre au tien — un visuel par section, un tableau comparatif, ta charte, tes interdits de copy — n'est dans aucune des cent mille. Ça, c'est une skill à toi, dans le .claude/skills/ du projet, ou une règle dans son CLAUDE.md. Installé, c'est le socle. Écrit, c'est ce qui fait que c'est ton site.

Tout ce que tu as lu en partie 2, Claude le connaît nativement : il sait ce qu'est un frontmatter, une bonne description, un dossier scripts/. La doc officielle le dit noir sur blanc, tu n'as pas besoin d'un outil spécial pour lui faire écrire une skill. Ton travail, c'est de lui donner la matière, et de corriger le fichier quand il se plante. Quatre gestes, dans l'ordre où ils arrivent.

Geste 1 · Fais d'abord, puis « fais-en une skill ». Ouvre une conversation neuve. Fais le process en entier, à la main, comme tu veux : tu demandes, tu corriges, tu valides. Ce que tu expliques en route, c'est justement ce que Claude n'avait pas. Quand le résultat est bon, une phrase :

Geste 2 · Itère à l'usage : « fixe la skill ». Les fois suivantes, tu utilises la skill. Elle se plantera : une étape manque, un cas n'était pas prévu, Claude a improvisé. Ne corrige pas dans la conversation, ça meurt quand tu fermes l'onglet. Dis-lui de corriger le fichier.

Fixe la skill : ce qui vient de rater, mets-le dans le SKILL.md pour que ça ne se reproduise pas. Ne change rien d'autre.

Geste 3 · Le code répété va dans scripts/. Regarde ce que Claude fait quand la skill tourne. S'il crée un fichier ou réécrit un bout de code à chaque fois, c'est du temps et des erreurs : dis-lui de le mettre dans un script, dans le dossier de la skill, et de l'appeler. Il oubliera parfois. Rappelle-le-lui, et fais-le noter dans la skill.

Ce code, tu le réécris à chaque fois. Mets-le dans un script dans le dossier de la skill (scripts/), avec ses erreurs gérées dedans, et fais en sorte que la skill l'appelle au lieu de le réécrire. Ajoute une ligne dans le SKILL.md qui dit de passer par le script.

Geste 4 · Le détail va dans references/. Au bout de quelques semaines, le fichier grossit. Le SKILL.md garde la procédure et les règles qui servent à chaque fois ; le détail (les règles fines, les cas particuliers, ce qu'on a appris) part dans des fichiers de référence que la skill pointe, avec une ligne qui dit quand les lire.

Le SKILL.md est trop long. Garde dedans uniquement la procédure et les règles qui servent à chaque fois. Sors le détail dans references/ (un fichier par sujet, un sommaire en tête s'il dépasse cent lignes) et pointe chaque fichier depuis le SKILL.md avec une ligne qui dit quand le lire. Un seul niveau : jamais de référence qui renvoie à une autre référence.

Et c'est tout. Une skill mûre, c'est trois dossiers et deux phrases : « fais-en une skill » et « fixe la skill ».

1. Elle existe ? Tape / et cherche son nom, ou demande « quelles skills sont disponibles ? ». Si elle n'y est pas, c'est presque toujours l'en-tête : un deux-points en trop, une description sur plusieurs lignes sans guillemets, le premier --- qui n'est pas en première ligne. Le piège vicieux : avec un en-tête cassé, /nom marche encore, mais Claude n'a plus de description, donc il ne la déclenchera jamais tout seul. La commande ci-dessous te dit quels fichiers ont un en-tête invalide.
2. Elle se déclenche au bon moment ? Session neuve (/clear), une demande formulée avec tes mots, sans nommer la skill. Puis une demande voisine qui ne doit pas la déclencher. Le résultat te dit quoi corriger dans la description.
3. Elle fait le bon travail ? Même tâche, session neuve, avec et sans la skill, et tu compares. La session neuve compte : si tu testes dans la conversation où tu viens d'écrire la skill, tout ce que tu as expliqué en route masque les trous du fichier. Ce qui rate, c'est un « fixe la skill ».

Et si elle se déclenche trop souvent : description plus précise, ou disable-model-invocation: true pour la garder manuelle.