AGENTS.md vs CLAUDE.md vs skills : qui va où

AGENTS.md est un fichier markdown simple à la racine de votre dépôt qui explique aux agents de codage comment travailler dans votre projet : comment le construire, comment lancer les tests, quelles conventions suivre, quoi ne pas toucher. Aucun schéma, aucune section obligatoire, aucun registre. Le standard entier tient en une phrase : mettez un fichier nommé AGENTS.md dans votre dépôt, et les agents qui supportent la convention le liront avant de toucher à votre code.

Les gens l'appellent le « README pour agents », et l'analogie tient. Un README explique votre projet à des humains qui viennent d'arriver. AGENTS.md l'explique à un logiciel qui vient d'arriver. La différence est que l'agent va vraiment suivre les instructions, donc des instructions vagues coûtent de l'argent réel en tokens gaspillés et modifications erronées.

Nous testons l'outillage d'agents pour gagner notre vie chez SkillProof, et nous avons vu ce fichier passer d'un projet parallèle d'OpenAI au standard le plus proche que le codage agentique ait jamais eu. Cet article couvre son lien avec CLAUDE.md et les autres dialectes d'outils, et où les skills s'insèrent, parce qu'ils résolvent un problème différent de ce que la plupart des gens supposent.

Ce qu'est AGENTS.md, et qui le lit vraiment

La convention est née de l'équipe Codex d'OpenAI mi-2025 et a rapidement été co-signée par Jules de Google, Cursor, Factory, Amp et d'autres. L'argument était simple : chaque fournisseur d'agent avait inventé son propre fichier d'instructions, et les racines de dépôts se remplissaient de markdown quasi identique adressé à différents robots. AGENTS.md a proposé un seul nom de fichier que tout le monde lit.

L'adoption depuis lors a été réelle mais inégale. Voici la carte honnête telle que nous la voyons mi-2026 :

