Qu'est-ce qu'une skill ?#

Une skill est un dossier d'instructions que l'agent lit seulement quand ta demande le justifie : tu peux en avoir cinquante sans alourdir ton contexte.

Temps de lecture : 10 min | Niveau : Debutant

Ce que tu sauras faire apres#

• Definir une skill et citer son unique fichier obligatoire.
• Expliquer la divulgation progressive et ses trois niveaux.
• Calculer pourquoi une skill coute moins cher qu'un CLAUDE.md geant.
• Ranger une skill au bon endroit selon sa portee (toi, le projet, l'equipe).
• Lister tes skills disponibles et en recharger une apres modification.

1. La definition, en une phrase#

Une skill est un dossier. Dedans, il y a au minimum un fichier SKILL.md. Ce fichier contient deux choses :

1. Un en-tete YAML (le frontmatter) avec un nom et une description.
2. Des instructions en Markdown que l'agent suit quand la skill est active.

C'est tout. Le reste (fichiers de reference, scripts) est optionnel.

ma-skill/
├── SKILL.md          # obligatoire : metadonnees + instructions
├── reference.md      # optionnel : le detail
├── examples.md       # optionnel : des exemples
└── scripts/          # optionnel : du code executable
    └── verifier.py

Deux mots de vocabulaire, expliques une fois :

• frontmatter : le bloc entre deux lignes --- tout en haut d'un fichier Markdown. Il contient des metadonnees, pas du texte a lire.
• token : l'unite de decoupage du texte pour un modele. Plus tu charges de texte, plus tu consommes de tokens, et plus la fenetre de contexte se remplit.

2. 🔍 La divulgation progressive (progressive disclosure)#

C'est le mecanisme a comprendre. Sans lui, les skills ne seraient qu'un dossier de notes.

L'idee : l'agent ne charge pas tout, tout de suite. Il charge par etages, au fur et a mesure du besoin. La doc Anthropic compare ca a un manuel bien range : d'abord le sommaire, puis le chapitre utile, puis l'annexe si vraiment necessaire.

Les trois niveaux#

Le deroule concret#

Prenons une skill pdf-processing (exemple de la doc officielle).

1. Demarrage : le prompt systeme contient seulement sa ligne de description.
2. Ta demande : « Extrais le texte de ce PDF et resume-le. »
3. Declenchement : l'agent reconnait la description, et lit SKILL.md avec un cat. Les instructions entrent dans le contexte.
4. Tri : le remplissage de formulaire n'est pas demande, donc FORMS.md n'est pas lu. Il coute zero token.
5. Execution : l'agent applique les instructions.

Pourquoi c'est econome, chiffres a l'appui#

Imagine 20 skills installees, chacune avec 300 lignes de reference.

• Sans divulgation progressive (tout dans CLAUDE.md) : les 20 x 300 lignes sont chargees a chaque conversation. Ton contexte est plein avant meme ta premiere question.
• Avec skills : 20 x environ 100 tokens = environ 2 000 tokens au demarrage. Puis une seule skill se charge quand tu en as besoin.

La consequence pratique. Tu peux bundler une documentation d'API complete, un dictionnaire de donnees de 500 lignes, une liste de tous tes modeles dbt. La doc officielle est explicite : il n'y a pas de limite pratique au contenu bundle, parce que ce qui n'est pas lu ne coute rien.

Le cas special des scripts#

Un script, l'agent ne le lit pas : il l'execute. Seule la sortie entre dans le contexte.

Un script Python de 200 lignes qui valide un fichier coute donc, en contexte, le prix de sa sortie : Validation OK ou Erreur ligne 42 : colonne manquante. L'economie est enorme. Et un script pre-ecrit est deterministe, donc plus fiable que du code regenere a chaque fois.

3. 📁 Ou se rangent les skills#

Dans Claude Code, une skill est decouverte depuis plusieurs emplacements. Voici le tableau officiel, traduit.

Comment choisir, pour un data engineer#

• Personnel (~/.claude/skills/) : tes habitudes a toi. Ton style de docstring Python, ta facon de formater un rapport d'analyse. Personne d'autre n'en a besoin.
• Projet (.claude/skills/) : les conventions de ce depot. Le schema de l'entrepot, les regles de nommage dbt, la liste des tables a ne jamais toucher. Ca se commit dans Git, donc toute l'equipe en profite.
• Plugin : quand tu veux distribuer un ensemble coherent (plusieurs skills + des agents + des hooks) a d'autres equipes. Voir la section 08.

Regle que j'applique. Si un nouveau collegue devrait le savoir pour travailler sur ce depot, la skill va dans .claude/skills/ et elle est commitee. Si c'est un gout personnel, elle reste dans ~/.claude/skills/.

4. Les commandes utiles#

Les quatre etats proposes par /skills : on (visible par toi et par l'agent), name-only (l'agent ne voit que le nom), user-invocable-only (seul toi peux l'invoquer) et off (masquee des deux cotes).

Quand faut-il vraiment /reload-skills ?#

C'est la question qui fait perdre le plus de temps. La reponse officielle est precise.

• Cas normal, rien a faire. Claude Code surveille ~/.claude/skills/, le .claude/skills/ du projet et celui d'un dossier ajoute avec --add-dir. Si tu ajoutes, modifies ou supprimes une skill dans un de ces dossiers, le changement est pris en compte dans la session en cours, sans redemarrer.
• Cas du dossier tout neuf. Si le dossier de skills de premier niveau (.claude/skills/ par exemple) n'existait pas au demarrage de la session, Claude Code ne le surveille pas encore. La, tu tapes /reload-skills — et tu le retapes apres chaque modification suivante dans ce dossier, tant que tu n'as pas relance la session.
• Limite a connaitre. Cette detection automatique ne couvre que le texte du SKILL.md. Pour un dossier de skill qui fait aussi partie d'un plugin, les changements dans hooks/, .mcp.json, agents/ et output-styles/ demandent /reload-plugins.

En pratique. Cree le dossier .claude/skills/ avant de lancer claude. Tu n'auras plus jamais a y penser.

5. ⚠️ Securite : une skill est du code#

La doc est directe : n'utilise que des skills de sources fiables, celles que tu as ecrites ou qui viennent d'Anthropic.

Une skill donne a l'agent des instructions et du code. Une skill malveillante peut donc lui faire appeler des outils ou executer du code qui n'a rien a voir avec son objectif affiche.

Les points de vigilance listes officiellement :

• Audite tout : le SKILL.md, mais aussi les scripts, les images, les autres ressources. Cherche les appels reseau inattendus ou les acces fichiers qui ne collent pas.
• Mefie-toi des sources externes : une skill qui va chercher des donnees sur une URL peut ramener des instructions malveillantes, et sa dependance peut changer dans le temps.
• Traite ca comme une installation de logiciel, surtout en production ou sur des donnees sensibles.

L'environnement d'execution n'est pas le meme partout, et ca change le niveau de risque :

Autrement dit : une skill que tu installes dans Claude Code peut faire, sur ta machine, tout ce que tu peux faire toi-meme. C'est la surface ou il faut etre le plus regardant.

6. Template : decider si un savoir-faire merite une skill#

Copie-colle ce prompt quand tu hesites.

Je travaille sur [TYPE_DE_PROJET : pipeline dbt / API Python / dashboard].
Voici une tache que je refais souvent : [DECRIS_LA_TACHE_EN_3_LIGNES].
A chaque fois, je dois reexpliquer ces regles : [LISTE_LES_REGLES_QUE_TU_REPETES].
Cette tache revient environ [FREQUENCE : 2 fois par semaine].

Dis-moi :
1. Est-ce que ca justifie une skill, ou un simple ajout au CLAUDE.md ?
2. Si c'est une skill : quel nom, et quelle description pour qu'elle se declenche au bon moment ?
3. Qu'est-ce qui doit rester dans le SKILL.md, et qu'est-ce qui doit partir dans un fichier de reference ?
Reponds en francais, de facon directe.

A retenir#

• Une skill est un dossier ; son seul fichier obligatoire est SKILL.md.
• La divulgation progressive charge en 3 niveaux : metadonnees toujours, instructions au declenchement, ressources a la demande.
• Une skill non utilisee coute environ 100 tokens. Tu peux donc en avoir beaucoup.
• Un script bundle est execute, pas lu : seule sa sortie coute des tokens.
• ~/.claude/skills/ pour toi, .claude/skills/ pour l'equipe (commite dans Git).
• Claude Code detecte tout seul les changements dans un dossier de skills qu'il surveille deja. /reload-skills sert uniquement si le dossier n'existait pas au demarrage de la session.
• Une skill execute du code avec tes droits : n'installe que ce que tu as audite. Dans Claude Code, l'acces reseau est complet.

Sources#

• Agent Skills - Overview
• Agent Skills in Claude Code
• Skill authoring best practices
• Equipping agents for the real world with Agent Skills
• agentskills.io
• anthropics/skills - les 19 skills officielles a ouvrir pour voir la structure en dossier (skills/, un dossier par skill)
• obra/superpowers - divulgation progressive en vrai : skills/writing-skills/ garde ses guides annexes a cote du SKILL.md