CLAUDE.md vs AGENTS.md vs SKILL.md: Co trafia gdzie i dlaczego

Każdy, kto zaczyna używać Claude Code, ma tendencję do tworzenia pliku CLAUDE.md i wkładania do niego wszystkiego: ustawień projektu, zasad programowania, zasad korzystania z pull requestów, szczegółów technologicznych oraz notatek wprowadzających. Następnie do gry wchodzi AGENTS.md, a potem SKILL.md – wygląda to jak trzy pliki do tego samego zadania. Tak nie jest. Ich mylne łączenie oznacza konieczność płacenia za tokeny, które nic dla ciebie nie robią.

Szybki model mentalny

Wyobraź sobie firmę. CLAUDE.md to podręcznik pracownika, który każdy nowy pracownik czyta już pierwszego dnia, zawsze w tle. AGENTS.md to ten sam podręcznik, napisany tak, by mogli go śledzić również zewnętrzni kontrahenci z dowolnej agencji, a nie tylko stały personel. SKILL.md to podręcznik leżący na półce, który zabierasz tylko wtedy, gdy wykonujesz konkretną zadanie. Trzy pliki, trzy zadania i trzy sposoby ładowania.

CLAUDE.md: zawsze ładowany

To główny plik konfiguracyjny Claude Code. Podczas rozpoczynania sesji Claude go czyta i przechowuje w swoim systemowym promptzie. Jest ładowany raz, staje się częścią kontekstu używanego przez całą sesję i nie musi być pobierany z dysku przy każdej wiadomości. Dlatego gdy wpiszesz powitanie, te instrukcje są już obecne, a ponownie pojawią się, gdy później poprosisz o naprawę błędu.

Skutkiem tego jest to, że duży plik trwale zajmuje część okna kontekstowego, nawet przy zadaniach, w których większość jego treści jest nieistotna. Dlatego warto korzystać z skoncentrowanego, krótkiego pliku.

Trzy poziomy

Instrukcje pochodzą z kilku źródeł i są łączone:

1. Osobisty plik w lokalizacji ~/.claude/CLAUDE.md, zawierający preferencje stosowane we wszystkich projektach, takie jak styl wcięć lub standardy komunikatów przy komitach. Członkowie zespołu nigdy go nie widzą.

Plik projektu, albo .claude/CLAUDE.md, albo taki znajdujący się w korzeniu repozytorium. Jest on zapisywany w Git, więc wszyscy, którzy klonują repozytorium, otrzymują te same zasady. Tutaj znajdują się szczegóły dotyczące stosu technologicznego, polecenia oraz standardy zespołu.

Zasady specyficzne dla danej ścieżki, przechowywane pod .claude/rules/ wraz z ustawieniem paths w frontmatterze. Na przykład plik z zasadami testowania może być ładowany tylko podczas edycji plików testowych, co zapobiega pojawianiu się nieistotnych wskazówek w tym kontekście.

Bardziej szczegółowe wskazówki dotyczące projektu są ładowane po ogólniejszych instrukcjach na poziomie użytkownika, więc gdy występuje konflikt, wersja projektu może mieć pierwszeństwo. Praktyczna zasada: osobiste preferencje trafiają do pliku konfiguracyjnego użytkownika, natomiast wspólne standardy zespołu – do pliku projektu.

Co powinno się tam znajdować

Niech będzie krótko. Rozsądnym celem jest utrzymanie tekstu poniżej 200 wierszy, choć to jedynie wytyczna, a nie sztywny limit. Włącz tylko to, czego Claude potrzebuje do wykonania każdego zadania: stack technologiczny, polecenia służące do uruchamiania testów i serwera deweloperskiego, bezwzględne zasady, takie jak nigdy nie rejestrowanie danych użytkowników, oraz główne decyzje architektoniczne.

Pomijaj wszystko, co jest specyficzne dla danego zadania. Długi przewodnik dotyczący sprawdzania PR-ów lub katalog przypadków granicznych znajdą lepsze miejsce, o którym mowa poniżej.

Uwaga

Jeśli edytujesz plik CLAUDE.md w trakcie sesji, bieżąca sesja tego nie zauważy. Plik został przeczytany raz na początku, więc aby zmiany weszły w życie, konieczna jest nowa sesja. To najczęstszy powód, dla którego świeżo dodana zasada wydaje się ignorowana.

