AGENTS.md vs CLAUDE.md vs skille: co gdzie

AGENTS.md to zwykły plik markdown w katalogu głównym twojego repozytorium, który mówi agentom kodującym, jak pracować w twoim projekcie: jak go zbudować, jak uruchomić testy, jakich konwencji przestrzegać, czego nie dotykać. Żadnego schematu, żadnych wymaganych sekcji, żadnego rejestru. Cały standard mieści się w jednym zdaniu: umieść plik o nazwie AGENTS.md w swoim repo, a agenci wspierający tę konwencję przeczytają go, zanim dotkną twojego kodu.

Ludzie nazywają go „README dla agentów", i ta analogia się broni. README wyjaśnia twój projekt ludziom, którzy właśnie przyszli. AGENTS.md wyjaśnia go oprogramowaniu, które właśnie przyszło. Różnica polega na tym, że agent faktycznie zastosuje się do instrukcji, więc niejasne kosztują realne pieniądze w zmarnowanych tokenach i błędnych edycjach.

Testujemy narzędzia agentowe na co dzień w SkillProof, i widzieliśmy, jak ten plik przeszedł z projektu pobocznego OpenAI do najbliższej rzeczy, jaką kodowanie agentowe ma do wspólnego standardu. Ten wpis omawia, jak odnosi się do CLAUDE.md i innych dialektów narzędzi, oraz gdzie pasują skille, bo rozwiązują inny problem, niż większość ludzi zakłada.

Czym jest AGENTS.md i kto naprawdę go czyta

Konwencja wyszła z zespołu Codex OpenAI w połowie 2025 roku i szybko została współpodpisana przez Jules Google, Cursor, Factory, Amp i innych. Pomysł był prosty: każdy dostawca agentów wymyślił własny plik instrukcji, a katalogi główne repozytoriów zapełniały się niemal identycznym markdownem adresowanym do różnych robotów. AGENTS.md zaproponował jedną nazwę pliku, którą wszyscy czytają.

Adopcja od tamtej pory jest realna, ale nierówna. Oto uczciwa mapa, jak ją widzimy w połowie 2026:

Narzędzie	Czyta AGENTS.md	Natywny dialekt
OpenAI Codex	Tak, natywnie	Żaden, AGENTS.md to format
GitHub Copilot (agent kodujący, VS Code)	Tak	.github/copilot-instructions.md
Cursor	Tak	.cursor/rules/*.mdc
Google Jules	Tak, natywnie	Żaden
Gemini CLI	Tak, przez konfigurację	GEMINI.md
Claude Code	Nie natywnie	CLAUDE.md
Zed	Tak	Żaden
Amp	Tak	Żaden
Aider	Nie	CONVENTIONS.md
Windsurf	Nie	.windsurf/rules/

Dwie rzeczy wyróżniają się w tej tabeli. Po pierwsze, kolumna odpowiedzi „tak" jest długa i wciąż rośnie; kiedy w 2026 startuje nowy agent, wsparcie AGENTS.md zwykle jest w notatkach o wydaniu. Po drugie, dialekty nigdzie nie zniknęły. Copilot wciąż czyta swój własny plik instrukcji, Cursor wciąż ma reguły z globami i trybami wyzwalania, których AGENTS.md nie potrafi wyrazić, a Claude Code, narzędzie, z którym spędzamy najwięcej czasu, wciąż chce CLAUDE.md.

Więc praktyczna sytuacja jest taka: AGENTS.md to lingua franca, dialekty to miejsce, gdzie żyje moc specyficzna dla narzędzia, a każdy zespół uruchamiający więcej niż jednego agenta potrzebuje polityki utrzymywania ich w synchronizacji. Ta polityka to większość tego artykułu.

To, co idzie do pliku, jest mniej sporne, niż była nazwa. Pliki AGENTS.md, które działają, obejmują komendy konfiguracji i budowania, jak uruchamiać testy, uwagi o stylu kodu, których linter nie wyłapie, i granice architektoniczne („logika płatności żyje w packages/billing, nie wkładaj jej nigdzie indziej"). Pliki, które nie działają, czytają się jak deklaracje misji. Agent nie musi wiedzieć, że cenisz czysty kod. Potrzebuje komendy, która sprawdza, czy kod jest czysty.

AGENTS.md vs CLAUDE.md

Te dwa pliki wykonują niemal tę samą pracę dla różnych czytelników. Oba to pliki instrukcji na poziomie projektu. Oba ładują się do kontekstu na początku sesji. Oba powinny być krótkie, bo każda linia kosztuje tokeny przy każdym żądaniu. Jeśli już napisałeś dobry CLAUDE.md, już wiesz, jak napisać dobry AGENTS.md, a nasze porady w dobrych praktykach CLAUDE.md przenoszą się niemal linia po linii.

Różnice warto znać, zanim je zunifikujesz:

Odbiorca. CLAUDE.md czyta dokładnie jedno narzędzie. To oznacza, że może bezpiecznie odwoływać się do maszynerii specyficznej dla Claude: skilli, hooków, subagentów, serwerów MCP, ustawień uprawnień. AGENTS.md mówiący „użyj skilla systematic-debugging przed zaproponowaniem poprawki" to szum dla Codexa i Copilota, które nie mają pojęcia, czym jest skill.

Hierarchia i importy. Claude Code łączy pliki CLAUDE.md z kilku poziomów (globalny użytkownika, katalog główny projektu, podkatalogi) i wspiera importy @path/to/file wewnątrz nich. AGENTS.md też wspiera zagnieżdżanie, z pierwszeństwem najbliższego pliku, ale składnia importu jest własnością Claude.

Egzekwowanie. Żaden plik nie jest egzekwowany. Oba to sugestie dla modelu językowego. Wszystko, co musi się dziać za każdym razem, należy do hooka albo CI, nie do żadnego z tych plików. To rozczarowuje ludzi jednakowo we wszystkich narzędziach.

Jeśli twój zespół używa Claude Code obok czegoś jeszcze, potrzebujesz obu plików, a tryb awarii jest oczywisty: dwa pliki mówiące niemal to samo, rozjeżdżające się, aż agent podąża za nieaktualnym. Dwa wzorce temu zapobiegają, i przetestowaliśmy oba.

Symlink. Zrób z AGENTS.md prawdziwy plik i niech CLAUDE.md na niego wskazuje:

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

Claude Code podąża za symlinkiem i czyta zawartość, jakby była jego własnym plikiem. To opcja zero-utrzymania, i jest właściwa, gdy nie masz nic specyficznego dla Claude do powiedzenia. Jej ograniczeniem jest dokładna tożsamość: obaj czytelnicy dostają każde słowo, w tym te istotne tylko dla drugiego.

Cienki wrapper. Trzymaj AGENTS.md jako wspólne źródło, a CLAUDE.md zrób małym plikiem, który je importuje i dodaje linie tylko dla Claude:

# CLAUDE.md
@AGENTS.md

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

To uruchamiamy w naszych własnych repo. Wspólne fakty żyją raz, dodatki dla Claude żyją tam, gdzie tylko Claude je zobaczy, a diff do AGENTS.md aktualizuje każde narzędzie w tym samym momencie. Ten sam kształt działa odwrotnie dla innych dialektów: trzymaj .github/copilot-instructions.md i pliki reguł Cursora w kilku liniach, które odsyłają do AGENTS.md dla wszystkiego, czego potrzebują oba narzędzia. Porównaliśmy te dialekty szczegółowo w skille Claude vs reguły Cursora i skille Claude vs instrukcje Copilota.

Jedno ostrzeżenie z naszych testów: który wzorzec byś nie wybrał, wybierz jeden. Repo noszące pełny CLAUDE.md i pełny AGENTS.md z niezależnie edytowaną zawartością to scenariusz rozjazdu z dodatkowymi krokami.

AGENTS.md vs skille: zupełnie inne warstwy

To porównanie, którego ludzie faktycznie szukają, i to takie zbudowane na błędzie kategorii. AGENTS.md i skille nie konkurują ze sobą jako formaty. Siedzą na różnych warstwach stosu i odpowiadają na różne pytania.

AGENTS.md odpowiada: co jakikolwiek agent powinien wiedzieć o tym projekcie? To fakty o miejscu. Podróżuje z repozytorium, stosuje się do tego, który agent się pojawi, i nic nie mówi o tym, jak agent wykonuje swoją pracę poza lokalnymi regułami.

Skill odpowiada: jak ten agent powinien wykonać ten rodzaj zadania? To zachowanie, zapakowane w folder z SKILL.md, ładowane na żądanie, gdy zadanie pasuje do jego opisu. Podróżuje z tobą, nie z repo. Zainstaluj skill do debugowania raz, a działa w każdym projekcie, który otworzysz, niezależnie od tego, czy ten projekt kiedykolwiek o tobie słyszał. Omówiliśmy mechanikę w czym są skille Claude?, ale model ładowania to kluczowa różnica: zawartość AGENTS.md siedzi w kontekście przez całą sesję, podczas gdy skill kosztuje około stu tokenów metadanych do momentu, gdy zadanie go wyzwoli.

Oto pełny stos, jak rysujemy go na tablicach:

Warstwa	Żyje w	Zasięg	Ładowana	Pytanie, na które odpowiada
AGENTS.md	Katalog główny repo	Projekt, każdy agent	Każda sesja	Co to za miejsce?
Dialekt narzędzia (CLAUDE.md, reguły)	Repo albo konfiguracja użytkownika	Projekt, jedno narzędzie	Każda sesja	Co to narzędzie powinno tu robić?
Skille	~/.claude/skills/ albo .claude/skills/	Jeden agent, dowolny projekt	Na żądanie	Jak wykonuje się ten rodzaj zadania?
Serwery MCP	Konfiguracja narzędzia	Jedna maszyna albo zespół	Definicje narzędzi zawsze w kontekście	Do czego agent może sięgnąć?

Czytaj to od góry do dołu jako rozszerzającą się zdolność i zwężającą przenośność. Standardowy plik jest uniwersalny i głupi. Dialekt jest przywiązany do narzędzia i nieco mądrzejszy. Skille są bogate w zachowanie, ale obecnie przywiązane do agenta. MCP to żywa infrastruktura z danymi uwierzytelniającymi i procesami.

Konkretny przykład czyni granicę oczywistą. „Uruchom pnpm test --filter=changed przed commitem" to linia AGENTS.md: to fakt o twoim repo, prawdziwy dla każdego agenta. „Podczas debugowania odtwórz awarię przed zaproponowaniem poprawki, i nigdy nie twierdź, że poprawka działa bez ponownego uruchomienia nieudanego testu" to skill, i w rzeczywistości jest jednym, który przetestowaliśmy i wpisaliśmy na listę: systematic-debugging. Nie ma nic wspólnego z żadnym konkretnym repo. Umieszczenie tego w AGENTS.md oznacza kopiowanie do każdego projektu i płacenie jego kosztu tokenowego w każdej sesji, w tym sesjach, gdzie nikt nic nie debuguje.

Zasada, którą dajemy zespołom: jeśli skopiowałbyś linię do drugiego repo bez zmian, to nie jest kontekst projektu, to zachowanie, i należy do skilla. Jeśli linia ma sens tylko w tym repo, to kontekst, i należy do AGENTS.md.

Strategia dla zespołów uruchamiających wiele narzędzi AI

Większość zespołów, z którymi rozmawiamy w 2026 roku, to nie firmy jednego agenta. Typowy mix to Claude Code do cięższej pracy, Copilot w edytorze, i Cursor na kilku maszynach opornych. Oto konfiguracja, która przetrwa kontakt z tym:

1. Napisz AGENTS.md jako źródło prawdy. Jeden plik, w katalogu głównym repo, posiadany jak kod. Umieść w nim każdy fakt, którego potrzebuje jakikolwiek agent: komendy, konwencje, granice, ostrzeżenia. Recenzuj zmiany w pull requestach, bo błędna instrukcja tutaj wprowadza w błąd każdego agenta twojego zespołu.

2. Trzymaj dialekty cienkie. CLAUDE.md importuje AGENTS.md i dodaje tylko linie specyficzne dla Claude. Instrukcje Copilota i reguły Cursora dostają to samo traktowanie: wskaźnik plus wszystko, czego naprawdę nie da się wyrazić we wspólnym pliku. Nasz test na „wystarczająco cienki" jest bezpośredni: jeśli plik dialektu przekracza jeden ekran, coś w nim prawdopodobnie należy do AGENTS.md albo do skilla.

3. Umieść wielokrotnego użytku zachowanie w skillach. Dyscyplina debugowania, nawyki commitów i PR-ów, standardy pisania testów, formatowanie dokumentów. Te nie należą do żadnego pliku per-repo, bo nie są per-repo. Zainstaluj je raz na agenta, a podążą za tobą wszędzie. Nasze przetestowane wybory do pracy programistycznej są zebrane w najlepszych skillach programistycznych, a git-workflow to ten, który zainstalowalibyśmy pierwszy w każdym zespole dbającym o higienę commitów.

4. Egzekwuj hookami i CI, nie prozą. Wszystko, co musi się dziać w 100% przypadków, nie może żyć w pliku markdown czytanym przez system probabilistyczny. Formatowanie przy zapisie to hook. Testy przed merge'em to CI. Warstwy markdown są do osądu, nie do egzekwowania.

Ten układ ma właściwość wartą nazwania: każda warstwa zmienia się w swoim tempie. AGENTS.md zmienia się, gdy zmienia się projekt, skille zmieniają się, gdy zmienia się rzemiosło twojego zespołu, a żaden agent nie czyta niczego adresowanego do innego agenta.

Czy jeden standard wygra?

Nasze zdanie, w kapeluszu obserwatora standardów: warstwa plikowa się zbiegnie, a warstwa zachowania nie.

Warstwa plikowa zbiega się, bo wszystkie zachęty wskazują w jedną stronę. Plik kontekstu ma małą powierzchnię, dostawcy zyskują kompatybilność za cenę jednego sprawdzenia nazwy pliku, a właściciele repo są widocznie zmęczeni chaosem plików instrukcji. Spodziewamy się natywnego wsparcia AGENTS.md w Claude Code w końcu, bo presja jest publiczna, a koszt wsparcia to jedno wyszukanie pliku. Kiedy to się stanie, wzorzec symlinku powyżej stanie się operacją zerową, którą będzie można usunąć.

Warstwa zachowania to inna historia. Mechanizmy podobne do skilli pojawiają się wszędzie: skille Claude, tryby reguł Cursora, pliki promptów Copilota, różne funkcje „playbook" w mniejszych agentach. Rymują się, ale każdy koduje własne pomysły dostawcy o wyzwalaniu i zasięgu. Opis wyzwalacza skilla i progresywne ładowanie mapują się na glob reguły Cursora mniej więcej tak, jak symfonia mapuje się na dzwonek. Formaty zachowania to miejsce, gdzie dostawcy się różnicują, więc mają wszelkie powody, żeby dalej się rozjeżdżać.

I oto część, której dostawcy nie umieszczają w postach o starcie: przenośność formatu to nie przenośność jakości. Nieprzetestowany plik zachowania zawodzi tak samo na każdym narzędziu, które go ładuje. Wyzwala się, kiedy nie powinien, albo nigdy się nie wyzwala. Mniej więcej połowa skilli społecznościowych, które ściągamy z GitHuba, zawodzi nasz pierwszy przebieg testów, a przyczyny awarii są niezależne od formatu: niejasne opisy wyzwalaczy, i instrukcje, których autor nigdy nie zweryfikował na prawdziwym narzędziu. Opisaliśmy ten wzorzec w dlaczego połowa skilli Claude nie działa, i wszystko w nim stosuje się do tego, co twój inny agent nazywa swoją wersją skilli. Zbieżny standard dałby nam jedną nazwę pliku i ten sam stary wskaźnik wad.

Więc: standaryzuj swoje fakty, bo ekosystem standaryzuje się razem z tobą. Potem bądź wybredny co do swoich zachowań, bo nikt nie standaryzuje jakości.

FAQ

Czy Claude Code czyta AGENTS.md?

Nie natywnie w połowie 2026 roku. Claude Code szuka CLAUDE.md. Standardowe obejścia to symlink (ln -s AGENTS.md CLAUDE.md) albo cienki CLAUDE.md, który importuje wspólny plik przez @AGENTS.md. Oba działają; wersja z importem daje ci też miejsce na instrukcje tylko dla Claude.

Czy AGENTS.md powinien zastąpić mój CLAUDE.md?

Zastąp jego treść, zachowaj plik. Przenieś wszystko niezależne od narzędzia do AGENTS.md, potem zmniejsz CLAUDE.md do importu plus linii specyficznych dla Claude o skillach, hookach i uprawnieniach. Usunięcie CLAUDE.md całkowicie ma sens tylko przy podejściu z symlinkiem, gdzie oba są dosłownie tymi samymi bajtami.

Czy mogę umieścić instrukcje podobne do skilli w AGENTS.md zamiast instalować skille?

Możesz, i dla jednego małego repo to w porządku. Koszty pojawiają się w skali: instrukcje ładują się w każdej sesji, niezależnie od tego, czy są istotne, i nie podążają za tobą do innych projektów. Inni agenci czytający ten plik też dostają wskazówki dotyczące zachowania napisane dla Claude. Zachowanie, którego użyłbyś ponownie w wielu repo, należy do skilla.

Jak długi powinien być AGENTS.md?

Wystarczająco krótki, żeby każda linia zarabiała na swój koszt kontekstu. Większość dobrych, które recenzowaliśmy, ma od 30 do 80 linii. Jeśli twój ma kilkaset, prawdopodobnie niesie treść zachowania, która należy do skilli, albo materiał referencyjny, który powinien być powiązanym dokumentem czytanym przez agenta na żądanie.

Czy działają pliki AGENTS.md w podkatalogach?

Tak, konwencja wspiera zagnieżdżanie: plik najbliższy edytowanemu kodowi wygrywa dla tego obszaru. Monorepo używają tego, żeby dać pakietom własne komendy budowania i testowania. Zachowaj plik główny dla faktów całego repo i przesuń specyfikę pakietów w dół. Claude Code stosuje tę samą logikę najbliższego pliku do CLAUDE.md, więc wzorzec wrappera też zagnieżdża się czysto.