Qu’est-ce qu’un skill et comment écrire SKILL.md ?

Qu’est-ce qu’un skill, et en quoi diffère-t-il d’un fichier de règles ?

Selon la définition du standard ouvert, un skill est un dossier qui contient un fichier SKILL.md. Le fichier commence par au moins un nom (name) et une description (description), suivis d’instructions qui expliquent à l’agent comment faire une tâche. Le dossier peut aussi contenir des scripts, des documents de référence et des modèles.

Le format a été conçu par Anthropic. Claude Code a pris en charge les skills le 16 octobre 2025, avec la version 2.0.20 ; Anthropic a publié le format comme standard ouvert le 18 décembre 2025. Au 18 octobre 2026, les pages sur les skills de Claude Code, Codex, Cursor, Gemini CLI et Copilot indiquent qu’elles reposent sur ce standard. La liste du standard lui-même compte 46 produits ; le site du standard précise que cette liste ne montre qu’une partie des produits qui le prennent en charge. Le 18 juin 2026, Google a remplacé Gemini CLI par Antigravity CLI pour les utilisateurs gratuits et les abonnés Google AI Pro et Ultra ; Gemini CLI reste disponible avec une licence d’entreprise ou une clé d’API payante. Antigravity lit aussi les skills et cherche les skills du projet dans .agents/skills.

Ce qui le distingue d’un fichier de règles (AGENTS.md, CLAUDE.md, GEMINI.md), c’est le moment où il est lu. Un fichier de règles est lu en entier à chaque session. Les instructions d’un skill, elles, ne sont chargées que lorsqu’une tâche y correspond. Les outils le disent avec leurs propres mots :

• Claude Code : contrairement à CLAUDE.md, le corps d’un skill n’est chargé que lorsque le skill est utilisé. Un long texte de référence ne prend donc presque pas de place tant qu’on n’en a pas besoin.
• Gemini CLI : les fichiers de contexte comme GEMINI.md donnent à l’espace de travail un arrière-plan permanent ; un skill est une expertise qu’on ouvre à la demande.
• Codex : AGENTS.md façonne le comportement de l’agent, les skills regroupent des processus qui se répètent.
• Copilot : les instructions simples qui valent pour presque toutes les tâches vont dans les custom instructions ; les instructions détaillées, à lire seulement quand elles servent, vont dans un skill.

Les anciens formats passent eux aussi aux skills. Dans Claude Code, les commandes sous .claude/commands/ ont été fusionnées avec les skills. Codex a déclaré obsolètes les custom prompts et recommande les skills à la place. Cursor fournit un skill /migrate-to-skills qui convertit les règles et les commandes slash en skills.

Nous avons présenté les fichiers de règles dans notre article sur AGENTS.md et CLAUDE.md, les commandes qui s’exécutent à chaque fois dans notre article sur les hooks, et les assistants qui travaillent dans un contexte séparé dans notre article sur les sous-agents. Cet article porte sur la couche intermédiaire : les instructions que l’agent n’ouvre qu’au besoin.

Quand l’agent lit-il un skill ?

Le standard appelle cela la divulgation progressive (progressive disclosure). L’agent ne lit pas un skill d’un seul coup ; il le lit par morceaux, au fil de ce que la tâche demande :

La première étape se paie à chaque session, même si le skill n’est jamais utilisé. C’est pourquoi le nombre de skills que vous installez compte. Deux outils disent quelle place cette liste reçoit :

• Claude Code réserve à la liste 1 % de la fenêtre de contexte du modèle. Si la liste ne tient pas, il retire les descriptions des skills que vous utilisez le moins. Chaque description est en outre coupée à 1 536 caractères dans la liste.
• Codex réserve à la liste au plus 2 % de la fenêtre de contexte, ou 8 000 caractères s’il ne connaît pas la fenêtre. Avec skills.max_context_tokens, vous pouvez porter cette part à 10 000 tokens au plus. Si beaucoup de skills sont installés, Codex raccourcit d’abord les descriptions.
• Cursor, Gemini CLI et Copilot : non précisé dans la documentation.

