AGENTS.md vs CLAUDE.md vs skills: wat hoort waar

AGENTS.md is een plat markdown-bestand in de root van je repository dat coding agents vertelt hoe in je project te werken: hoe het te bouwen, hoe de tests te draaien, welke conventies te volgen, wat met rust te laten. Geen schema, geen verplichte secties, geen register. De hele standaard past in één zin: zet een bestand genaamd AGENTS.md in je repo, en agents die de conventie ondersteunen lezen het voordat ze je code aanraken.

Mensen noemen het de "README voor agents," en de analogie klopt. Een README legt je project uit aan mensen die net zijn aangekomen. AGENTS.md legt het uit aan software die net is aangekomen. Het verschil is dat de agent de instructies daadwerkelijk zal volgen, dus vage instructies kosten echt geld aan verspilde tokens en verkeerde edits.

We testen agent-tooling voor de kost bij SkillProof, en we hebben dit bestand zien gaan van een OpenAI-side-project naar het dichtstbijzijnde dat agentic coding heeft aan een gedeelde standaard. Deze post behandelt hoe het zich verhoudt tot CLAUDE.md en de andere tooldialecten, en waar skills passen, want ze lossen een ander probleem op dan de meeste mensen aannemen.

Wat AGENTS.md is, en wie het daadwerkelijk leest

De conventie kwam voort uit OpenAI's Codex-team medio 2025 en werd snel mede-ondertekend door Google's Jules, Cursor, Factory, Amp en anderen. De pitch was simpel: elke agent-leverancier had zijn eigen instructiebestand uitgevonden, en repository-roots vulden zich met bijna-identieke markdown gericht aan verschillende robots. AGENTS.md stelde één bestandsnaam voor die iedereen leest.

De adoptie sindsdien is echt maar ongelijk. Hier is de eerlijke kaart zoals wij hem zien medio 2026:

Tool	Leest AGENTS.md	Native dialect
OpenAI Codex	Ja, native	Geen, AGENTS.md is het formaat
GitHub Copilot (coding agent, VS Code)	Ja	.github/copilot-instructions.md
Cursor	Ja	.cursor/rules/*.mdc
Google Jules	Ja, native	Geen
Gemini CLI	Ja, via config	GEMINI.md
Claude Code	Niet nativ	CLAUDE.md
Zed	Ja	Geen
Amp	Ja	Geen
Aider	Nee	CONVENTIONS.md
Windsurf	Nee	.windsurf/rules/

Twee dingen vallen op in die tabel. Ten eerste is de kolom "ja"-antwoorden lang en blijft groeien; wanneer een nieuwe agent in 2026 verschijnt, staat AGENTS.md-ondersteuning meestal in de lancerings-notities. Ten tweede zijn de dialecten niet verdwenen. Copilot leest nog steeds zijn eigen instructiebestand, Cursor heeft nog steeds rules met globs en triggermodi die AGENTS.md niet kan uitdrukken, en Claude Code, de tool waar wij de meeste tijd mee doorbrengen, wil nog steeds een CLAUDE.md.

Dus de praktische situatie is deze: AGENTS.md is de lingua franca, de dialecten zijn waar toolspecifieke kracht leeft, en elk team dat meer dan één agent draait heeft een beleid nodig om ze gesynchroniseerd te houden. Dat beleid is het grootste deel van dit artikel.

Wat in het bestand hoort is minder omstreden dan de bestandsnaam was. De AGENTS.md-bestanden die werken behandelen setup- en buildcommando's, hoe tests te draaien, codestijl-notities die de linter niet kan vangen, en architecturale grenzen ("betalingslogica leeft in packages/billing, zet het nergens anders"). De bestanden die niet werken lezen als missieverklaringen. Een agent hoeft niet te weten dat je schone code waardeert. Hij heeft het commando nodig dat controleert of de code schoon is.

AGENTS.md vs CLAUDE.md

Deze twee bestanden doen bijna hetzelfde werk voor verschillende lezers. Beide zijn project-level instructiebestanden. Beide laden in context aan het begin van een sessie. Beide moeten kort zijn, want elke regel kost tokens bij elk verzoek. Als je al een goede CLAUDE.md hebt geschreven, weet je al hoe je een goede AGENTS.md schrijft, en ons advies in CLAUDE.md best practices gaat bijna woord voor woord over.

De verschillen zijn het weten waard voordat je ze verenigt:

Publiek. CLAUDE.md wordt gelezen door precies één tool. Dat betekent dat het veilig kan verwijzen naar Claude-specifieke machinerie: skills, hooks, subagents, MCP-servers, permissie-instellingen. Een AGENTS.md die zegt "gebruik de systematic-debugging-skill voordat je een fix voorstelt" is ruis voor Codex en Copilot, die geen idee hebben wat een skill is.

Hiërarchie en imports. Claude Code voegt CLAUDE.md-bestanden samen van verschillende niveaus (gebruiker-globaal, projectroot, submappen) en ondersteunt @pad/naar/bestand-imports erbinnen. AGENTS.md ondersteunt ook nesting, waarbij het dichtstbijzijnde bestand voorrang krijgt, maar de import-syntax is die van Claude zelf.

Handhaving. Geen van beide bestanden wordt afgedwongen. Beide zijn suggesties aan een taalmodel. Alles wat elke keer moet gebeuren, hoort in een hook of CI, niet in een van beide bestanden. Dit stelt mensen bij alle tools evenzeer teleur.

Als je team Claude Code naast iets anders gebruikt, heb je beide bestanden nodig, en de faalmodus is duidelijk: twee bestanden die bijna hetzelfde zeggen, uit elkaar drijvend tot een agent het verouderde volgt. Twee patronen voorkomen dat, en we hebben ze beide getest.

De symlink. Maak AGENTS.md het echte bestand en laat CLAUDE.md ernaar wijzen:

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

Claude Code volgt de symlink en leest de inhoud alsof het zijn eigen bestand was. Dit is de zero-onderhoud-optie, en het is de juiste keuze wanneer je niets Claude-specifieks te zeggen hebt. De beperking is exacte identiteit: beide lezers krijgen elk woord, inclusief de woorden die alleen relevant zijn voor de ander.

De dunne wrapper. Houd AGENTS.md als de gedeelde bron, en maak CLAUDE.md een klein bestand dat het importeert en Claude-only regels toevoegt:

# CLAUDE.md
@AGENTS.md

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

Dit is wat wij in onze eigen repo's draaien. De gedeelde feiten leven één keer, de Claude-extra's leven waar alleen Claude ze ziet, en een diff naar AGENTS.md werkt elke tool tegelijk bij. Dezelfde vorm werkt omgekeerd voor andere dialecten: houd .github/copilot-instructions.md en Cursor rule-bestanden tot een paar regels die verwijzen naar AGENTS.md voor alles wat beide tools nodig hebben. We vergeleken die dialecten in detail in Claude skills vs Cursor rules en Claude skills vs Copilot instructions.

Eén waarschuwing uit ons testwerk: welk patroon je ook kiest, kies er één. Repo's die een volledige CLAUDE.md en een volledige AGENTS.md dragen met onafhankelijk bewerkte inhoud zijn het drift-scenario met extra stappen.

AGENTS.md vs skills: totaal verschillende lagen

Dit is de vergelijking waar mensen daadwerkelijk naar zoeken, en het is degene gebouwd op een categoriefout. AGENTS.md en skills zijn geen concurrerende formaten. Ze zitten op verschillende lagen van de stack en beantwoorden verschillende vragen.

AGENTS.md beantwoordt: wat moet elke agent weten over dit project? Het zijn feiten over een plek. Het reist mee met de repository, geldt voor welke agent er ook verschijnt, en zegt niets over hoe de agent zijn werk doet buiten lokale regels.

Een skill beantwoordt: hoe moet deze agent dit soort taak uitvoeren? Het is een gedrag, verpakt in een map met een SKILL.md, geladen op aanvraag wanneer de taak bij zijn beschrijving past. Het reist mee met jou, niet met de repo. Installeer een debug-skill één keer en hij werkt in elk project dat je opent, of dat project ooit van je gehoord heeft of niet. We behandelden de mechanica in Wat zijn Claude skills?, maar het laadmodel is het belangrijkste verschil: AGENTS.md-inhoud zit in context voor de hele sessie, terwijl een skill ongeveer honderd tokens metadata kost tot het moment dat een taak hem triggert.

Hier is de volledige stack zoals wij hem op whiteboards tekenen:

Laag	Leeft in	Geschaald naar	Geladen	Vraag die het beantwoordt
AGENTS.md	Repo-root	Het project, elke agent	Elke sessie	Wat is deze plek?
Tooldialect (CLAUDE.md, rules)	Repo of gebruikersconfig	Het project, één tool	Elke sessie	Wat moet deze tool hier doen?
Skills	~/.claude/skills/ of .claude/skills/	Eén agent, elk project	Op aanvraag	Hoe wordt dit soort taak gedaan?
MCP-servers	Toolconfig	Eén machine of team	Tooldefinities altijd in context	Wat kan de agent bereiken?

Lees het van boven naar beneden als verbredende capaciteit en versmallende portabiliteit. Het standaardbestand is universeel en dom. Het dialect is toolgebonden en iets slimmer. Skills zijn gedragsrijk maar momenteel agent-gebonden. MCP is live infrastructuur met credentials en processen.

Een concreet voorbeeld maakt de grens duidelijk. "Draai pnpm test --filter=changed voor het committen" is een AGENTS.md-regel: het is een feit over je repo, waar voor elke agent. "Reproduceer bij het debuggen de storing voordat je een fix voorstelt, en beweer nooit dat een fix werkt zonder de falende test opnieuw te draaien" is een skill, en het is er zelfs een die we getest en vermeld hebben: systematic-debugging. Het heeft niets te maken met een bepaalde repo. Het in AGENTS.md zetten betekent het kopiëren naar elk project en zijn tokenkost betalen in elke sessie, inclusief sessies waar niemand iets debugt.

De vuistregel die we teams geven: als je een regel ongewijzigd naar een tweede repo zou kopiëren, is het geen projectcontext, het is gedrag, en het hoort in een skill. Als een regel alleen zin heeft in deze repo, is het context, en het hoort in AGENTS.md.

De strategie voor teams die meerdere AI-tools draaien

De meeste teams waarmee we praten in 2026 zijn geen single-agent shops. Een typische mix is Claude Code voor zwaarder werk, Copilot in de editor, en Cursor op een paar achterblijversmachines. Hier is de configuratie die het contact hiermee overleeft:

1. Schrijf AGENTS.md als de bron van waarheid. Eén bestand, in de repo-root, bezeten als code. Zet elk feit dat elke agent nodig heeft erin: commando's, conventies, grenzen, waarschuwingen. Review wijzigingen erin in PR's, want een verkeerde instructie hier misleidt elke agent die je team draait.

2. Houd de dialecten dun. CLAUDE.md importeert AGENTS.md en voegt alleen Claude-specifieke regels toe. Copilot instructions en Cursor rules krijgen dezelfde behandeling: een verwijzing plus wat echt niet uit te drukken is in het gedeelde bestand. Onze test voor "dun genoeg" is bot: als een dialectbestand langer is dan een scherm, hoort iets erin waarschijnlijk in AGENTS.md of in een skill.

3. Zet herbruikbaar gedrag in skills. Debugdiscipline, commit- en PR-gewoontes, testschrijf-standaarden, documentopmaak. Deze horen in geen enkel per-repo-bestand omdat ze niet per-repo zijn. Installeer ze één keer per agent en ze volgen je overal. Onze geteste keuzes voor coding-werk staan verzameld in de beste coding-skills, en git-workflow is degene die we het eerst zouden installeren op elk team dat om commit-hygiëne geeft.

4. Handhaaf met hooks en CI, niet met proza. Alles wat 100% van de tijd moet gebeuren kan niet leven in een markdown-bestand gelezen door een probabilistisch systeem. Formatteren bij opslaan is een hook. Tests voor merge is CI. De markdown-lagen zijn voor oordeel, niet voor handhaving.

Deze indeling heeft een eigenschap die het waard is te benoemen: elke laag verandert op zijn eigen tempo. AGENTS.md verandert wanneer het project verandert, skills veranderen wanneer het vakmanschap van je team verandert, en geen agent leest iets gericht aan een andere agent.

Zal er één standaard winnen?

Onze inschatting, met de standaardwatcher-pet op: de bestandslaag zal convergeren, en de gedragslaag niet.

De bestandslaag convergeert omdat de prikkels allemaal dezelfde kant op wijzen. Een contextbestand heeft een klein oppervlak, leveranciers winnen compatibiliteit voor de prijs van één bestandsnaamcontrole, en repo-eigenaren zijn zichtbaar moe van instructiebestand-wildgroei. We verwachten uiteindelijk native AGENTS.md-ondersteuning in Claude Code, want de druk is publiek en de kost van ondersteuning is een bestandsopzoeking. Wanneer dat gebeurt, wordt het symlink-patroon hierboven een no-op die je kunt verwijderen.

De gedragslaag is een ander verhaal. Skill-achtige mechanismen verschijnen overal: Claude's skills, Cursors rule-modi, Copilots prompt-bestanden, allerlei "playbook"-features bij kleinere agents. Ze rijmen, maar elk codeert de eigen ideeën van zijn leverancier over triggering en scoping. De triggerbeschrijving en progressive loading van een skill mappen op een Cursor rule-glob ongeveer zoals een symfonie op een ringtone mapt. Gedragsformaten zijn waar leveranciers zich onderscheiden, dus hebben ze alle reden om verder uiteen te blijven lopen.

En hier is het deel dat leveranciers niet in lanceringsposts zetten: portabiliteit van formaat is geen portabiliteit van kwaliteit. Een ongetest gedragsbestand faalt op dezelfde manier op elke tool die het laadt. Het triggert wanneer het niet zou moeten, of het triggert nooit. Ruwweg de helft van de community-skills die we van GitHub trekken faalt onze eerste testronde, en de faaloorzaken zijn formaat-onafhankelijk: vage triggerbeschrijvingen, en instructies die de auteur nooit tegen een echte tool verifieerde. We schreven het patroon op in waarom de helft van de Claude skills niet werkt, en alles erin geldt voor wat je andere agent zijn versie van skills ook noemt. Een geconvergeerde standaard zou ons één bestandsnaam geven en hetzelfde oude defectpercentage.

Dus: standaardiseer je feiten, want het ecosysteem standaardiseert met je mee. Wees dan kieskeurig over je gedragingen, want niemand standaardiseert kwaliteit.

FAQ

Leest Claude Code AGENTS.md?

Niet nativ, medio 2026. Claude Code zoekt naar CLAUDE.md. De standaard workarounds zijn een symlink (ln -s AGENTS.md CLAUDE.md) of een dunne CLAUDE.md die het gedeelde bestand importeert met @AGENTS.md. Beide werken; de import-versie geeft je ook een plek voor Claude-only instructies.

Moet AGENTS.md mijn CLAUDE.md vervangen?

Vervang de inhoud, behoud het bestand. Verplaats alles toolagnostisch naar AGENTS.md, verklein dan CLAUDE.md tot een import plus Claude-specifieke regels over skills, hooks en permissies. CLAUDE.md volledig verwijderen heeft alleen zin bij de symlink-aanpak, waar de twee letterlijk dezelfde bytes zijn.

Kan ik skill-achtige instructies in AGENTS.md zetten in plaats van skills te installeren?

Dat kan, en voor een enkele kleine repo is het prima. De kosten verschijnen op schaal: de instructies laden in elke sessie of ze relevant zijn of niet, en ze volgen je niet naar andere projecten. Andere agents die het bestand lezen krijgen ook gedragsbegeleiding geschreven voor Claude. Gedrag dat je over repo's zou hergebruiken hoort in een skill.

Hoe lang moet een AGENTS.md zijn?

Kort genoeg dat elke regel zijn contextkost verdient. De meeste goede die wij hebben gereviewd zijn 30 tot 80 regels. Als de jouwe honderden regels is, draagt hij waarschijnlijk gedragsinhoud die in skills hoort, of referentiemateriaal dat een gelinkt document zou moeten zijn dat de agent op aanvraag leest.

Werken submap-AGENTS.md-bestanden?

Ja, de conventie ondersteunt nesting: het bestand dichtst bij de bewerkte code wint voor dat gebied. Monorepo's gebruiken dit om packages hun eigen build- en testcommando's te geven. Houd het root-bestand voor repo-brede feiten en duw pakket-specifieke zaken naar beneden. Claude Code past dezelfde dichtstbijzijnde-bestand-logica toe op CLAUDE.md, dus het wrapper-patroon nest ook netjes.