AGENTS.md: dla zespołów używających kilku narzędzi

AGENTS.md służy temu samemu celowi – przechowuje kontekst projektu oraz instrukcje. Różnica polega na tym, kto może go czytać. Claude Code czyta CLAUDE.md, natomiast OpenAI Codex, Cursor, Gemini CLI i GitHub Copilot czytają AGENTS.md.

Zgodnie z opisem, Claude Code nie potrafi automatycznie odczytać AGENTS.md, ale symlink rozwiązuje ten problem, kierując oba nazwy do tego samego pliku (sprawdź aktualne dokumentację na wypadek zmian w obsłudze):

ln -s AGENTS.md CLAUDE.md

Teraz istnieje jeden plik, który czyta każde narzędzie i nic się nie rozchodzi w różne strony.

Kiedy jest to potrzebne

Jeśli cały zespół używa tylko Claude Code, wystarczy plik CLAUDE.md. Jeśli ludzie korzystają z różnych narzędzi lub jeśli CI uruchamia inny agent niż ten, którego używają deweloperzy lokalnie, AGENTS.md staje się jedynym źródłem prawdy dla wszystkich tych narzędzi.

Niewidoczna utrata instrukcji

Procesy wieloagentowe mają nieprzyjemny sposób awarii. Wyobraź sobie, że jedna z etapów jest wykonywana w Claude Code, a druga w narzędziu od innego dostawcy. Jeśli twoje zasady znajdują się tylko w pliku CLAUDE.md, drugie narzędzie je ignoruje bez żadnego błędu ani ostrzeżenia. Agent działa normalnie, ale nie przestrzega konwencji, o których zakładałeś, że obowiązują. Wyniki stają się niespójne, zachowanie ulega zmianom, a ponieważ nic nie wygląda na uszkodzone, trudno jest znaleźć przyczynę. Użycie pliku AGENTS.md jako wspólnego punktu odniesienia pozwala każdemu narzędziu w procesie widzieć te same zasady.

SKILL.md: ładowane na żądanie

To rozwiązanie działa inaczej. Pozostałe dwa pliki są ładowane na początku każdej sesji i pozostają w kontekście. Umiejętność jest ładowana tylko wtedy, gdy bieżące zadanie odpowiada jej opisowi.

Nawyk to folder zawierający plik SKILL.md. Plik ten zaczyna się od krótkiego nagłówka w formacie YAML, który podaje nazwę nawyku oraz jednozdaniowy opis; to właśnie ten opis jest czytany przez Claude’a w celu oceny, czy dany nawyk pasuje. Gdy wysyłasz wiadomość, Claude porównuje ją z opisami wszystkich swoich nawyków i ładuje ten, który się zgadza. Po zakończeniu zadania nawyk jest odrzucany. Oto, jak może wyglądać frontmatter:

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Dlaczego to oszczędza tokeny

Załóżmy, że udokumentowałeś dziesięć procesów pracy. Umieść je wszystkie w pliku CLAUDE.md, a wszystkie one będą ładowane przy każdej wiadomości, nawet przy prośbie o poprawę błędu pisowni. Jako umiejętności ładowana jest tylko ta istotna, a pozostałe dziewięć nie kosztują nic. W długich sesjach łączących różne typy zadań to sprawia, że kontekst pozostaje zwięzły i skupiony na pracy przed tobą.

Najważniejsza jest opis

Claude polega na opisie do podejmowania decyzji. Niejasny opis, taki jak „pomaga z kodem”, albo w ogóle się nie aktywuje, albo działa we wszystkich przypadkach. Dokładny opis, np. sprawdzanie prośb o włączenie kodu w Pythonie pod kątem zagrożeń takich jak iniekcja SQL czy hardkodowane hasła, uruchamia się niezawodnie i tylko wtedy, gdy jest to konieczne. Nazwa folderu służy tobie, a opis – Claude’owi, więc pisz go dla niego.

Dwie przydatne opcje frontmatter

allowed-tools określa, co Claude może robić, gdy umiejętność jest aktywna. W przypadku umiejętności służącej do analizy bazy kodu ustawienie jej na read, grep i glob pozwala Claude’owi przeglądać pliki bez ich edycji czy zapisywania, a ograniczenie to obowiązuje nawet wtedy, gdy poprosisz o zmiany.

