Où chaque instruction doit être placée : AGENTS.md, CLAUDE.md et SKILL.md

Plus de 4 300 ingénieurs ont voté en faveur d’un seul problème GitHub demandant que Claude Code charge AGENTS.md sans aide. En juillet 2026, avec la version 2.1.201, cela n’est toujours pas le cas. La documentation interne d’Anthropic indique désormais aux développeurs comment forcer ce comportement : exécuter ln -s AGENTS.md CLAUDE.md dans une terminal. En réalité, le fournisseur fournit une solution de contournement pour un fichier que son propre outil refuse de lire.

L’argument est la partie moins intéressante. La véritable ingénierie se trouve dans une seule ligne du fichier claude-api SKILL.md, dans le répertoire public des compétences d’Anthropic, dans le champ de description de son frontmatter YAML. Contrairement à CLAUDE.md et AGENTS.md, c’est cette description qui détermine si Claude lit le reste du fichier ou non. Trois fichiers et trois modèles de chargement sont impliqués, et la question de l’emplacement trouve sa réponse dès que le mécanisme de contrôle devient visible.

Comment cette séparation a été créée

Le chronologie montre comment l’industrie en est arrivée là. En août 2025, la spécification AGENTS.md a été lancée en tant que ensemble universel d’instructions pour les assistants de codage IA. Les commandes de construction, les règles de test et l’architecture du projet pouvaient être regroupés en un seul endroit, avec pour idée que des outils tels que Cursor, Copilot et les agents indépendants consulteraient ce même fichier.

Deux mois plus tard, en octobre 2025, Anthropic a présenté Agent Skills, qui adoptait une approche différente du contexte. Plutôt qu’un fichier markdown plat contenant des règles, une compétence se présente sous forme de dossier possédant ses propres métadonnées, scripts et documents de référence.

D’ici décembre 2025, ces deux formats étaient devenus des normes ouvertes. La spécification des compétences a été publiée sur agentskills.io, tandis que la spécification AGENTS.md a été transmise à la Linux Foundation en tant que projet phare pour l’Agentic AI Foundation. Plus de 60 000 dépôts et une vingtaine d’outils prennent désormais en charge AGENTS.md directement, ce qui signifie que ces normes ne disparaîtront pas.

En conséquence, les équipes écrivent désormais les mêmes instructions en trois endroits : un AGENTS.md pour l’éditeur, un CLAUDE.md pour le terminal et un SKILL.md pour les workflows complexes. Elles se demandent alors pourquoi les agents ralentissent et pourquoi les frais liés aux tokens augmentent. La solution commence par la manière dont ces outils analysent réellement le texte.

Le contrôle des compétences

Une session ne commence pas par l’agent qui lit tous les fichiers du projet, car cela épuiserait la fenêtre de contexte et affaiblirait l’attention du modèle. Il cherche plutôt des points d’accès spécifiques, ainsi que des compétences qui suivent un modèle de révélation progressive à partir de ces points d’accès.

Lors du démarrage, l’agent charge les métadonnées de chaque compétence installée dans le prompt du système. Ces métadonnées comprennent un nom et une description, ce qui représente environ 100 tokens par compétence. L’agent lit ensuite la demande de l’utilisateur, la compare aux descriptions chargées, et décide s’il faut afficher le contenu d’une compétence. La description agit comme une barrière, avec les matériaux de référence verrouillés derrière elle.

Ci-dessous se trouve le frontmatter de la compétence claude-api, tel qu’il a été publié dans le répertoire ouvert d’Anthropic.

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

Le champ de description remplit une double fonction : il indique à l’agent ce que fait la compétence, et il sert d’interface de programmation permettant à l’auteur de la compétence d’encoder la logique de déclenchement.

TRIGGER et SKIP sont des conventions, et non des champs définis par le schéma. L’auteur écrit simplement des instructions en langue anglaise ordinaire indiquant quand le mécanisme de déclenchement doit s’activer. Le corps de cette compétence comprend des centaines de lignes de références API. Une question concernant une base de données Postgres échoue au contrôle de la description, et le texte de référence reste non chargé.

CLAUDE.md et AGENTS.md se comportent différemment : ils ne disposent pas d’équivalent de ce mécanisme de déclenchement. Une fois qu’un agent les trouve dans le chemin, il les insère au début de la session, et ils restent en vigueur tout au long de la conversation.

Qu’est-ce qui doit se trouver dans quel fichier ?

Le modèle de chargement détermine le contenu. Un fichier injecté ne doit contenir que ce dont l’agent a besoin à chaque tour. Un fichier verrouillé doit contenir des connaissances spécialisées applicables à des tâches particulières.

Un répertoire appelé orchard montre comment ces fichiers peuvent coexister sur le disque sans dupliquer d’informations.

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md contient les règles de construction partagées, y compris les directives de style, la structure du monorepo, les instructions pour exécuter des tests ainsi que des notes sur les dépendances. C’est le contexte de référence dont tout agent a besoin, quel que soit l’outil qui le lit. Son comportement caractéristique est la priorité donnée au fichier le plus proche : un agent travaillant dans services/payments/ lit d’abord le fichier AGENTS.md imbriqué et préfère ses règles locales à celles situées à la racine. OpenAI gère son contexte interne à l’aide d’un modèle de monorepo composé de 88 fichiers, et les fichiers imbriqués permettent de rester ciblé en ne chargeant que ce dont le répertoire actuel a besoin.

CLAUDE.md a une fonction plus restreinte. Il contient des directives qui n’ont de sens que lorsque l’agent actif est Claude Code.