Une fois ouvert, un skill prend aussi de la place. Dans Claude Code, le contenu d’un skill appelé entre dans la conversation sous la forme d’un seul message et y reste aux tours suivants. Quand la conversation est compactée, seuls les 5 000 premiers tokens de chaque skill sont rajoutés. Écrivez donc l’instruction la plus importante en haut du fichier.

Où placer les skills dans les cinq outils ?

Le standard définit ce que contient un dossier de skill, mais pas où ce dossier se trouve. Son guide pour les développeurs d’outils le dit clairement et présente .agents/skills comme le dossier commun qui se répand d’un outil à l’autre. Voici ce que disait la documentation des cinq outils le 18 octobre 2026 :

Source : la documentation des skills de chaque outil, 18 octobre 2026. Dans ces dossiers, chaque skill occupe son propre sous-dossier : .agents/skills/<nom>/SKILL.md. Cursor lit les dossiers de Claude Code et de Codex par compatibilité. Les dossiers personnels de Copilot viennent de la documentation de la CLI ; celle de VS Code y ajoute ~/.claude/skills. « Non précisé dans la documentation » : dans les pages que nous avons lues ce jour-là, nous n’avons trouvé aucune phrase qui en parle.

Aucun dossier n’apparaît dans la documentation des cinq outils à la fois. Quatre outils lisent .agents/skills ; la documentation de Claude Code ne cite que .claude/skills et ne dit rien de .agents/skills. Outre Claude Code, Cursor et Copilot lisent .claude/skills ; la documentation de Codex et celle de Gemini CLI ne citent pas ce dossier. Qu’un dossier ne figure pas dans la documentation ne veut pas dire que l’outil ne le lit pas. Mais si l’on s’en tient à la documentation, aucun dossier unique ne permet de compter sur l’ouverture d’un skill dans les cinq outils.

Les outils se comportent aussi différemment quand deux skills portent le même nom. Le guide du standard présente la priorité du skill de projet sur le skill personnel comme la convention commune à tous les outils ; la documentation de Gemini CLI et celle de Copilot CLI la suivent. Dans la documentation de Claude Code, l’ordre est inversé : le skill personnel l’emporte sur celui du projet. Codex ne fusionne pas les deux et les affiche tous les deux dans la liste.

Les sous-dossiers ne sont pas lus de la même façon non plus. Claude Code et Codex lisent chaque dossier skills depuis le dossier où vous avez lancé la session jusqu’à la racine du dépôt. Cursor trouve chaque dossier .cursor/skills ou .agents/skills dans le dépôt et ne propose les skills qu’il contient que lorsque vous travaillez sur des fichiers de ce dossier. Gemini CLI ne descend que d’un niveau dans un dossier skills : .gemini/skills/<nom>/SKILL.md est trouvé, ce qui est plus profond ne l’est pas.

Comment utiliser le même skill dans les cinq outils ?

Si vos skills se trouvent dans .agents/skills, Codex, Cursor, Gemini CLI et Copilot les lisent ; Claude Code demande une étape de plus. Le chemin le plus court qu’appuie la documentation est le suivant : écrivez le skill sous .agents/skills/<nom>/ et faites pointer .claude/skills/<nom> vers lui par un symlink.

mkdir -p .claude/skills
# le skill se trouve dans .agents/skills/resume-pr/SKILL.md
ln -s ../../.agents/skills/resume-pr .claude/skills/resume-pr
git add .claude/skills/resume-pr

La documentation de Claude Code indique qu’un dossier de skill (.claude/skills/<nom>) peut être un symlink vers un dossier situé ailleurs. Même si plusieurs emplacements pointent vers la même cible, Claude Code ne charge le skill qu’une fois. Faire de tout le dossier .claude/skills un seul symlink n’y est pas mentionné ; la documentation décrit un lien par skill. Si vous reliez dans l’autre sens, la documentation de Codex indique elle aussi que Codex suit la cible des dossiers de skills reliés par symlink.