context: fork uruchamia działanie umiejętności w izolowanym kontekście. Etapy pośrednie pozostają niewidoczne, a do głównej sesji wraca tylko ostateczny wynik – co jest odpowiednie dla zadań generujących dużo treści, których nie musisz czytać, np. skanowania pięćdziesięciu plików w celu stworzenia jednego podsumowania.

Zachowaj umiejętności również kompaktowe

Duża umiejętność po załadowaniu zużywa więcej kontekstu. Jeśli proces wymaga obszernej dokumentacji, przykładów lub materiałów referencyjnych, umieść je w oddzielnych plikach i niech umiejętność ładuje je w razie potrzeby. Główne instrukcje powinny znajdować się bezpośrednio w procesie.

Porównanie trzech opcji

Jak wybrać

• Zasada obowiązująca we wszystkich zadaniach podczas każdej sesji umieszcza się w CLAUDE.md.
• Jeśli zespół używa kilku narzędzi do programowania opartych na AI lub proces łączy różne narzędzia, AGENTS.md powinno być źródłem prawdy, a CLAUDE.md powinno do niego być odlinkowane.

Określony proces pracy, który powtarzasz, np. przeglądanie PR-ów, tworzenie CV lub wyszukiwanie dokumentacji, powinien stać się umiejętnością.

Jeśli Claude musi pozostać w trybie tylko do odczytu podczas realizacji procesu, ustaw go jako umiejętność z atrybutem allowed-tools.

Jeśli chcesz ręcznie uruchomić coś za pomocą jednego polecenia, użyj polecenia z ukośnikiem w katalogu .claude/commands/.

Uporządkowana struktura

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md pozostaje krótki, ponieważ zawiera tylko to, co naprawdę jest potrzebne do wykonania każdego zadania. Umiejętności obsługują skomplikowane, specyficzne dla zadania procesy pracy. AGENTS.md zapewnia, że wszystko nadal funkcjonuje, gdy kolega z zespołu zmienia narzędzia.

Zasada ogólna

Jeśli CLAUDE.md ma ponad 200 wierszy lub około 1 200–1 500 tokenów, najprawdopodobniej za każdą wiadomość płacisz za instrukcje, których nie potrzebujesz. Ułóż treść według tego, kiedy jest potrzebna każda instrukcja: „zawsze” oznacza CLAUDE.md, „w różnych narzędziach” oznacza AGENTS.md, a „tylko dla jednego rodzaju zadania” oznacza umiejętność. Twoje okno kontekstowe to swego rodzaju budżet – główny plik zużywa część go przy każdej wiadomości, natomiast umiejętności – tylko w momencie użycia, więc projektuj strukturę z tym uwzględnieniem.

Literatura pokrewna

• Wyjaśnienie subagentów Claude Code: czym są i kiedy ich używać — Jak subagenty Claude Code różnią się od umiejętności i zespołów agentów: izolacja kontekstu, pierwszy dostosowany subagent, zasady opisywania i używania narzędzi oraz sytuacje, w których można ich pominąć.
• Zespoły agentów Claude Code: kiedy i jak używać modeli multi-agent — Kiedy jeden agent wystarcza, cztery sytuacje wymagające dodania więcej agentów, wzorce orkiestracji, style komunikacji, osiem sposobów awarii oraz wybór między rozwiązaniami wbudowanymi a samodzielnie budowanymi dla zespołów Claude Code.

GPT-Image-2.5 Flare vs Sunburst: Którą wariantę używać i kiedy — Praktyczne porównanie GPT-Image-2.5 Flare i Sunburst: wyniki w Arena, opóźnienia, rezultaty bezpieczeństwa, ceny, ograniczenia jakości oraz to, który wariant nadaje się do każdego procesu pracy.

Zmniejszenie rozmiaru gigantycznego CLAUDE.md o 91% i pomiar tego, co się zepsuło — Podzielenie pliku CLAUDE.md o długości 194 tysięcy znaków na elementy typu skills, referencje oraz reguły skierowane do określonych ścieżek, sprawdzenie, że nic nie zostało utracone, oraz pomiar częstotliwości wykonywania zadań przez elementy typu skills.