Aller au contenu principal

SKILL.md : le standard ouvert inter-agents

Intermédiaire

Pendant quelques années, chaque agent de code avait son propre fichier : .cursorrules, CLAUDE.md, prompts système Codex, instructions Gemini, et une douzaine d'autres. Puis Anthropic a discrètement transformé son format interne Skills en spécification ouverte — et en 48 heures les plus grands agents du monde lisaient les fichiers les uns des autres. Aujourd'hui, un simple dossier nommé code-reviewer/ contenant un SKILL.md s'exécute sans modification dans Claude Code, Codex CLI, ChatGPT, Gemini CLI, Junie, Kiro, Goose et Cursor. C'est ce qui se rapproche le plus, dans le monde des agents, d'une prise universelle partagée.

Cette page est le guide pratique de terrain : ce qu'est vraiment le standard au niveau octet, l'unique astuce ingénieuse (la divulgation progressive) qui rend abordable l'installation de 100 skills, précisément quels champs cassent la portabilité dès qu'on y touche, le tableau honnête de la sécurité, et une skill portable prête à copier-coller que vous pouvez expédier dès aujourd'hui.

What you'll learn
  • Comprendre ce qu'est SKILL.md au niveau du format de fichier — champs obligatoires, champs optionnels, structure de répertoire
  • Comprendre la divulgation progressive : pourquoi 100 skills coûtent ~10 000 tokens au démarrage, et non 100× le corps
  • Connaître les extensions propriétaires exactes qui cassent silencieusement la portabilité entre agents
  • Écrire une skill qui s'exécute sans modification dans Claude Code, Codex CLI et Gemini CLI
  • Peser honnêtement le compromis de sécurité avant d'installer des skills depuis n'importe quel marketplace

Ce qu'est vraiment le standard​

Une fois le marketing mis de côté, le standard ouvert Agent Skills est assez compact pour tenir dans votre tête :

  • Un dossier dont le nom est le name de la skill
  • Un fichier SKILL.md obligatoire à l'intérieur — frontmatter YAML, puis corps Markdown
  • Frères optionnels : scripts/ (exécutables que la skill peut lancer), references/ (documents que la skill peut charger à la demande), assets/ (modèles, images, fichiers de prompt), et — ajouté plus tard — agents/ pour une configuration propriétaire opt-in

Voilà toute la surface. Deux champs obligatoires de frontmatter font l'essentiel du travail :

  • name — jusqu'à 64 caractères, lowercase-with-hyphens, doit correspondre au dossier parent
  • description — jusqu'à 1 024 caractères, la phrase que l'agent utilise pour décider s'il doit charger cette skill pour la tâche en cours

Tout le reste — license, compatibility, metadata, et le encore-expérimental allowed-tools — est optionnel et ignoré sans risque par les outils qui ne le comprennent pas. Les corps sont en Markdown ; la convention communautaire est de les garder sous ~5 000 tokens, et les skills du monde réel le font majoritairement : la taille médiane d'une skill sur le plus grand marketplace est d'environ 1 414 tokens avec 90 % sous 3 935 tokens.

L'unique astuce ingénieuse : la divulgation progressive​

Si SKILL.md fonctionne à grande échelle, ce n'est pas grâce au format de fichier — c'est grâce à la manière dont les agents le chargent. Tous les agents conformes implémentent trois niveaux :

Guided walkthrough1 of 3
  1. L'agent parcourt le dossier des skills et ne lit que le frontmatter de chaque SKILL.md. Cela représente environ 100 tokens par skill. Installez 100 skills et vous avez dépensé ~10 000 tokens de contexte avant même votre premier prompt — moins cher qu'un unique long message système.

C'est pourquoi la spécification plafonne description si strictement et la traite comme un champ de premier ordre : c'est le seul texte que le modèle voit lorsqu'il choisit d'activer la skill. Une description vague est la raison la plus courante pour laquelle une skill qui "devrait fonctionner" ne se déclenche jamais.

:::tip Rédigez la description en dernier, puis réécrivez-la Une fois le corps de la skill solide, revenez traiter la description comme votre texte publicitaire. Elle a un seul rôle : aider le modèle à reconnaître la forme d'une tâche que cette skill doit gérer. "Fait la revue des pull requests" est mauvais. "Fait la revue d'un diff de PR pour bugs de logique, tests manquants et conventions du projet violées ; à utiliser dès que l'utilisateur demande une revue, une code review, ou 'jette un œil à cette PR'" est bon. :::