Le surdimensionnement est un problème courant avec les fichiers CLAUDE.md. Les développeurs collent leur fichier AGENTS.md complet dans CLAUDE.md, en supposant que Claude a besoin de sa propre copie des règles de compilation. La forme minimale appropriée, en revanche, importe le standard commun dans le contexte de Claude.

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

Une règle applicable à plusieurs outils doit être placée dans AGENTS.md. L’importation via @AGENTS.md est le modèle principal recommandé dans la documentation sur la mémoire d’Anthropic, tandis que le lien symbolique sert de solution de repli pour les dépôts ne contenant rien de spécifique à Claude mais souhaitant simplement que l’outil lit le fichier standard.

SKILL.md constitue la couche de capacités conditionnelles, destinée aux workflows récurrents, aux capacités ponctuelles et au vocabulaire spécialisé d’un domaine. Dans orchard, le répertoire .agents/skills/db-migration/ contient tout ce qui est nécessaire pour effectuer une migration vers Postgres en toute sécurité, à savoir un script Python permettant de vérifier la réversibilité et une note en markdown sur les modes de verrouillage de Postgres. Rien de tout cela ne doit figurer dans AGENTS.md. Un agent qui modifie un fichier CSS dans le package UI n’a aucune raison de recevoir des informations sur les modes de verrouillage dans son prompt système. Le mécanisme de description garantit que la compétence n’est chargée que lorsque le fichier de migration est modifié.

Une règle de routage

Dès que les modèles de chargement sont prêts, l’ajout d’un nouveau contexte devient mécanique :

• Le contexte de projet partagé, indépendant des outils et nécessaire à chaque étape, doit être placé dans AGENTS.md.
• Les directives réservées uniquement à Claude Code doivent être ajoutées dans CLAUDE.md, de préférence sous forme de fichier court qui importe AGENTS.md.
• Les flux de travail spécifiques à une situation, les scripts et les références sectorielles nécessaires uniquement à certaines tâches doivent être intégrés dans une compétence, accompagnés d’une description indiquant quand l’ouvrir.

Gérer le budget en mode permanent

La différence entre un chargement conditionnel et un chargement en mode permanent est directement liée à la performance de l’agent.

Une étude de janvier 2026 (arXiv:2601.20404) menée par des chercheurs du King’s College London, de la Singapore Management University, de l’Université de Heidelberg et de l’Université de Bamberg a mesuré ce que font réellement les fichiers AGENTS.md. Le temps d’exécution des agents a diminué de 28,64 % et le nombre de tokens générés de 16,58 %, tandis que les tâches étaient accomplies à un rythme similaire. Une couche d’instructions partagée rend les agents plus efficaces : ils cessent d’inventer des commandes de construction et d’exécuter les suites de tests incorrectes, car le modèle lit les règles canoniques une seule fois avant de se lancer dans la tâche.

Cette efficacité n’est maintenue que tant que le contexte reste pertinent. Chaque élément inséré dans la prompt du système sollicite l’attention du modèle. Supposons qu’une équipe colle un guide de 500 mots sur les migrations de base de données dans le fichier AGENTS.md principal. L’agent doit alors le lire tout en corrigeant un bug lié à l’état du frontend, consacrant son attention aux modes de verrouillage de Postgres au lieu de se concentrer sur les hooks React.

Le chargement conditionnel protège ces avantages. En déplaçant les workflows spécifiques dans SKILL.md, on maintient AGENTS.md principal léger, ce qui permet de conserver les gains liés à un contexte partagé et d’éviter de gaspiller de l’attention pour des instructions inutiles.

Le pont qui existe et celui qui n’existe pas

L’écosystème présente un manque de compatibilité en matière de traduction. Claude Code comprend les compétences et leurs mécanismes de détection, mais Cursor, Copilot ainsi que les outils CLI indépendants ne comprennent pas nativement la structure .agents/skills/.

Une équipe qui crée une compétence de migration de base de données souhaite que les utilisateurs de Cursor en profitent également. Copier manuellement cette compétence dans AGENTS.md annulerait l’unique source de vérité, c’est pourquoi la solution réside dans la compilation.

Les agents non Claude peuvent alors voir ces compétences sans duplication manuelle. Le bloc généré, tel qu’il apparaît dans AGENTS.md d’Orchard, se présente comme ceci.

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

Le pont affiche le nom, le chemin et la description de chaque compétence. Les agents non Claude ne disposent pas d’une fonction de révélation progressive intégrée pour ces dossiers, c’est pourquoi le résumé dans le bloc des compétences sert d’interface : un outil qui lit AGENTS.md trouve ce bloc, lit les conditions de déclenchement et apprend où chercher sur le disque pour effectuer une migration.

Le pont qui fait encore défaut est que Claude Code lise nativement AGENTS.md, sans import ni lien symbolique. Un marché des prédictions sur Manifold continue de traiter la question de savoir si Anthropic intégrera un tel support d’ici la fin de l’année. Ce manque indique que les créateurs d’outils souhaitent contrôler leur propre couche de contexte. Anthropic possède CLAUDE.md, tandis que la communauté détient AGENTS.md. La compatibilité croisée dépendra toujours des outils et des pipelines CI, et non de directives de spécification.

Le système en fin de compte

En examinant le monorepo de la ferme fruitière, on constate une configuration fonctionnelle. Les fichiers AGENTS.md imbriqués contiennent les règles structurelles partagées. Un fichier CLAUDE.md d’une seule ligne gère les importations spécifiques à Claude. Le fichier SKILL.md relatif aux migrations de base de données attend, derrière son mécanisme de déclenchement, qu’une tâche sur la base de données le active, et l’action GitHub assemble tout cela afin qu’aucun développeur n’écrive deux fois la même règle.