Si un membre de l’équipe travaille sous Windows, faites attention à un point. D’après la documentation de Git, quand core.symlinks est désactivé, un symlink est extrait sous la forme d’un petit fichier texte qui contient le chemin du lien. Et git clone désactive ce réglage de lui-même si le système de fichiers ne prend pas en charge les symlinks. Vérifiez à part que le lien fonctionne sur sa machine.

Nous avons aussi regardé ce que font les dépôts populaires. Pour l’article sur AGENTS.md, nous avions examiné le 13 octobre 2026 les 100 dépôts les plus étoilés ; cette fois, nous avons cherché SKILL.md dans les mêmes arborescences. Sur les 98 dépôts dont nous avons pu lire l’arborescence en entier, 41 contiennent au moins un SKILL.md. Parmi eux, 21 rangent leurs skills dans un dossier d’outil à la racine :

Le dossier le plus courant est .agents/skills, celui que lisent quatre outils. 7 dépôts relient les deux dossiers par un symlink. Dans 5 d’entre eux, .claude/skills pointe vers .agents/skills ; dans 1, c’est l’inverse, .agents/skills pointe vers .claude/skills ; et dans 1, .claude/skills pointe vers .github/skills, le dossier de Copilot. vercel/next.js et flutter/flutter relient tout le dossier .claude/skills. langgenius/dify relie au contraire chaque skill séparément, comme le décrit la documentation de Claude Code.

Que met-on en tête d’un SKILL.md ?

Un SKILL.md se compose de deux parties : tout en haut, du YAML entre deux lignes --- (le frontmatter), et en dessous des instructions en Markdown. Le standard définit six champs de frontmatter :

Source : la spécification Agent Skills, 18 octobre 2026.

Les outils n’appliquent pas ces règles avec la même rigueur :

• Dans Claude Code, tous les champs sont facultatifs ; seul description est recommandé. Si name manque, c’est le nom du dossier qui est utilisé. Un champ qu’il ne reconnaît pas est ignoré sans erreur.
• Codex, Cursor, Gemini CLI et Copilot exigent name et description.
• Gemini CLI ignore le fichier sans rien dire si l’un des deux champs manque ou si quoi que ce soit précède la première ligne --- (un titre, un commentaire, même une ligne vide). Il prend aussi le nom du skill dans le champ name, et non dans le dossier ; le standard et Cursor exigent au contraire que le nom soit identique à celui du dossier.
• Copilot CLI accepte aussi dans le nom les majuscules, les espaces, les tirets bas, les points et les deux-points. Le standard n’accepte que les minuscules, les chiffres et les tirets.

Les règles sur les balises XML ne viennent pas du standard, mais d’Anthropic. Selon ses règles pour claude.ai et l’API, name et description ne peuvent pas contenir de balises XML, et name ne peut pas contenir les mots « anthropic » ou « claude ». Les champs propres à Claude Code (comme when_to_use, context et hooks) fonctionnent dans Claude Code. Mais si vous chargez le même skill sur claude.ai ou dans la Skills API, tout champ hors du standard bloque le chargement : Unexpected key(s) in SKILL.md frontmatter.

Si vous comptez utiliser un skill dans plusieurs outils, commencez par les seuls champs du standard. L’exemple ci-dessous n’utilise que les deux champs obligatoires et respecte les règles sur les champs de la documentation des cinq outils :

Pour décider de ce qui va dans le corps, posez à chaque ligne la question du guide du standard : l’agent ferait-il mal cette tâche sans cette instruction ? Si la réponse est non, supprimez la ligne. Déplacez les longs textes de référence sous references/ et liez-les directement depuis SKILL.md. Le standard comme le guide d’Anthropic recommandent de garder les fichiers de référence à un seul niveau de SKILL.md.

Que faut-il écrire dans la description ?

Avant de choisir un skill, l’agent ne voit que sa description. Le guide du standard le dit clairement : « the description carries the entire burden of triggering. » La documentation des outils dit la même chose : Claude Code, Codex, Cursor et Copilot choisissent un skill d’après sa description. Selon le guide de Gemini CLI aussi, la description est la seule information dont le modèle dispose avant d’ouvrir le skill.