Le répertoire universel​

Chaque agent conforme attend la même structure. Celle-ci fonctionne partout :

code-reviewer/
├── SKILL.md          # obligatoire — les instructions que l'agent lit
├── scripts/          # optionnel — exécutables que la skill peut invoquer
│   └── run-linters.sh
├── references/       # optionnel — longs docs que la skill charge à la demande
│   └── style-guide.md
├── assets/           # optionnel — modèles, fichiers de prompt, snippets
│   └── pr-comment-template.md
└── agents/           # optionnel — PROPRIÉTAIRE, opt-in uniquement
    └── openai.yaml   # ignoré par tout agent non-Codex

Le sous-dossier agents/ est la soupape de sécurité du standard : il permet aux éditeurs d'expédier des extensions sans contaminer le cœur portable. Un fichier à agents/openai.yaml est spécifique à Codex et tous les autres agents l'ignoreront simplement. Utilisez-le quand vous avez besoin de puissance supplémentaire ; sachez qu'il vous coûte en portabilité.

Ce qui voyage vraiment vs ce qui ne voyage pas silencieusement​

Toute la spécification a été conçue pour la portabilité, mais les vraies skills sur le terrain ont trois modes d'échec.

Ce que vous utilisezPortable ?Pourquoi
name, description, corps Markdown✅ OuiSpécification centrale. Tout agent conforme les lit à l'identique.
scripts/, references/, assets/ référencés depuis le corps✅ OuiLa structure de répertoire fait partie de la spec ; les agents les liront quand le corps le demandera.
license, metadata✅ Oui (ignorables sans risque)Champs optionnels — les agents non-supportants sautent sans erreur.
Frontmatter allowed-tools⚠️ PartielMarqué expérimental dans la spec ; la syntaxe n'est pas standardisée entre agents. Claude Code honore une forme, Codex CLI une autre, la plupart des autres l'ignorent totalement.
Liste when_to_use de Claude Code❌ Claude uniquementSilencieusement ignorée par Codex, Gemini CLI et tous les autres.
Drapeau sous-agent context: fork de Claude Code❌ Claude uniquementSémantique d'exécution de sous-agent non portable — le comportement du modèle diffère partout ailleurs.
Extensions agents/openai.yaml❌ Codex uniquementExplicitement à portée éditeur par conception. Portable parce que les autres agents l'ignorent.

La leçon est brutale : tenez-vous en à name + description + corps Markdown + les trois sous-dossiers optionnels et votre skill s'exécute partout. Touchez à n'importe quel champ de frontmatter au-delà des deux du cœur et vous construisez pour un seul agent. C'est un choix légitime — certaines skills en ont vraiment besoin — mais faites-le délibérément, pas parce que vous avez copié-collé un modèle.

Comment fonctionne réellement l'activation (par agent)​

La spec standardise le fichier, pas la décision. Chaque agent lance toujours sa propre logique d'activation sur les descriptions qu'il a lues au démarrage :

  • Claude Code compare la lecture par le modèle du tour en cours avec description et (si présente) la liste when_to_use spécifique à Claude ; l'activation est une décision du modèle, pas une règle de mots-clés.
  • Codex CLI utilise la même activation pilotée par description, avec des surcharges optionnelles dans agents/openai.yaml.
  • Gemini CLI charge de même les descriptions au démarrage et laisse Gemini choisir ; le comportement suit les heuristiques de sélection d'outils propres à Gemini.
  • Cursor, Junie, Kiro, Goose implémentent tous une activation pilotée par description avec de légères variations de pondération.

Conséquence pratique : une skill qui ne se déclenche jamais sur un agent mais fonctionne sur un autre a presque toujours un problème de description, pas un problème de corps. Réécrivez la description pour décrire la forme de la requête utilisateur, pas les rouages internes de la skill, et le taux de déclenchement monte simultanément sur tous les agents.

Un SKILL.md portable que vous pouvez copier​

