AGENTS.md vs CLAUDE.md vs skills: co kam patří

AGENTS.md je obyčejný markdown soubor v kořeni vašeho repozitáře, který agentům pro psaní kódu říká, jak mají ve vašem projektu pracovat: jak ho sestavit, jak spustit testy, jaké konvence dodržovat, čeho se nedotýkat. Žádné schéma, žádné povinné sekce, žádný registr. Celý standard se vejde do jedné věty: dejte do repozitáře soubor s názvem AGENTS.md a agenti, kteří tuto konvenci podporují, si ho přečtou dřív, než sáhnou na váš kód.

Lidé tomu říkají "README pro agenty" a to přirovnání sedí. README vysvětluje váš projekt lidem, kteří právě dorazili. AGENTS.md ho vysvětluje softwaru, který právě dorazil. Rozdíl je v tom, že agent instrukce skutečně dodrží, takže vágní pokyny stojí reálné peníze v podobě promarněných tokenů a špatných úprav.

V SkillProof testujeme nástroje pro agenty jako svou hlavní práci a sledovali jsme, jak se tento soubor proměnil z vedlejšího projektu OpenAI v to nejbližší, co agentní programování má ke sdílenému standardu. Tento článek se věnuje tomu, jak souvisí s CLAUDE.md a dalšími dialekty jednotlivých nástrojů, a kam zapadají skilly – protože ty řeší úplně jiný problém, než si většina lidí myslí.

Co AGENTS.md je a kdo si ho vlastně čte

Konvence vznikla v týmu Codexu od OpenAI v polovině roku 2025 a rychle ji podpořily Jules od Googlu, Cursor, Factory, Amp a další. Záměr byl jednoduchý: každý dodavatel agenta si vymyslel vlastní soubor s instrukcemi a kořeny repozitářů se plnily téměř identickým markdownem adresovaným různým robotům. AGENTS.md navrhl jeden název souboru, který čtou všichni.

Přijetí od té doby je reálné, ale nerovnoměrné. Tady je poctivá mapa stavu, jak ji vidíme v polovině roku 2026:

Nástroj	Čte AGENTS.md	Vlastní dialekt
OpenAI Codex	Ano, nativně	Žádný, AGENTS.md je jeho formát
GitHub Copilot (coding agent, VS Code)	Ano	.github/copilot-instructions.md
Cursor	Ano	.cursor/rules/*.mdc
Google Jules	Ano, nativně	Žádný
Gemini CLI	Ano, přes konfiguraci	GEMINI.md
Claude Code	Ne nativně	CLAUDE.md
Zed	Ano	Žádný
Amp	Ano	Žádný
Aider	Ne	CONVENTIONS.md
Windsurf	Ne	.windsurf/rules/

Z té tabulky vyplývají dvě věci. Za prvé, sloupec s odpověďmi "ano" je dlouhý a stále se prodlužuje; když v roce 2026 vyjde nový agent, podpora AGENTS.md bývá součástí poznámek k vydání. Za druhé, dialekty nikam nezmizely. Copilot si stále čte vlastní soubor s instrukcemi, Cursor má stále pravidla s globy a spouštěcími režimy, které AGENTS.md nedokáže vyjádřit, a Claude Code, nástroj, kterému věnujeme nejvíc času, stále chce CLAUDE.md.

Praktická situace je tedy taková: AGENTS.md je lingua franca, dialekty jsou tam, kde žije specifická síla jednotlivých nástrojů, a každý tým, který provozuje víc než jednoho agenta, potřebuje politiku, jak je udržet v souladu. Tato politika tvoří většinu tohoto článku.

Co do souboru patří, je méně sporné, než byl název souboru. Fungující soubory AGENTS.md pokrývají příkazy pro nastavení a sestavení, jak spouštět testy, poznámky ke stylu kódu, které linter neodhalí, a architektonické hranice ("logika plateb žije v packages/billing, jinam ji nedávejte"). Soubory, které nefungují, čtou se jako prohlášení o poslání. Agent nepotřebuje vědět, že si vážíte čistého kódu. Potřebuje příkaz, který ověří, jestli je kód čistý.

AGENTS.md vs CLAUDE.md

Tyto dva soubory dělají téměř stejnou práci pro různé čtenáře. Oba jsou instrukční soubory na úrovni projektu. Oba se načítají do kontextu na začátku session. Oba by měly být krátké, protože každý řádek stojí tokeny při každém požadavku. Pokud už máte napsaný dobrý CLAUDE.md, už víte, jak napsat dobrý AGENTS.md, a naše rady z článku Osvědčené postupy pro CLAUDE.md se dají přenést téměř řádek po řádku.

Rozdíly stojí za to znát dřív, než je sjednotíte:

Publikum. CLAUDE.md čte přesně jeden nástroj. To znamená, že může bezpečně odkazovat na mechanismy specifické pro Claude: skilly, hooky, subagenty, MCP servery, nastavení oprávnění. AGENTS.md, který říká "před navržením opravy použijte skill systematic-debugging", je pro Codex a Copilot jen šum – ty netuší, co je to skill.

Hierarchie a importy. Claude Code slučuje soubory CLAUDE.md z několika úrovní (globální uživatelská, kořen projektu, podadresáře) a podporuje v nich importy @cesta/k/souboru. AGENTS.md také podporuje zanořování, kdy vyhrává nejbližší soubor, ale syntaxe importů patří Claude.

Vynucení. Ani jeden soubor se nevynucuje. Oba jsou pouze doporučení pro jazykový model. Cokoliv, co se musí stát vždy, patří do hooku nebo CI, ne do žádného z těchto souborů. To zklame lidi stejnou měrou napříč všemi nástroji.

Pokud váš tým používá vedle Claude Code i něco jiného, potřebujete oba soubory, a selhání je zřejmé: dva soubory říkají téměř totéž, postupně se rozcházejí, až agent nakonec sleduje ten zastaralý. Tomu předchází dva vzory, oba jsme otestovali.

Symlink. Udělejte z AGENTS.md skutečný soubor a nechte CLAUDE.md na něj ukazovat:

# AGENTS.md je jediný zdroj pravdy
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code symlink sleduje a obsah čte, jako by šlo o vlastní soubor. Tohle je bezúdržbová varianta a je správná ve chvíli, kdy nemáte nic specifického pro Claude, co byste chtěli říct navíc. Jejím limitem je přesná identita: oba čtenáři dostanou úplně každé slovo, včetně těch relevantních jen pro toho druhého.

Tenký wrapper. Nechte AGENTS.md jako sdílený zdroj a udělejte z CLAUDE.md malý soubor, který ho importuje a přidává řádky jen pro Claude:

# CLAUDE.md
@AGENTS.md

## Specifické pro Claude
- Pro commity a PR použijte skill git-workflow.
- Nikdy needitujte soubory pod infra/ bez zeptání.

Tohle provozujeme ve vlastních repozitářích. Sdílená fakta žijí jen jednou, extra věci pro Claude žijí tam, kde je uvidí jen Claude, a diff v AGENTS.md aktualizuje všechny nástroje ve stejném okamžiku. Stejný tvar funguje obráceně i pro jiné dialekty: udržujte .github/copilot-instructions.md a soubory s pravidly Cursoru na pár řádcích, které pro vše sdílené odkazují na AGENTS.md. Tyto dialekty jsme podrobně porovnali v článcích Claude skilly vs pravidla Cursoru a Claude skilly vs instrukce Copilotu.

Jedno varování z našeho testování: ať zvolíte jakýkoliv vzor, zvolte jen jeden. Repozitáře, které nesou plnohodnotný CLAUDE.md i plnohodnotný AGENTS.md s nezávisle editovaným obsahem, jsou scénář rozcházení s extra kroky navíc.

AGENTS.md vs skilly: úplně jiné vrstvy

Tohle je srovnání, které lidé opravdu hledají, a zároveň je postavené na kategoriální chybě. AGENTS.md a skilly spolu nesoutěží jako formáty. Sedí na různých vrstvách zásobníku a odpovídají na různé otázky.

AGENTS.md odpovídá na otázku: co by měl o tomto projektu vědět jakýkoliv agent? Jsou to fakta o místě. Cestují spolu s repozitářem, platí pro jakéhokoliv agenta, který se objeví, a o tom, jak agent svou práci dělá, neříkají nic kromě lokálních pravidel.

Skill odpovídá na otázku: jak by tento agent měl vykonávat tento druh úkolu? Je to chování zabalené ve složce se souborem SKILL.md, které se načítá na vyžádání ve chvíli, kdy úkol odpovídá jeho popisu. Cestuje s vámi, ne s repozitářem. Nainstalujte si debugovací skill jednou a bude fungovat v každém projektu, který otevřete, ať už o vás ten projekt někdy slyšel, nebo ne. Mechaniku jsme popsali v článku Co jsou Claude skilly?, ale klíčový rozdíl je v modelu načítání: obsah AGENTS.md sedí v kontextu po celou session, zatímco skill stojí zhruba stovku tokenů metadat až do chvíle, kdy ho spustí odpovídající úkol.

Tady je celý zásobník tak, jak ho kreslíme na tabuli:

Vrstva	Žije v	Platí pro	Načítání	Otázka, na kterou odpovídá
AGENTS.md	Kořen repozitáře	Projekt, jakýkoliv agent	Každou session	Co je tohle za místo?
Dialekt nástroje (CLAUDE.md, pravidla)	Repozitář nebo konfigurace uživatele	Projekt, jeden nástroj	Každou session	Co má tento nástroj tady dělat?
Skilly	~/.claude/skills/ nebo .claude/skills/	Jeden agent, jakýkoliv projekt	Na vyžádání	Jak se dělá tento druh úkolu?
MCP servery	Konfigurace nástroje	Jeden stroj nebo tým	Definice nástrojů vždy v kontextu	Kam agent může dosáhnout?

Čtěte to odshora dolů jako rostoucí schopnosti a klesající přenositelnost. Standardní soubor je univerzální a hloupý. Dialekt je vázaný na nástroj a o něco chytřejší. Skilly jsou bohaté na chování, ale zatím vázané na agenta. MCP je živá infrastruktura s přihlašovacími údaji a procesy.

Konkrétní příklad tu hranici udělá zřejmou. "Před commitem spusťte pnpm test --filter=changed" je řádek pro AGENTS.md: je to fakt o vašem repozitáři, platný pro každého agenta. "Při debugování nejdřív reprodukujte selhání, než navrhnete opravu, a nikdy netvrďte, že oprava funguje, aniž byste znovu spustili neúspěšný test" je skill, a je to dokonce jeden z těch, které jsme otestovali a zařadili do seznamu: systematic-debugging. Nemá to nic společného s žádným konkrétním repozitářem. Dát to do AGENTS.md znamená kopírovat to do každého projektu a platit jeho tokenovou cenu v každé session, včetně sessions, kde zrovna nikdo nic neladí.

Pravidlo, které dáváme týmům: pokud byste řádek zkopírovali beze změny do druhého repozitáře, není to kontext projektu, je to chování a patří do skillu. Pokud řádek dává smysl jen v tomto repozitáři, je to kontext a patří do AGENTS.md.

Strategie pro týmy provozující víc AI nástrojů

Většina týmů, se kterými mluvíme v roce 2026, nejsou dílny s jedním agentem. Typický mix je Claude Code na náročnější práci, Copilot v editoru a Cursor na strojích pár jednotlivců. Tady je konfigurace, která přežije kontakt s realitou:

1. Napište AGENTS.md jako jediný zdroj pravdy. Jeden soubor v kořeni repozitáře, spravovaný jako kód. Vložte do něj každé fakto, které potřebuje jakýkoliv agent: příkazy, konvence, hranice, varování. Změny v něm procházejte přes PR review, protože špatná instrukce tady zmate každého agenta, kterého váš tým provozuje.

2. Udržujte dialekty tenké. CLAUDE.md importuje AGENTS.md a přidává jen řádky specifické pro Claude. Instrukce Copilotu a pravidla Cursoru dostávají stejné zacházení: odkaz plus cokoliv, co se opravdu nedá vyjádřit ve sdíleném souboru. Náš test "dost tenký" je přímočarý: pokud soubor dialektu přesáhne jednu obrazovku, něco v něm asi patří do AGENTS.md nebo do skillu.

3. Znovupoužitelné chování dávejte do skillů. Disciplína při debugování, zvyky pro commity a PR, standardy psaní testů, formátování dokumentů. Tyhle věci nepatří do žádného souboru na úrovni repozitáře, protože nejsou vázané na repozitář. Nainstalujte je jednou na agenta a budou vás následovat všude. Naše otestované tipy pro práci s kódem jsou shromážděné v článku nejlepší skilly pro programování a git-workflow je ten, který bychom jako první nainstalovali každému týmu, kterému záleží na hygieně commitů.

4. Vynucujte pomocí hooků a CI, ne prózou. Cokoliv, co se musí stát stoprocentně vždy, nemůže žít v markdown souboru, který čte pravděpodobnostní systém. Formátování při uložení je hook. Testy před mergem jsou CI. Markdownové vrstvy jsou pro úsudek, ne pro vynucování.

Tenhle layout má vlastnost, kterou stojí za to pojmenovat: každá vrstva se mění svým vlastním tempem. AGENTS.md se mění, když se mění projekt, skilly se mění, když se mění řemeslo vašeho týmu, a žádný agent nečte nic adresované jinému agentovi.

Zvítězí jeden standard?

Náš názor, v roli pozorovatele standardů: souborová konvence konverguje, vrstva chování ne.

Souborová vrstva konverguje, protože pobídky míří všechny jedním směrem. Kontextový soubor má malou plochu dopadu, dodavatelé získávají kompatibilitu za cenu jedné kontroly názvu souboru a vlastníci repozitářů jsou viditelně unavení z bujení instrukčních souborů. Nativní podporu AGENTS.md v Claude Code nakonec čekáme, protože tlak je veřejný a náklad na jeho podporu je jedno vyhledání souboru. Až se to stane, výše popsaný vzor se symlinkem se stane no-opem, který můžete smazat.

Vrstva chování je jiný příběh. Mechanismy podobné skillům se objevují všude: skilly Claude, režimy pravidel Cursoru, prompt soubory Copilotu, různé funkce typu "playbook" napříč menšími agenty. Rýmují se, ale každý zakódovává vlastní představy svého dodavatele o spouštění a rozsahu. Spouštěcí popis skillu a progresivní načítání se na glob pravidla Cursoru mapují asi tak dobře, jako se symfonie mapuje na vyzváněcí tón. Formáty chování jsou tam, kde se dodavatelé odlišují, takže mají každý důvod dál se rozcházet.

A tady je část, kterou dodavatelé nedávají do launchových příspěvků: přenositelnost formátu není přenositelnost kvality. Netestovaný soubor s chováním selhává stejně na každém nástroji, který ho načte. Spustí se, když by neměl, nebo se nespustí vůbec. Zhruba polovina komunitních skillů, které stahujeme z GitHubu, neprojde naším prvním testovacím kolem, a příčiny selhání jsou nezávislé na formátu: vágní popisy spouštění a instrukce, které autor nikdy neověřil na skutečném nástroji. Tenhle vzorec jsme popsali v článku proč polovina Claude skillů nefunguje a všechno v něm platí i pro to, jak svojí verzi skillů nazývá váš jiný agent. Sjednocený standard by nám dal jeden název souboru a stejnou starou míru chybovosti.

Takže: standardizujte svá fakta, protože ekosystém se standardizuje s vámi. A pak buďte vybíraví ohledně svého chování, protože kvalitu nikdo nestandardizuje.

FAQ

Čte Claude Code AGENTS.md?

Ne nativně, aspoň ne v polovině roku 2026. Claude Code hledá CLAUDE.md. Standardní řešení jsou symlink (ln -s AGENTS.md CLAUDE.md) nebo tenký CLAUDE.md, který importuje sdílený soubor pomocí @AGENTS.md. Obě fungují; varianta s importem vám navíc dává místo pro instrukce jen pro Claude.

Měl by AGENTS.md nahradit můj CLAUDE.md?

Nahraďte jeho obsah, soubor si nechte. Přesuňte vše, co je nezávislé na nástroji, do AGENTS.md, pak CLAUDE.md zmenšete na import plus řádky specifické pro Claude o skillech, hoocích a oprávněních. Úplné smazání CLAUDE.md dává smysl jen u přístupu se symlinkem, kde jsou oba soubory doslova stejné bajty.

Můžu do AGENTS.md dát instrukce podobné skillům místo instalace skillů?

Můžete, a pro jeden malý repozitář je to v pořádku. Náklady se projeví ve velkém měřítku: instrukce se načítají v každé session bez ohledu na relevanci a nenásledují vás do dalších projektů. Ostatní agenti, kteří soubor čtou, navíc dostanou pokyny pro chování napsané pro Claude. Chování, které byste chtěli znovu použít napříč repozitáři, patří do skillu.

Jak dlouhý by měl AGENTS.md být?

Dost krátký na to, aby si každý řádek zasloužil svou cenu v kontextu. Většina dobrých souborů, které jsme viděli, má 30 až 80 řádků. Pokud má váš několik set řádků, pravděpodobně nese obsah týkající se chování, který patří do skillů, nebo referenční materiál, který by měl být propojený dokument, jenž si agent přečte na vyžádání.

Fungují soubory AGENTS.md v podadresářích?

Ano, konvence podporuje zanořování: soubor nejblíž upravovanému kódu vyhrává pro danou oblast. Monorepa tohle využívají k tomu, aby daly balíčkům vlastní příkazy pro sestavení a testy. Kořenový soubor si nechte na fakta platná pro celý repozitář a specifika balíčků posouvejte níž. Claude Code aplikuje stejnou logiku nejbližšího souboru i na CLAUDE.md, takže se čistě zanořuje i vzor s wrapperem.