Vous est-il déjà arrivé de recoller le même bloc d'instructions dans le chat plusieurs fois ? C'est exactement ce que permettent d'éviter les skills. Vous décrivez la procédure dans un fichier, et l'agent va la chercher tout seul au moment où la tâche s'y prête.
C'est quoi une Skill ?
Une skill est un dossier contenant un fichier SKILL.md. Ce fichier commence par un en-tête en YAML avec le nom et la description. Ensuite, c'est du markdown classique avec vos instructions. Pour reprendre l'image qu'a utilisée Anthropic, construire une skill c'est comme préparer un guide pour une nouvelle recrue. On ne réexplique pas à quelqu'un comment faire une tâche, on lui explique comment nous faisons.
mon-skill/ ├── SKILL.md # Obligatoire : métadonnées + instructions ├── scripts/ # Optionnel : du code exécutable ├── references/ # Optionnel : de la documentation └── assets/ # Optionnel : templates, ressources
Vous avez certainement déjà utilisé ou entendu parler des instructions personnalisées, mais il s'agit d'un concept différent. Les instructions sont lues au démarrage de manière systématique, même quand vos demandes n'ont aucun rapport avec elles. Une skill n'est lue qu'au moment où elle devient pertinente.
Anthropic recommande de déplacer les instructions spécialisées de CLAUDE.md vers des skills.
Voici comment je répartis de manière générale :
-
Les instructions sont ce qui est vrai en permanence sur le projet, la stack et les conventions par exemple
-
Une skill est une procédure que l'IA ne sort que dans certains cas, comme générer un rapport dans un format précis, générer un
READMEselon votre style
À noter
Contrairement à une instruction, une skill est capable d'embarquer du code exécutable et d'être réutilisée telle quelle ailleurs.
Les skills sont-elles réservées à Claude ?
Anthropic a présenté les skills en octobre 2025 pour Claude. Puis, en décembre 2025, ils ont publié la spécification comme un standard ouvert hébergé sur agentskills.io. Une skill peut être lue par différents outils comme Claude, Cursor, OpenAI, Gemini ou encore Mistral Vibe. Vous avez accès à la liste via ce lien.
Comment ça marche les skills ?
On parlera ici de progressive disclosure : le mécanisme qui explique pourquoi on peut installer beaucoup de skills sans faire exploser sa fenêtre de contexte.
Le chargement se fait en trois temps :
-
Les métadonnées (nom et description), elles sont toujours chargées au démarrage, très peu coûteuses en tokens
-
Les instructions (le corps), elles ne sont chargées qu'au déclenchement de la skill
-
Les ressources (fichiers annexes), qui sont chargées à la demande
Au démarrage d'une session, l'agent ne connaît que le nom et la description de vos skills, et c'est quand une demande correspond à une description que la skill sera lue. Et si le fichier renvoie vers references/api.md par exemple, il ne lira ce fichier que si la tâche le demande.
À noter
Le cas des scripts est différent : quand l'agent exécute scripts/patrick.py, le code du script n'est pas chargé dans le contexte. Seule sa sortie est consommée. Vous pouvez donc embarquer un script de 500 lignes qui ne coûtera que les quelques lignes de son résultat.
Attention
Si vos instructions demandent à l'agent de lire le script pour en comprendre la logique, alors là son contenu entre bien en contexte. La documentation recommande d'ailleurs d'être explicite là-dessus dans le SKILL.md : « lance patrick.py » et « regarde patrick.py » ne produisent pas du tout le même coût.
Comment est structuré un fichier SKILL.md ?
Prenons un fichier minimal selon la spécification que vous retrouverez ici.
--- name: mon-skill description: Ce que fait ce skill, et quand l'utiliser. --- # Mon skill Vos instructions ici.
Le bloc entre les trois tirets s'appelle le frontmatter. On y place un petit bloc de métadonnées au format YAML. Il s'agit du premier niveau que l'agent a en permanence sous le coude. On retrouve plusieurs champs dans le frontmatter :
-
name: obligatoire, 64 caractères maximum, en minuscules et uniquement des lettres, chiffres et des tirets -
description: obligatoire, 1024 caractères maximum -
license: optionnel -
compatibility: optionnel, 500 caractères maximum -
metadata: optionnel, paires clés-valeurs -
allowed-tools: optionnel
Attention
name doit correspondre au nom du dossier parent.
La description est un vrai point critique. C'est ce que l'agent voit avant de décider s'il utilise la skill. La documentation vous donne d'ailleurs les bonnes pratiques :
-
Écrire à la troisième personne, car la description est injectée dans le prompt système, un changement de point de vue perturbe la détection
-
Dire ce que fait la skill et quand l'utiliser
Créer sa première Skill
On va construire une skill qui dresse le bilan d'activité d'un dépôt Git : qui commite, à quelle heure, et ce que ça raconte sur l'équipe.
Où placer la skill ?
Une skill n'est pas forcément globale, et l'emplacement du dossier détermine sa portée :
-
~/.claude/skills/est personnel et disponible dans tous les projets -
.claude/skills/à la racine d'un projet n'est valable que pour ce projet en particulier, et en plus la skill est versionnée avec le projet
Je vais partir sur une skill personnelle :
mkdir -p ~/.claude/skills/bilan-git/scripts
Nous aurons donc cette arborescence après la création des fichiers SKILL.md et historique.py :
~/.claude/skills/bilan-git/ ├── SKILL.md └── scripts/ └── historique.py
Le SKILL.md
Il se place à la racine du dossier bilan-git/, à côté de scripts/ :
--- name: bilan-git description: Analyse l'historique Git d'un dépôt et en tire un bilan d'équipe lisible. À utiliser quand l'utilisateur demande un bilan de son dépôt, qui a commité quoi, un récap de l'activité Git ou une analyse des habitudes de commit. --- # Bilan Git ## Étape 1 : agréger l'historique Exécuter le script sur le dépôt concerné : python3 scripts/historique.py <chemin_du_depot> Il affiche le nombre de commits par auteur et leur répartition sur la journée. ## Étape 2 : rédiger le bilan À partir de ces chiffres, écrire un bilan de dix lignes maximum, sur un ton léger mais sans flatterie. Couvrir systématiquement ces trois points : - **Le rythme** : les commits sont-ils concentrés sur une plage horaire inhabituelle ? Le signaler sans en faire un jugement de valeur - **La répartition** : si un seul auteur dépasse la moitié des commits, le dire clairement, c'est un risque si cette personne quitte le projet - **Une action concrète** : terminer par une seule suggestion actionnable Ne jamais inventer de chiffre absent de la sortie du script.
Le script
Dans le dossier scripts, créons un fichier historique.py :
"""Agrège l'historique Git d'un dépôt : qui commite, et à quelle heure.""" import subprocess import sys from collections import Counter def lire_historique(depot: str) -> list[str]: """Retourne une ligne "auteur|heure" par commit du dépôt.""" resultat = subprocess.run( ["git", "-C", depot, "log", "--pretty=format:%an|%ad", "--date=format:%H"], capture_output=True, text=True, check=False, ) if resultat.returncode != 0: print(f"Lecture impossible : {resultat.stderr.strip()}") sys.exit(1) return resultat.stdout.splitlines() def main() -> None: auteurs, heures = Counter(), Counter() lignes = lire_historique(sys.argv[1] if len(sys.argv) > 1 else ".") for ligne in lignes: # rsplit car un nom d'auteur peut lui-même contenir le séparateur auteur, heure = ligne.rsplit("|", 1) auteurs[auteur] += 1 heures[int(heure)] += 1 print(f"{len(lignes)} commits analysés\n") print("Commits par auteur :") for auteur, total in auteurs.most_common(): print(f" {auteur} : {total}") print("\nRépartition sur la journée :") for heure in sorted(heures): print(f" {heure:02d}h {'█' * heures[heure]} ({heures[heure]})") if __name__ == "__main__": main()
Ici on utilise uniquement la bibliothèque standard : subprocess pour appeler Git et collections pour compter. D'ailleurs, n'hésitez pas à aller lire notre article sur le module collections.
Attention
Un script de skill doit résoudre ses cas d'erreur, pas les renvoyer à l'agent.
Utilisation de la skill
Je viens de lancer le prompt fais-moi un bilan de l'activité sur ce dépôt sur un projet. Regardez le résultat :
Claude va bien charger la skill
Le rapport de Claude
J'ai une analyse, des statistiques, et même un petit conseil pour uniformiser mes deux identités !
Vous pouvez aussi appeler explicitement une skill avec /nom-de-la-skill :
Appel explicite
Pourquoi embarquer un script si Claude sait en écrire un ?
On est tous d'accord pour dire que Claude serait capable de nous faire un rapport sans script embarqué. Mais comme seule la sortie est consommée, un script embarqué est nettement plus économique que de laisser Claude générer le code équivalent à chaque fois. De plus, un script généré à la volée est différent à chaque session : même dépôt, même question, sortie potentiellement différente.
Valider sa skill
Il existe une bibliothèque de référence, fournie par le standard, qui vérifie que votre frontmatter est juste :
pip install skills-ref
La commande installée s'appelle agentskills :
agentskills validate ~/.claude/skills/bilan-git
Faire générer ses skills par Claude
Anthropic a créé une skill qui permet de faire générer ses skills : skill-creator. Il faut installer le paquet example-skills du dépôt officiel :
/plugin marketplace add anthropics/skills /plugin install example-skills@anthropic-agent-skills
Et regardez, j'ai demandé à Claude s'il était capable de me générer une skill :
skill-creator
Télécharger des skills
Il est très courant de télécharger des skills existantes.
Vous pouvez le faire directement sur l'application Claude, depuis Paramètres > Compétences et parcourir les skills disponibles ou ajouter les vôtres. La skill est ensuite stockée sur votre compte Claude, ce qui est différent de Claude Code où la skill est un dossier sur votre disque.
Skills depuis l'application Claude
N'hésitez pas aussi à aller jeter un œil sur le dépôt skills d'Anthropic, vous y trouverez des skills écrites par des gens dont c'est le métier ! On clone une skill comme n'importe quel projet.
Dans Claude Code, ce dépôt s'installe aussi via la marketplace de plugins avec les deux commandes vues plus haut.
Il faut savoir qu'il existe tout un écosystème tiers de skills. Prenez par exemple DuckDB (domaine de la data), l'équipe maintient duckdb-skills qui permet à un agent d'explorer vos données avec le moteur maison.
Attention
Une skill embarque du code que l'agent exécutera, faites attention à ce que vous ajoutez comme skills.
