AGENTS.md vs CLAUDE.md vs skills: vad hör hemma var

AGENTS.md är en vanlig markdown-fil i roten av ditt repository som talar om för kodningsagenter hur de ska jobba i ditt projekt: hur man bygger det, hur man kör testerna, vilka konventioner som ska följas, vad som ska lämnas ifred. Inget schema, inga obligatoriska sektioner, inget register. Hela standarden ryms i en mening: lägg en fil som heter AGENTS.md i ditt repo, så läser agenter som stödjer konventionen den innan de rör din kod.

Folk kallar det "README för agenter," och analogin håller. En README förklarar ditt projekt för människor som just anlänt. AGENTS.md förklarar det för mjukvara som just anlänt. Skillnaden är att agenten faktiskt kommer följa instruktionerna, så vaga sådana kostar riktiga pengar i bortkastade tokens och felaktiga redigeringar.

Vi testar agentverktyg för vårt levebröd på SkillProof, och vi har sett den här filen gå från ett OpenAI-sidoprojekt till det närmaste agentkodning har en delad standard. Det här inlägget täcker hur den relaterar till CLAUDE.md och de andra verktygsdialekterna, och var skills passar in, för de löser ett annat problem än de flesta antar.

Vad AGENTS.md är, och vem som faktiskt läser den

Konventionen kom från OpenAIs Codex-team i mitten av 2025 och skrevs snabbt under av Googles Jules, Cursor, Factory, Amp och andra. Pitchen var enkel: varje agentleverantör hade uppfunnit sin egen instruktionsfil, och repo-rötter fylldes med nästan identisk markdown adresserad till olika robotar. AGENTS.md föreslog ett filnamn som alla läser.

Adoptionen sedan dess har varit verklig men ojämn. Här är den ärliga kartan som vi ser den i mitten av 2026:

Verktyg	Läser AGENTS.md	Egen dialekt
OpenAI Codex	Ja, inbyggt	Ingen, AGENTS.md är formatet
GitHub Copilot (kodningsagent, VS Code)	Ja	.github/copilot-instructions.md
Cursor	Ja	.cursor/rules/*.mdc
Google Jules	Ja, inbyggt	Ingen
Gemini CLI	Ja, via konfiguration	GEMINI.md
Claude Code	Inte inbyggt	CLAUDE.md
Zed	Ja	Ingen
Amp	Ja	Ingen
Aider	Nej	CONVENTIONS.md
Windsurf	Nej	.windsurf/rules/

Två saker sticker ut i den tabellen. För det första, kolumnen med "ja"-svar är lång och blir längre; när en ny agent släpps 2026 finns AGENTS.md-stöd oftast med i lanseringsanteckningarna. För det andra har dialekterna inte försvunnit. Copilot läser fortfarande sin egen instructions-fil, Cursor har fortfarande rules med globs och triggerlägen som AGENTS.md inte kan uttrycka, och Claude Code, verktyget vi tillbringar mest tid med, vill fortfarande ha en CLAUDE.md.

Så den praktiska situationen är denna: AGENTS.md är lingua francan, dialekterna är där verktygsspecifik kraft bor, och alla team som kör mer än en agent behöver en policy för att hålla dem synkade. Den policyn är merparten av den här artikeln.

Vad som ska stå i filen är mindre omtvistat än filnamnet var. De AGENTS.md-filer som fungerar täcker uppsättnings- och byggkommandon, hur man kör tester, kodstilsanteckningar lintern inte kan fånga, och arkitektoniska gränser ("betalningslogik bor i packages/billing, lägg den ingen annanstans"). Filerna som inte fungerar läser som visionsdokument. En agent behöver inte veta att du värderar ren kod. Den behöver kommandot som kontrollerar om koden är ren.

AGENTS.md vs CLAUDE.md

De här två filerna gör nästan samma jobb för olika läsare. Båda är projektnivå-instruktionsfiler. Båda laddas in i kontexten vid start av en session. Båda bör vara korta, för varje rad kostar tokens i varje förfrågan. Om du redan har skrivit en bra CLAUDE.md kan du redan skriva en bra AGENTS.md, och våra råd i CLAUDE.md best practices överförs nästan rad för rad.

Skillnaderna är värda att känna till innan du enar dem:

Målgrupp. CLAUDE.md läses av exakt ett verktyg. Det betyder att den säkert kan referera Claude-specifik maskineri: skills, hooks, subagenter, MCP-servrar, behörighetsinställningar. En AGENTS.md som säger "använd systematic-debugging-skillen innan du föreslår en fix" är brus för Codex och Copilot, som inte har en aning om vad en skill är.

Hierarki och imports. Claude Code slår ihop CLAUDE.md-filer från flera nivåer (användarglobal, projektrot, undermappar) och stödjer @sökväg/till/fil-imports inuti dem. AGENTS.md stödjer nästling också, med den närmaste filen som prioriterad, men import-syntaxen är Claudes egen.

Efterlevnad. Ingen av filerna efterlevs. Båda är förslag till en språkmodell. Allt som måste hända varje gång hör hemma i en hook eller CI, inte i endera filen. Det här besviker alla lika mycket, oavsett verktyg.

Om ditt team använder Claude Code vid sidan av något annat behöver du båda filerna, och feltypen är uppenbar: två filer som säger nästan samma sak, som glider isär tills en agent följer den föråldrade. Två mönster förhindrar det, och vi har testat båda.

Symlinken. Gör AGENTS.md till den verkliga filen och låt CLAUDE.md peka på den:

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

Claude Code följer symlinken och läser innehållet som om det vore dess egen fil. Det här är alternativet med noll underhåll, och det är rätt val när du inte har något Claude-specifikt att säga. Dess begränsning är exakt identitet: båda läsarna får varje ord, inklusive de som bara är relevanta för den andra.

Den tunna wrappern. Håll AGENTS.md som den delade källan, och gör CLAUDE.md till en liten fil som importerar den och lägger till Claude-bara rader:

# CLAUDE.md
@AGENTS.md

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

Det här är vad vi kör i våra egna repos. De delade fakta lever en gång, Claude-extrorna lever där bara Claude ser dem, och en diff till AGENTS.md uppdaterar varje verktyg i samma ögonblick. Samma form fungerar omvänt för andra dialekter: håll .github/copilot-instructions.md och Cursor-regelfiler nere på några rader som hänvisar till AGENTS.md för allt båda verktygen behöver. Vi jämförde de dialekterna i detalj i Claude-skills vs Cursor rules och Claude-skills vs Copilot instructions.

En varning från vår testning: oavsett vilket mönster du väljer, välj ett. Repos som bär en fullständig CLAUDE.md och en fullständig AGENTS.md med oberoende redigerat innehåll är glidningsscenariot med extra steg.

AGENTS.md vs skills: helt olika lager

Det här är jämförelsen folk faktiskt söker efter, och den bygger på ett kategorimisstag. AGENTS.md och skills konkurrerar inte om samma format. De ligger på olika lager av stacken och besvarar olika frågor.

AGENTS.md besvarar: vad borde vilken agent som helst veta om det här projektet? Det är fakta om en plats. Det reser med repositoryn, gäller för vilken agent som än dyker upp, och säger inget om hur agenten gör sitt jobb bortom lokala regler.

En skill besvarar: hur ska den här agenten utföra den här typen av uppgift? Det är ett beteende, paketerat i en mapp med en SKILL.md, laddat på begäran när uppgiften matchar dess beskrivning. Det reser med dig, inte med repot. Installera en felsökningsskill en gång och den fungerar i varje projekt du öppnar, oavsett om det projektet någonsin hört talas om dig. Vi täckte mekaniken i Vad är Claude-skills?, men laddningsmodellen är nyckelskillnaden: AGENTS.md-innehåll ligger i kontexten för hela sessionen, medan en skill kostar ungefär hundra tokens metadata tills det ögonblick en uppgift triggar den.

Här är hela stacken som vi ritar den på whiteboards:

Lager	Bor i	Scopat till	Laddat	Fråga det besvarar
AGENTS.md	Reporot	Projektet, vilken agent som helst	Varje session	Vad är den här platsen?
Verktygsdialekt (CLAUDE.md, rules)	Repo eller användarkonfig	Projektet, ett verktyg	Varje session	Vad ska det här verktyget göra här?
Skills	~/.claude/skills/ eller .claude/skills/	En agent, vilket projekt som helst	På begäran	Hur görs den här typen av uppgift?
MCP-servrar	Verktygskonfig	En maskin eller ett team	Verktygsdefinitioner alltid i kontexten	Vad kan agenten nå?

Läs den uppifrån och ner som vidgande förmåga och krympande portabilitet. Standardfilen är universell och dum. Dialekten är verktygsbunden och lite smartare. Skills är beteenderika men för närvarande agentbundna. MCP är levande infrastruktur med inloggningsuppgifter och processer.

Ett konkret exempel gör gränsen tydlig. "Kör pnpm test --filter=changed innan du committar" är en AGENTS.md-rad: det är ett faktum om ditt repo, sant för varje agent. "Vid felsökning, återskapa felet innan du föreslår en fix, och påstå aldrig att en fix fungerar utan att köra om det felande testet" är en skill, och faktiskt en vi testat och listat: systematic-debugging. Den har inget med något särskilt repo att göra. Att lägga den i AGENTS.md betyder att kopiera den till varje projekt och betala dess tokenkostnad i varje session, inklusive sessioner där ingen felsöker något.

Tumregeln vi ger team: om du skulle kopiera en rad till ett andra repo oförändrad är det inte projektkontext, det är beteende, och det hör hemma i en skill. Om en rad bara är meningsfull i det här repot är det kontext, och det hör hemma i AGENTS.md.

Strategin för team som kör flera AI-verktyg

De flesta team vi pratar med 2026 är inte enagent-verkstäder. En typisk mix är Claude Code för tyngre arbete, Copilot i editorn, och Cursor på några enstaka maskiner. Här är konfigurationen som överlever kontakt med det:

1. Skriv AGENTS.md som sanningskällan. En fil, i reporoten, ägd som kod. Lägg varje faktum som någon agent behöver in i den: kommandon, konventioner, gränser, varningar. Granska ändringar till den i PR:er, för en felaktig instruktion här missleder varje agent ditt team kör.

2. Håll dialekterna tunna. CLAUDE.md importerar AGENTS.md och lägger bara till Claude-specifika rader. Copilot-instructions och Cursor-rules får samma behandling: en pekare plus vad som genuint inte kan uttryckas i den delade filen. Vårt test för "tunn nog" är rakt på sak: om en dialektfil överstiger en skärm hör förmodligen något i den hemma i AGENTS.md eller i en skill.

3. Lägg återanvändbart beteende i skills. Felsökningsdisciplin, commit- och PR-vanor, teststandarder, dokumentformatering. Dessa hör inte hemma i någon per-repo-fil för de är inte per-repo. Installera dem en gång per agent och de följer med dig överallt. Våra testade val för kodningsarbete finns samlade i de bästa kodningsskillsen, och git-workflow är den vi skulle installera först för vilket team som helst som bryr sig om commit-hygien.

4. Efterlev med hooks och CI, inte prosa. Allt som måste hända 100 % av tiden kan inte bo i en markdown-fil läst av ett sannolikhetsbaserat system. Formatering vid spara är en hook. Tester före merge är CI. Markdown-lagren är för omdöme, inte efterlevnad.

Den här layouten har en egenskap värd att namnge: varje lager förändras i sin egen takt. AGENTS.md förändras när projektet förändras, skills förändras när ditt teams hantverk förändras, och ingen agent läser något adresserat till en annan agent.

Kommer en standard att vinna?

Vår bedömning, med standardbevakarhatten på: filnivån kommer att konvergera, och beteendelagret kommer inte att göra det.

Filnivån konvergerar för att incitamenten alla pekar åt samma håll. En kontextfil har låg angreppsyta, leverantörer vinner kompatibilitet för priset av en filnamnskontroll, och reporägare är synbart trötta på instruktionsfilssplittring. Vi förväntar oss inbyggt AGENTS.md-stöd i Claude Code så småningom, för trycket är offentligt och kostnaden för att stödja det är en fil-uppslagning. När det händer blir symlink-mönstret ovan en no-op du kan radera.

Beteendelagret är en annan historia. Skills-liknande mekanismer dyker upp överallt: Claudes skills, Cursors regelläge, Copilots prompt-filer, diverse "playbook"-funktioner över mindre agenter. De rimmar, men var och en kodar sin leverantörs egna idéer om triggering och scoping. En skills triggerbeskrivning och progressive loading mappar mot en Cursor-regel-glob ungefär som en symfoni mappar mot en ringsignal. Beteendeformat är där leverantörer differentierar sig, så de har all anledning att fortsätta divergera.

Och här är delen leverantörer inte lägger i lanseringsinlägg: portabilitet av format är inte portabilitet av kvalitet. En otestad beteendefil misslyckas på samma sätt på varje verktyg som laddar den. Den triggas när den inte borde, eller den triggas aldrig alls. Ungefär hälften av community-skills vi hämtar från GitHub misslyckas vårt första testpass, och felorsakerna är formatoberoende: vaga triggerbeskrivningar, och instruktioner författaren aldrig verifierade mot ett riktigt verktyg. Vi skrev om mönstret i varför hälften av Claude-skills inte fungerar, och allt i den gäller för vad din andra agent än kallar sin version av skills. En konvergerad standard skulle ge oss ett filnamn och samma gamla felfrekvens.

Så: standardisera dina fakta, för ekosystemet standardiserar med dig. Var sedan kräsen om dina beteenden, för ingen standardiserar kvalitet.

Vanliga frågor

Läser Claude Code AGENTS.md?

Inte inbyggt i mitten av 2026. Claude Code letar efter CLAUDE.md. Standardlösningarna är en symlink (ln -s AGENTS.md CLAUDE.md) eller en tunn CLAUDE.md som importerar den delade filen med @AGENTS.md. Båda fungerar; import-versionen ger dig också en plats för Claude-bara instruktioner.

Ska AGENTS.md ersätta min CLAUDE.md?

Ersätt dess innehåll, behåll filen. Flytta allt verktygsoberoende till AGENTS.md, krymp sedan CLAUDE.md till en import plus Claude-specifika rader om skills, hooks och behörigheter. Att radera CLAUDE.md helt är bara vettigt med symlink-metoden, där de två bokstavligen är samma bytes.

Kan jag lägga skill-liknande instruktioner i AGENTS.md istället för att installera skills?

Du kan, och för ett enda litet repo är det okej. Kostnaderna visar sig i skala: instruktionerna laddas i varje session oavsett relevans, och de följer inte med dig till andra projekt. Andra agenter som läser filen får också beteendevägledning skriven för Claude. Beteende du skulle återanvända över repos hör hemma i en skill.

Hur lång bör en AGENTS.md vara?

Kort nog att varje rad förtjänar sin kontextkostnad. De flesta bra vi granskat är 30 till 80 rader. Om din är flera hundra bär den förmodligen beteendeinnehåll som hör hemma i skills, eller referensmaterial som borde vara ett länkat dokument agenten läser på begäran.

Fungerar undermapps-AGENTS.md-filer?

Ja, konventionen stödjer nästling: filen närmast koden som redigeras vinner för det området. Monorepos använder detta för att ge paket sina egna bygg- och testkommandon. Behåll rotfilen för repo-omfattande fakta och skjut paketspecifika detaljer nedåt. Claude Code tillämpar samma närmaste-fil-logik på CLAUDE.md, så wrapper-mönstret nästlar snyggt också.