• Dites ce que fait le skill et quand l’utiliser. Le standard, Claude Code, Cursor et Copilot demandent les deux ensemble. Une description comme « Helps with PDFs. » ne dit rien à l’agent ; c’est le mauvais exemple du standard lui-même.
• Employez les mots de vos utilisateurs. La liste de dépannage de Claude Code commence par là : la description contient-elle les mots-clés que les utilisateurs diraient naturellement ?
• Mettez l’essentiel au début. Quand la liste ne tient pas, les descriptions sont raccourcies. Claude Code coupe chaque description à 1 536 caractères dans la liste. Codex raccourcit d’abord les descriptions quand beaucoup de skills sont installés ; sa documentation recommande donc de placer le cas d’usage et les mots déclencheurs au début.
• Distinguez-le des skills voisins. Le guide de Gemini CLI veut des descriptions distinctes les unes des autres et de ce que le modèle sait déjà faire.

Les guides divergent sur le point de vue. Le guide d’Anthropic demande la troisième personne et écrit que les descriptions qui commencent par « I can help you… » ou « You can use this… » peuvent gêner la découverte. Le guide d’agentskills.io recommande au contraire d’écrire la description comme une consigne donnée à l’agent, sur le modèle « Use this skill when… ». Les exemples des deux guides suivent le même chemin : d’abord ce que fait le skill, puis, avec « Use when… », quand l’utiliser. L’exemple ci-dessus est écrit de cette façon.

Même une bonne description ne garantit pas que le skill s’ouvre à chaque fois. Selon le guide du standard, les agents se tournent surtout vers les skills pour les tâches qu’ils ne savent pas faire seuls. Une demande en une étape comme « lis ce PDF » peut ne pas ouvrir un skill PDF, même si la description correspond parfaitement. Pour Copilot, la documentation de VS Code indique aussi que la découverte ne garantit pas que le skill soit appelé pour chaque prompt pertinent.

Appelez-vous le skill vous-même, ou l’agent le choisit-il ?

Les deux sont possibles. Dans les cinq outils, l’agent peut ouvrir de lui-même un skill qu’il juge adapté à la tâche. Appeler un skill à la main, et empêcher l’agent de le choisir seul, dépend de l’outil :

Source : la documentation des skills de chaque outil, 18 octobre 2026. Dans Claude Code et Copilot, user-invocable: false fait l’inverse : seul l’agent peut ouvrir le skill.

Désactivez le choix de l’agent pour les tâches qui ont des effets de bord. La documentation de Claude Code le dit ainsi : « You don't want Claude deciding to deploy because your code looks ready. » Les skills qui déploient, font un commit ou envoient des messages sont de ce type. Avec ce réglage, Claude Code ne met pas du tout la description du skill dans le contexte ; elle ne prend donc pas non plus de place dans la liste. Vous trouverez un exemple de skill appelé à la main, qui transforme une demande de review en commande /revue, dans notre article sur le prompt de revue de code.

Gemini CLI fonctionne autrement : seul l’agent peut appeler activate_skill, l’outil qui ouvre un skill ; vous ne le pouvez pas. En revanche, l’agent vous demande votre accord chaque fois qu’il ouvre un skill.

Comment savoir si un skill fonctionne ?

La documentation de Claude Code commence par un avertissement : « Seeing a skill trigger tells you Claude found it, not that it did what you intended. » Qu’un skill s’ouvre et qu’il fasse bien le travail sont deux questions distinctes, et chacune se mesure à part.

Les deux se mesurent par comparaison. Rassemblez quelques prompts réalistes ; lancez chacun dans une nouvelle session, une fois avec le skill activé et une fois avec le skill désactivé, puis mettez les résultats côte à côte. La nouvelle session compte, car le contexte accumulé pendant l’écriture du skill masque les lacunes de ses instructions.

Pour mesurer à quelle fréquence un skill s’ouvre, le guide d’agentskills.io donne une méthode concrète :