Outil	Lit AGENTS.md	Dialecte natif
OpenAI Codex	Oui, nativement	Aucun, AGENTS.md est le format
GitHub Copilot (agent de codage, VS Code)	Oui	.github/copilot-instructions.md
Cursor	Oui	.cursor/rules/*.mdc
Google Jules	Oui, nativement	Aucun
Gemini CLI	Oui, via config	GEMINI.md
Claude Code	Pas nativement	CLAUDE.md
Zed	Oui	Aucun
Amp	Oui	Aucun
Aider	Non	CONVENTIONS.md
Windsurf	Non	.windsurf/rules/

Deux choses ressortent de ce tableau. D'abord, la colonne des réponses « oui » est longue et ne cesse de s'allonger ; quand un nouvel agent sort en 2026, le support d'AGENTS.md figure généralement dans les notes de lancement. Ensuite, les dialectes n'ont pas disparu. Copilot lit toujours son propre fichier d'instructions, Cursor a toujours des règles avec des globs et des modes de déclenchement qu'AGENTS.md ne peut pas exprimer, et Claude Code, l'outil avec lequel nous passons le plus de temps, veut toujours un CLAUDE.md.

Donc la situation pratique est celle-ci : AGENTS.md est la lingua franca, les dialectes sont là où vit le pouvoir spécifique à l'outil, et toute équipe qui fait tourner plus d'un agent a besoin d'une politique pour les garder synchronisés. Cette politique est l'essentiel de cet article.

Ce qui va dans le fichier est moins contesté que ne l'était le nom du fichier. Les fichiers AGENTS.md qui fonctionnent couvrent les commandes de configuration et de build, comment lancer les tests, les notes de style de code que le linter ne peut pas attraper, et les frontières architecturales (« la logique de paiement vit dans packages/billing, ne la mettez nulle part ailleurs »). Les fichiers qui ne fonctionnent pas se lisent comme des déclarations de mission. Un agent n'a pas besoin de savoir que vous valorisez le code propre. Il a besoin de la commande qui vérifie si le code est propre.

AGENTS.md vs CLAUDE.md

Ces deux fichiers font presque le même travail pour des lecteurs différents. Les deux sont des fichiers d'instructions au niveau projet. Les deux se chargent dans le contexte au début d'une session. Les deux devraient être courts, parce que chaque ligne coûte des tokens à chaque requête. Si vous avez déjà écrit un bon CLAUDE.md, vous savez déjà écrire un bon AGENTS.md, et nos conseils dans les bonnes pratiques CLAUDE.md se transposent presque ligne pour ligne.

Les différences valent la peine d'être connues avant de les unifier :

L'audience. CLAUDE.md est lu par exactement un outil. Cela signifie qu'il peut sans risque référencer des mécanismes spécifiques à Claude : skills, hooks, sous-agents, serveurs MCP, paramètres de permission. Un AGENTS.md qui dit « utilise le skill systematic-debugging avant de proposer un correctif » est du bruit pour Codex et Copilot, qui n'ont aucune idée de ce qu'est un skill.

Hiérarchie et imports. Claude Code fusionne les fichiers CLAUDE.md de plusieurs niveaux (utilisateur global, racine du projet, sous-répertoires) et supporte des imports @path/to/file à l'intérieur. AGENTS.md supporte aussi l'imbrication, le fichier le plus proche l'emportant, mais la syntaxe d'import est propre à Claude.

L'application. Aucun des deux fichiers n'est appliqué de force. Les deux sont des suggestions à un modèle de langage. Tout ce qui doit se produire à chaque fois appartient à un hook ou à la CI, pas à l'un ou l'autre de ces fichiers. Ça déçoit tout le monde de façon égale, quel que soit l'outil.

Si votre équipe utilise Claude Code aux côtés d'autre chose, vous avez besoin des deux fichiers, et le mode d'échec est évident : deux fichiers disant presque la même chose, divergeant jusqu'à ce qu'un agent suive celui qui est périmé. Deux schémas préviennent ça, et nous avons testé les deux.

Le lien symbolique. Faites d'AGENTS.md le vrai fichier et laissez CLAUDE.md pointer vers lui :

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code suit le lien symbolique et lit le contenu comme si c'était son propre fichier. C'est l'option à zéro maintenance, et c'est la bonne quand vous n'avez rien de spécifique à Claude à dire. Sa limite est l'identité exacte : les deux lecteurs reçoivent chaque mot, y compris ceux qui ne concernent que l'autre.

Le wrapper léger. Gardez AGENTS.md comme source partagée, et faites de CLAUDE.md un petit fichier qui l'importe et ajoute des lignes propres à Claude :

# CLAUDE.md
@AGENTS.md

## Claude-specific
- Use the git-workflow skill for commits and PRs.
- Never edit files under infra/ without asking.

C'est ce que nous faisons tourner dans nos propres dépôts. Les faits partagés vivent une seule fois, les extras Claude vivent là où seul Claude les verra, et un diff sur AGENTS.md met à jour chaque outil au même moment. La même forme fonctionne à l'inverse pour d'autres dialectes : gardez .github/copilot-instructions.md et les fichiers de règles Cursor réduits à quelques lignes qui renvoient vers AGENTS.md pour tout ce dont les deux outils ont besoin. Nous avons comparé ces dialectes en détail dans Claude Skills vs règles Cursor et Claude Skills vs instructions Copilot.

Un avertissement issu de nos tests : quel que soit le schéma choisi, choisissez-en un. Les dépôts qui portent un CLAUDE.md complet et un AGENTS.md complet avec un contenu édité indépendamment sont le scénario de dérive avec des étapes en plus.

AGENTS.md vs skills : des couches entièrement différentes

C'est le comparatif que les gens cherchent vraiment, et c'est celui construit sur une erreur de catégorie. AGENTS.md et les skills ne sont pas des formats concurrents. Ils se situent sur des couches différentes de la pile et répondent à des questions différentes.

AGENTS.md répond : que devrait savoir n'importe quel agent sur ce projet ? Ce sont des faits sur un lieu. Ça voyage avec le dépôt, s'applique à quel que soit l'agent qui se présente, et ne dit rien sur comment l'agent fait son travail au-delà des règles locales.

Un skill répond : comment cet agent devrait-il exécuter ce type de tâche ? C'est un comportement, empaqueté dans un dossier avec un SKILL.md, chargé à la demande quand la tâche correspond à sa description. Il voyage avec vous, pas avec le dépôt. Installez un skill de débogage une fois et il fonctionne dans chaque projet que vous ouvrez, que ce projet ait ou non déjà entendu parler de vous. Nous avons couvert la mécanique dans Que sont les skills Claude ?, mais le modèle de chargement est la différence clé : le contenu d'AGENTS.md reste dans le contexte pour toute la session, alors qu'un skill coûte environ cent tokens de métadonnées jusqu'au moment où une tâche le déclenche.

Voici la pile complète telle que nous la dessinons sur les tableaux blancs :

Couche	Vit dans	Limitée à	Chargée	Question à laquelle elle répond
AGENTS.md	Racine du dépôt	Le projet, n'importe quel agent	Chaque session	Qu'est-ce que ce lieu ?
Dialecte d'outil (CLAUDE.md, règles)	Dépôt ou config utilisateur	Le projet, un seul outil	Chaque session	Que devrait faire cet outil ici ?
Skills	~/.claude/skills/ ou .claude/skills/	Un agent, n'importe quel projet	À la demande	Comment ce type de tâche se fait-il ?
Serveurs MCP	Config de l'outil	Une machine ou une équipe	Définitions d'outils toujours dans le contexte	Que peut atteindre l'agent ?

Lisez de haut en bas comme une capacité qui s'élargit et une portabilité qui se rétrécit. Le fichier standard est universel et simple. Le dialecte est lié à l'outil et un peu plus intelligent. Les skills sont riches en comportement mais actuellement liés à l'agent. MCP est une infrastructure vivante avec des identifiants et des processus.

Un exemple concret rend la frontière évidente. « Lance pnpm test --filter=changed avant de commit » est une ligne AGENTS.md : c'est un fait sur votre dépôt, vrai pour chaque agent. « En déboguant, reproduis l'échec avant de proposer un correctif, et ne prétends jamais qu'un correctif fonctionne sans relancer le test qui échouait » est un skill, et c'en est même un que nous avons testé et référencé : systematic-debugging. Il n'a rien à voir avec un dépôt particulier. Le mettre dans AGENTS.md signifie le copier dans chaque projet et payer son coût en tokens à chaque session, y compris les sessions où personne ne débogue quoi que ce soit.

La règle empirique que nous donnons aux équipes : si vous copieriez une ligne dans un second dépôt sans la changer, ce n'est pas du contexte de projet, c'est du comportement, et ça appartient à un skill. Si une ligne n'a de sens que dans ce dépôt, c'est du contexte, et ça appartient à AGENTS.md.

La stratégie pour les équipes qui font tourner plusieurs outils IA

La plupart des équipes à qui nous parlons en 2026 ne sont pas des boutiques mono-agent. Un mélange typique est Claude Code pour le travail lourd, Copilot dans l'éditeur, et Cursor sur quelques machines de résistants. Voici la configuration qui survit au contact avec ça :

1. Écrivez AGENTS.md comme source de vérité. Un fichier, à la racine du dépôt, possédé comme du code. Mettez-y chaque fait dont n'importe quel agent a besoin : commandes, conventions, frontières, avertissements. Relisez les changements en PR, parce qu'une instruction erronée ici induit en erreur chaque agent que votre équipe fait tourner.

2. Gardez les dialectes minces. CLAUDE.md importe AGENTS.md et n'ajoute que des lignes propres à Claude. Les instructions Copilot et les règles Cursor reçoivent le même traitement : un pointeur plus tout ce qui ne peut vraiment pas s'exprimer dans le fichier partagé. Notre test pour « assez mince » est direct : si un fichier de dialecte dépasse un écran, quelque chose dedans appartient probablement à AGENTS.md ou à un skill.

3. Mettez le comportement réutilisable dans des skills. Discipline de débogage, habitudes de commit et de PR, standards d'écriture de tests, formatage de documents. Ça n'appartient à aucun fichier par dépôt parce que ce n'est pas par dépôt. Installez-les une fois par agent et ils vous suivent partout. Nos choix testés pour le travail de code sont rassemblés dans les meilleurs skills de code, et git-workflow est celui que nous installerions en premier sur toute équipe qui tient à l'hygiène des commits.

4. Appliquez avec des hooks et la CI, pas de la prose. Tout ce qui doit se produire 100% du temps ne peut pas vivre dans un fichier markdown lu par un système probabiliste. Le formatage à la sauvegarde est un hook. Les tests avant fusion sont de la CI. Les couches markdown sont pour le jugement, pas l'application.

Cette disposition a une propriété qui mérite d'être nommée : chaque couche change à son propre rythme. AGENTS.md change quand le projet change, les skills changent quand le savoir-faire de votre équipe change, et aucun agent ne lit rien adressé à un autre agent.

Un standard va-t-il l'emporter ?

Notre avis, avec la casquette d'observateur de standards : la couche fichier va converger, et la couche comportement non.

La couche fichier converge parce que toutes les incitations pointent dans le même sens. Un fichier de contexte a une faible surface, les fournisseurs gagnent en compatibilité pour le coût d'une vérification de nom de fichier, et les propriétaires de dépôts sont visiblement fatigués de la prolifération de fichiers d'instructions. Nous nous attendons à un support natif d'AGENTS.md dans Claude Code éventuellement, parce que la pression est publique et que le coût de le supporter est une recherche de fichier. Quand ça arrivera, le schéma de lien symbolique ci-dessus devient une opération neutre que vous pourrez supprimer.

La couche comportement est une autre histoire. Des mécanismes semblables aux skills apparaissent partout : les skills de Claude, les modes de règles de Cursor, les fichiers de prompt de Copilot, diverses fonctionnalités « playbook » sur des agents plus petits. Ils riment, mais chacun encode ses propres idées de fournisseur sur le déclenchement et la portée. La description de déclenchement d'un skill et son chargement progressif correspondent à un glob de règle Cursor à peu près comme une symphonie correspond à une sonnerie de téléphone. Les formats de comportement sont là où les fournisseurs se différencient, donc ils ont toutes les raisons de continuer à diverger.

Et voici la partie que les fournisseurs ne mettent pas dans leurs articles de lancement : la portabilité du format n'est pas la portabilité de la qualité. Un fichier de comportement non testé échoue de la même façon sur chaque outil qui le charge. Il se déclenche quand il ne devrait pas, ou il ne se déclenche jamais. Environ la moitié des skills communautaires que nous récupérons sur GitHub échouent notre première passe de test, et les causes d'échec sont indépendantes du format : des descriptions de déclenchement vagues, et des instructions que l'auteur n'a jamais vérifiées contre un outil réel. Nous avons documenté ce schéma dans pourquoi la moitié des skills Claude ne fonctionnent pas, et tout ce qui s'y trouve s'applique à ce que votre autre agent appelle sa version des skills. Un standard convergé nous donnerait un seul nom de fichier et le même vieux taux de défauts.

Donc : standardisez vos faits, parce que l'écosystème se standardise avec vous. Puis soyez exigeants sur vos comportements, parce que personne ne standardise la qualité.

FAQ

Claude Code lit-il AGENTS.md ?

Pas nativement à la mi-2026. Claude Code cherche CLAUDE.md. Les contournements standards sont un lien symbolique (ln -s AGENTS.md CLAUDE.md) ou un CLAUDE.md mince qui importe le fichier partagé avec @AGENTS.md. Les deux fonctionnent ; la version import vous donne aussi un endroit pour des instructions propres à Claude.

AGENTS.md devrait-il remplacer mon CLAUDE.md ?

Remplacez son contenu, gardez le fichier. Déplacez tout ce qui est indépendant de l'outil vers AGENTS.md, puis réduisez CLAUDE.md à un import plus des lignes propres à Claude sur les skills, hooks et permissions. Supprimer CLAUDE.md complètement n'a de sens qu'avec l'approche du lien symbolique, où les deux sont littéralement les mêmes octets.

Puis-je mettre des instructions de type skill dans AGENTS.md au lieu d'installer des skills ?

Vous pouvez, et pour un seul petit dépôt c'est correct. Les coûts apparaissent à l'échelle : les instructions se chargent à chaque session, pertinentes ou non, et elles ne vous suivent pas vers d'autres projets. Les autres agents qui lisent le fichier reçoivent aussi des conseils de comportement écrits pour Claude. Le comportement que vous réutiliseriez entre dépôts appartient à un skill.

Quelle longueur devrait avoir un AGENTS.md ?

Assez court pour que chaque ligne justifie son coût en contexte. La plupart des bons que nous avons relus font 30 à 80 lignes. Si le vôtre fait plusieurs centaines, il porte probablement du contenu de comportement qui appartient à des skills, ou du matériel de référence qui devrait être un document lié que l'agent lit à la demande.

Les fichiers AGENTS.md de sous-répertoires fonctionnent-ils ?

Oui, la convention supporte l'imbrication : le fichier le plus proche du code en cours d'édition l'emporte pour cette zone. Les monorepos utilisent ça pour donner à chaque paquet ses propres commandes de build et de test. Gardez le fichier racine pour les faits à l'échelle du dépôt et poussez les spécificités des paquets vers le bas. Claude Code applique la même logique de fichier le plus proche à CLAUDE.md, donc le schéma de wrapper s'imbrique proprement aussi.