Voici une skill de code review minimale et véritablement portable. Placez-la dans ~/.agents/skills/code-reviewer/SKILL.md et elle s'exécutera dans Claude Code, Codex CLI, ChatGPT et Gemini CLI sans modification.

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

Chaque ligne de cette skill s'exécute sur tout agent conforme. Rien dans le frontmatter n'est à portée éditeur. Le corps utilise des titres Markdown simples que tout agent parse.

Comparez maintenant à une variante non portable — subtilement, elle est réservée à Claude :

Variante Claude uniquement (à ne pas utiliser si vous voulez la portabilité)

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

Trois choses cassent la portabilité d'un coup : when_to_use (Claude Code uniquement), context: fork (sémantique de sous-agent Claude Code), et allowed-tools (expérimental, non honoré de manière cohérente). Codex lira la description comme "Reviews a diff or pull request" — ce qui est si vague qu'elle ne s'activera presque jamais — et ignorera le reste.

Le tableau de la sécurité (soyez honnête avec vous-même)​

La vérité inconfortable sur l'installation de skills depuis n'importe quel marketplace : une skill est un ensemble d'instructions arbitraires données à un agent très capable qui s'exécute dans votre environnement avec vos permissions. Le standard ne spécifie ni signature de code, ni bac à sable, ni revue obligatoire, ni modèle de permissions d'exécution. C'est par conception une spécification de fichier texte, pas une spécification de sécurité.

Les chiffres concrets, tirés d'analyses indépendantes de grands catalogues publics de skills (vérifiez à la source avant de citer) :

  • Environ une sur trois des skills partagées publiquement contient au moins un défaut lié à la sécurité — instructions shell trop larges, secrets en dur, appels vers des URLs non fiables, ou étapes d'amorçage du type curl | sh.
  • Un sous-ensemble plus petit mais non nul de skills a été signalé comme purement malveillant — tentatives d'exfiltration, collecte d'identifiants, ou opérations destructrices.
  • Les skills héritent de tout ce dont hérite l'agent. Si votre agent peut lire ~/.ssh/, toute skill que vous installez le peut aussi.

Défenses pratiques qui fonctionnent réellement :

Guided walkthrough1 of 4
  1. C'est du Markdown. Cela prend une minute. Si la description dit 'formate la prose' et que le corps contient un `curl` vers une URL que vous ne reconnaissez pas, c'est le moment de vous arrêter.

Pour un approfondissement sur la manière dont les skills sont compromises et ce qu'il faut vérifier, voyez Vetting Agent Skills et Coding Agents Under Attack.

Quand écrire une skill vs quand simplement rédiger un prompt​

Les nouveaux mainteneurs d'un catalogue de skills en produisent souvent trop. Une règle utile :

  • Prompt pour une tâche ponctuelle ou une forme que vous n'utiliserez que dans un seul projet. Les skills entraînent un coût de démarrage — même faible — et encombrent votre budget de descriptions.
  • Écrivez une skill quand les mêmes instructions s'appliquent à travers de nombreuses conversations ou projets (revue de code, rédaction de messages de commit, génération de changelog, extraction de factures) et que la description serait sans ambiguïté. Si vous n'arrivez pas à écrire une description nette, la skill ne se déclenchera pas de manière fiable de toute façon.
  • Optez plutôt pour un sous-agent quand la tâche a besoin de son propre jeu d'outils, de son propre choix de modèle, ou d'un vrai parallélisme. Les skills instruisent le modèle principal ; les sous-agents s'exécutent séparément. Voir Subagents.

Lectures liées​

Vérifiez votre maîtrise​

Check yourself

0/4
  1. Vous installez 100 skills. Environ combien de tokens leurs descriptions coûtent-elles à votre agent au démarrage ?
  2. Lequel de ces champs de frontmatter cassera silencieusement votre skill sur Codex CLI et Gemini CLI même s'il fonctionne dans Claude Code ?
  3. Une skill que vous avez écrite se déclenche de manière fiable dans Claude Code mais presque jamais dans Codex CLI. Quelle est la chose à corriger en premier avec le plus grand effet de levier ?
  4. Pourquoi la posture de sécurité des Agent Skills est-elle fondamentalement plus faible que, disons, celle des paquets npm avec lockfiles et outillage d'audit ?

Sources et lectures complémentaires​