Skills Claude Code : écrire un SKILL.md que Claude charge au bon moment

Une procédure qu’on recolle dans le chat à chaque fois a sa place dans une skill. Encore faut-il que Claude la trouve quand il en a besoin, sans qu’elle pèse sur les sessions où elle ne sert à rien.

Une skill est un dossier qui contient un fichier SKILL.md : un en-tête YAML, puis des instructions en Markdown. Claude l’utilise quand elle est pertinente, ou on l’appelle par /nom-de-la-skill.

Où la ranger

• ~/.claude/skills/<nom>/SKILL.md : skill personnelle, disponible dans tous vos projets ;
• .claude/skills/<nom>/SKILL.md : skill de projet, versionnée avec le dépôt ;
• <plugin>/skills/<nom>/SKILL.md : livrée par un plugin (voir ce billet).

À nom égal, la skill personnelle l’emporte sur celle du projet.

L’en-tête

---
name: compte-rendu-incident
description: Rédige le compte rendu d'un incident d'exploitation à partir des notes et des logs fournis. À utiliser quand l'utilisateur parle de post-mortem, de retex ou de compte rendu d'incident.
---

# Compte rendu d'incident

1. Reconstituer la chronologie, heures en UTC.
2. Séparer cause racine et facteurs aggravants.
3. Lister les actions par rôle, sans nom de personne.

Gabarit complet : [modele.md](modele.md)

Dans Claude Code, tous les champs sont facultatifs : name reprend le nom du dossier et, sans description, c’est la première ligne non vide du corps qui sert. La doc ne recommande que description, car c’est elle que Claude lit pour décider d’appliquer la skill. Le guide de bonnes pratiques commun aux produits Claude limite name à 64 caractères : minuscules, chiffres et tirets.

Comment Claude décide de la charger

En session, seules les descriptions sont en contexte (effet sur la consommation : ce billet). Le corps n’entre qu’à l’invocation, en un seul message, et y reste les tours suivants. Claude Code ne relit pas le fichier : une consigne valable pour toute la tâche s’écrit comme une règle permanente (« lancer les tests après chaque modification ») plutôt que comme une étape.

Deux limites touchent le déclenchement :

• when_to_use, champ facultatif, complète description avec des phrases de déclenchement ou des exemples de demandes. Les deux sont tronqués ensemble à 1 536 caractères dans la liste : le cas d’usage principal va en tête.
• La liste a un budget de 1 % de la fenêtre de contexte du modèle. Quand il déborde, Claude Code retire d’abord les descriptions des skills les moins invoquées : le nom reste, les mots-clés disparaissent.

Deux champs règlent qui déclenche :

disable-model-invocation: true   # appel par /nom uniquement, description retirée du contexte
user-invocable: false            # absente du menu /, seul Claude l'invoque

La doc conseille le premier pour les flux à effet de bord, comme un déploiement ou un commit.

Des fichiers annexes plutôt qu’un gros SKILL.md

Repère de la doc : moins de 500 lignes pour SKILL.md, le détail dans des fichiers voisins cités avec leur contenu, pour que Claude sache quand les ouvrir.

compte-rendu-incident/
├── SKILL.md        # vue d'ensemble, lue à l'invocation
├── modele.md       # lu seulement si la tâche le demande
└── scripts/
    └── chrono.py   # exécuté, pas chargé

Selon le guide, un fichier non lu ne consomme aucun jeton et un script exécuté ne coûte que sa sortie. Il recommande des références à un seul niveau depuis SKILL.md : un fichier pointé par un autre fichier risque d’être lu partiellement. Dans SKILL.md, ${CLAUDE_SKILL_DIR} est remplacé par le dossier de la skill : c’est par lui qu’on appelle ses scripts, quel que soit le répertoire courant.

Bonnes pratiques

• Une description qui ressemble aux vraies demandes. Le guide la veut à la troisième personne : ce que fait la skill, quand l’utiliser.
• Un corps court. Il reste en contexte les tours suivants. Après une compaction, Claude Code ne rattache que les 5 000 premiers jetons de chaque skill ; au-delà de 25 000 jetons au total, les plus anciennes sautent. L’essentiel va en haut, et réinvoquer la skill la recharge.
• Le process, pas l’état. Le guide demande d’éviter l’information datée qui deviendra fausse. Une skill dit comment faire ; une date ou un statut se rangent ailleurs.
• Une règle impérative n’est pas une skill. Si Claude saute une consigne obligatoire, la doc renvoie vers un hook, exécuté à chaque événement (voir ce billet).

Skill qui ne se déclenche pas : vérifier qu’elle apparaît en demandant What skills are available?. Un YAML mal formé charge le corps sans métadonnées : /nom marche, mais Claude ne peut plus s’appuyer sur la description ; --debug affiche l’erreur de parsing.

Ce qu’il faut retenir

• Une skill, c’est un dossier et un SKILL.md : .claude/skills/ pour le projet, ~/.claude/skills/ pour soi.
• Seule la description vit en permanence dans le contexte : elle décide du déclenchement.
• disable-model-invocation: true pour tout ce qui a un effet de bord.
• SKILL.md sous 500 lignes, le détail dans des annexes lues à la demande, à un seul niveau.
• Le process dans la skill, l’état ailleurs, les règles impératives dans un hook.

In English

A skill is a folder and a SKILL.md. Where to store it, what to put in name and description, how Claude decides to load it and how to keep the body short. Only skill descriptions stay in context, the body enters only on invocation, and disable-model-invocation: true reserves a skill for manual calls, which the docs advise for actions with side effects.

Sources & vérification

Relevé sur : Documentation Claude Code, relevé 2026-10

• Claude Code, Skills code.claude.com
• Claude Platform, Skill authoring best practices platform.claude.com

Comment les billets sont vérifiés et corrigés