• Écrivez environ 20 prompts : la moitié doit ouvrir le skill, l’autre moitié non.
• Choisissez ceux qui ne doivent pas l’ouvrir parmi des tâches voisines. Les prompts qui emploient les mêmes mots mais demandent autre chose montrent le mieux à quel point la description est précise.
• Le modèle ne prend pas toujours la même décision. Lancez chaque prompt plusieurs fois (3 fois, c’est un bon début) et calculez le taux d’ouverture.
• Un seuil de 0,5 est raisonnable : le taux doit être au-dessus pour les prompts qui doivent ouvrir le skill, et en dessous pour les autres.

C’est pourquoi un seul essai ne compte pas comme un résultat. Il est normal qu’un même prompt ouvre le skill lors d’une exécution et pas lors de la suivante ; quand vous modifiez une description, relancez les mêmes prompts le même nombre de fois.

Que vérifier avant d’installer le skill d’un autre ?

Un skill n’est pas qu’un texte : il peut exécuter des scripts, autoriser certains outils sans demander et orienter l’agent par ses instructions. La documentation d’Anthropic écrit qu’un skill malveillant peut amener l’agent à appeler des outils ou à exécuter du code d’une manière qui ne correspond pas à son but affiché, et recommande de n’utiliser que des skills venant de sources de confiance.

Les outils ne traitent pas la confiance de la même façon :

• Claude Code applique le champ allowed-tools d’un skill de projet même lors d’une exécution -p dans un dossier auquel vous n’avez jamais fait confiance. Sa documentation demande donc de lire ce champ dans les skills présents dans un dépôt avant d’y lancer Claude Code. Ce champ ne restreint aucun outil ; il permet d’utiliser sans demander les outils listés pendant le tour où le skill est appelé.
• Copilot indique que les skills installés avec gh skill ne sont pas vérifiés par GitHub et peuvent contenir de l’injection de prompt, des instructions cachées ou des scripts malveillants. Il recommande de les examiner avec gh skill preview avant de les installer.
• Gemini CLI fait confirmer la source lors d’une installation depuis une adresse distante et demande l’autorisation chaque fois qu’il ouvre un skill. Il ne charge par ailleurs les skills de projet sous .gemini/skills que si le dossier de travail est marqué comme fiable.
• Codex et Cursor n’ont aucune règle sur la confiance dans leurs pages sur les skills : non précisé dans la documentation.

Le guide du standard pour les développeurs d’outils recommande lui aussi de ne charger les skills de projet que dans des dossiers marqués comme fiables. Un dépôt que vous venez de cloner peut ajouter des instructions au contexte de l’agent sans que vous le remarquiez.

Faut-il utiliser un skill ou AGENTS.md ?

L’un ne remplace pas l’autre, et les dépôts populaires utilisent les deux. Parmi les 41 dépôts examinés qui contiennent un SKILL.md, 35 ont aussi un AGENTS.md ou un CLAUDE.md à la racine.

Tout dépend du moment où l’information sert. Ce qui vaut pour chaque tâche (la structure du projet, les commandes de build, les règles du type « ne fais jamais ça ») va dans le fichier de règles ; un workflow dont on a besoin de temps en temps, ou un long texte de référence, va dans un skill. Le critère de la documentation de Claude Code est utile : si une section de CLAUDE.md n’est plus une information mais une procédure, faites-en un skill.

Vercel a posé la question à ses propres tests dans un article du 27 janvier 2026. Dans des tests construits sur les API de Next.js 16, le skill n’a jamais été appelé dans 56 % des cas. Un index de documentation de 8 Ko intégré à AGENTS.md a atteint 100 % de réussite ; le meilleur résultat du skill a été de 79 %. C’est la mesure d’une seule équipe sur un seul sujet, et l’article ne dit pas sur combien de tâches elle a été faite. Vercel ne conclut pas non plus à « l’un ou l’autre » : « The two approaches complement each other. » Selon l’article, les workflows précis que l’utilisateur lance explicitement fonctionnent mieux en skill.

Une règle que chaque pull request doit respecter relève aussi du fichier de règles. Quand diffox examine une pull request, il lit le fichier AGENTS.md à la racine du dépôt, ou à défaut CLAUDE.md, et utilise les règles qu’il contient comme règles de review. Si vous voulez qu’une règle s’applique à chaque review, écrivez-la dans le fichier de règles.