Gdzie powinna znajdować się każda instrukcja: AGENTS.md, CLAUDE.md i SKILL.md

Ponad 4 300 inżynierów oddało głosy na pojedynczy problem w GitHubie, w którym prosi się o to, aby Claude Code ładował plik AGENTS.md bez żadnej pomocy. W lipcu 2026 roku, w wersji 2.1.201, nadal tak nie robi. Dokumentacja dotycząca pamięci opracowana przez samą firmę Anthropic pokazuje teraz programistom, jak mimo to wymusić takie zachowanie: należy uruchomić w terminalu polecenie ln -s AGENTS.md CLAUDE.md. W praktyce dostawca oferuje rozwiązanie obejścia problemu z plikiem, którego własne narzędzie odmawia odczytania.

Argumenty są mniej interesującą częścią. Prawdziwa inżynieria objawia się w jednej linii pliku claude-api SKILL.md w publicznym repozytorium umiejętności Anthropic, konkretnie w polu opisu jego struktury YAML. W odróżnieniu od plików CLAUDE.md i AGENTS.md, to właśnie ten opis decyduje o tym, czy Claude w ogóle będzie czytał resztę pliku. W grę wchodzą trzy pliki oraz trzy modele do ładowania, a kwestia ich umieszczenia sama się rozwiązuje, gdy tylko stanie się widoczna odpowiednia ścieżka.

Jak doszło do podziału

Historia pokazuje, jak branża doszła do tego stanu. W sierpniu 2025 roku uruchomiono specyfikację AGENTS.md jako uniwersalny zestaw instrukcji dla asystentów do programowania opartych na sztucznej inteligencji. Polecenia budowy, zasady testowania oraz architektura projektu mogły znajdować się w jednym miejscu, a idea polegała na tym, że zarówno Cursor, Copilot, jak i samodzielne agenty miały korzystać z tego jednego pliku.

Dwa miesiące później, w październiku 2025 roku, Anthropic przedstawił Agent Skills, który przyjął inne podejście do obsługi kontekstu. Zamiast prostego pliku markdown z zasadami, umiejętność to katalog zawierający własne metadane, skrypty oraz dokumenty referencyjne.

Oba formaty stały się standardami otwartymi do grudnia 2025 roku. Specyfikacja umiejętności została opublikowana na agentskills.io, natomiast specyfikacja AGENTS.md trafiła do Linux Foundation jako projekt podstawowy dla Agentic AI Foundation. Obecnie ponad 60 000 repozytoriów oraz około dwudziestu narzędzi obsługuje AGENTS.md bez dodatkowych ustawień, więc żaden z tych standardów nie zniknie.

W rezultacie zespoły piszą teraz te same instrukcje w trzech miejscach: AGENTS.md dla edytora, CLAUDE.md dla terminala oraz SKILL.md dla złożonych procesów pracy. Następnie zastanawiają się, dlaczego agenci zwalniają, a rachunki za tokeny rosną. Rozwiązanie zaczyna się od sposobu, w jaki te narzędzia faktycznie analizują tekst.

Brama dostępu do umiejętności

Sesja nie rozpoczyna się od czytania przez agenta każdego pliku w projekcie, ponieważ to wyczerpałoby okno kontekstowe i osłabiło uwagę modelu. Zamiast tego szuka on określonych punktów wejścia oraz umiejętności, dla których te punkty wejścia stosują model stopniowej ujawniania informacji.

Podczas uruchamiania agent ładowa metadane każdej z zainstalowanych umiejętności do promptu systemowego. Te metadane to nazwa i opis, co kosztuje około 100 tokenów na umiejętność. Następnie agent czyta prośbę użytkownika, porównuje ją z załadowanymi opisami i decyduje, czy otworzyć treść danej umiejętności. Opis pełni rolę strażnika, a materiały referencyjne są za nim zamknięte.

Poniżej znajduje się frontmatter umiejętności claude-api, opublikowany w otwartym repozytorium Anthropic.

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

Pole opisu pełni podwójną funkcję. Informuje agenta o tym, czym zajmuje się dana umiejętność, a jednocześnie służy jako interfejs programistyczny, za pośrednictwem którego autor umiejętności koduje logikę aktywacji.

TRIGGER i SKIP to konwencje, a nie pola zdefiniowane w schemacie. Autor po prostu pisze instrukcje w zwykłym języku angielskim dotyczące momentu, gdy brama powinna się otworzyć. Treść tej umiejętności składa się z setek linijek referencji API. Pytanie dotyczące bazy danych Postgres nie przechodzi sprawdzenia opisu, w związku z czym tekst referencyjny pozostaje niewykorzystany.

CLAUDE.md i AGENTS.md zachowują się inaczej. Nie mają odpowiednika bramy. Gdy agent znajdzie je na ścieżce, wstrzykuje je na początku sesji i pozostają one aktywne przez całą rozmowę.

Co powinno znajdować się w którym pliku

Model ładowania decyduje o zawartości. Plik wstrzyknięty powinien zawierać tylko to, czego agent potrzebuje na każdym kroku. Plik z kontrolą dostępu powinien przechowywać specjalistyczną wiedzę stosowaną do konkretnych zadań.

Repozytorium o nazwie orchard pokazuje, jak te pliki mogą współistnieć na dysku bez duplikowania informacji.

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md zawiera wspólne zasady budowania, w tym wytyczne dotyczące stylu, strukturę monorepo, instrukcje jak uruchamiać testy oraz notatki na temat zależności. Jest to podstawowy kontekst, którego potrzebuje każdy agent, niezależnie od używanego narzędzia. Jego charakterystyczną cechą jest zasada „najbliższy plik ma pierwszeństwo”: agent pracujący w katalogu services/payments/ najpierw czyta zawarty tam AGENTS.md i preferuje swoje lokalne zasady nad tymi znajdującymi się w katalogu głównym. OpenAI zarządza swoim wewnętrznym kontekstem za pomocą takiej struktury monorepo składającej się z 88 plików, a zawarte w niej pliki pozwalają zachować uporządkowanie poprzez ładowanie wyłącznie tego, czego potrzebuje aktualny katalog.

CLAUDE.md ma węższy zakres funkcji. Zawiera ono instrukcje, które mają sens tylko wtedy, gdy aktywnym agentem jest Claude Code.

Rozdęcie to powszechny problem plików CLAUDE.md. Programiści wklejają cały plik AGENTS.md do CLAUDE.md, zakładając, że Claude potrzebuje własnej kopii zasad budowania. Zamiast tego właściwa, minimalna forma importuje wspólny standard do kontekstu Claude’a.

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

Zasada obowiązująca w kilku narzędziach powinna znajdować się w pliku AGENTS.md. Import z @AGENTS.md jest głównym wzorem zalecanym w dokumentacji dotyczącej pamięci w Anthropic, natomiast symlink stanowi rozwiązanie awaryjne dla repozytoriów, które nie mają nic specyficznego dla Claude i chcą jedynie, aby narzędzie czytało standardowy plik.

SKILL.md to warstwa umiejętności warunkowych – miejsce na powtarzające się procesy, jednorazowe funkcje oraz specjalistyczną terminologię danego obszaru. W orchard katalog .agents/skills/db-migration/ zawiera wszystko, co jest potrzebne do bezpiecznej migracji do Postgresa, mianowicie skrypt w Pythonie służący do sprawdzenia możliwości odwrócenia zmian oraz notatkę w formacie markdown na temat trybów blokowania w Postgresie. Nic z tego nie powinno znajdować się w AGENTS.md. Agent edytujący plik CSS w pakiecie UI nie powinien otrzymywać informacji o trybach blokowania w swoim systemowym komunikacie. Mechanizm opisowy zapewnia, że umiejętność zostanie załadowana tylko wtedy, gdy zostanie edytowany plik migracyjny.

Zasada routingu

Gdy proces ładowania modeli zostanie zakończony, dodawanie nowych informacji kontekstowych staje się rutynowe:

• Kontekst projektu, dostępny we wszystkich narzędziach i potrzebny przy każdym kroku, umieszcza się w pliku AGENTS.md.
• Wskazówki przeznaczone wyłącznie dla Claude Code trafiają do pliku CLAUDE.md, najlepiej w postaci krótkiego pliku, który importuje AGENTS.md.
• Procedury pracy specyficzne dla danej sytuacji, skrypty oraz odniesienia do określonego dziedziny, potrzebne tylko przy niektórych zadaniach, umieszcza się w odpowiedniej umiejętności, za opisem wskazującym, kiedy ją otworzyć.

Ochrona budżetu ciągłej aktywności

Różnica pomiędzy ładowaniem warunkowym a ciągłym jest bezpośrednio związana z wydajnością agenta.

Badanie przeprowadzone w styczniu 2026 roku (arXiv:2601.20404) przez badaczy z King’s College London, Singapore Management University, Uniwersytetu w Heidelbergu oraz Uniwersytetu w Bambergu zmierzyło, jakie faktycznie funkcje pełnią pliki AGENTS.md. Czas działania agentów skurczył się o 28,64%, a liczba wygenerowanych tokenów o 16,58%, przy tym zadania były realizowane z podobną szybkością. Wspólna warstwa instrukcji sprawia, że agenci są bardziej wydajni. Przestają wymyślać komendy budowania i uruchamiać niewłaściwe zestawy testów, ponieważ model czyta kanoniczne zasady raz i od razu przystępuje do wykonywania zadania.

Ta efektywność utrzymuje się tylko wtedy, gdy kontekst pozostaje istotny. Każdy token umieszczony w promptzie systemowym przyciąga uwagę modelu. Załóżmy, że zespół wklei 500-słowny przewodnik dotyczący migracji bazy danych do pliku AGENTS.md. Agent musi wtedy go przeczytać podczas naprawy błędu w stanie interfejsu użytkownika, poświęcając uwagę trybom blokowania w Postgresie, podczas gdy powinien myśleć o hookach w React.

Ładowanie warunkowe chroni te osiągnięcia. Przenoszenie zadań specyficznych dla danej sytuacji do pliku SKILL.md sprawia, że plik AGENTS.md pozostaje zwięzły, co zapewnia korzyści wynikające z wspólnego kontekstu podczas działania i unika kosztów związanych z poświęcaniem uwagi instrukcjom, które się nie odnoszą.

Most, który istnieje, i ten, który nie istnieje

W ekosystemie istnieje luka w obszarze tłumaczeń. Claude Code rozumie umiejętności oraz zasady ich ujawniania, natomiast Cursor, Copilot oraz samodzielne narzędzia CLI nie rozumieją w sposób wbudowany struktury .agents/skills/.

Zespół, który tworzy umiejętność migracji bazy danych, chce, aby również użytkownicy Cursor mogli z niej skorzystać. Ręczne kopiowanie tej umiejętności do pliku AGENTS.md zniweczyłoby zasadę jednego źródła prawdy, dlatego rozwiązaniem jest jej skompilowanie.

Agenty inne niż Claude mogą wtedy widzieć te umiejętności bez konieczności ręcznego kopiowania. Wygenerowany blok, taki jaki pojawia się w pliku AGENTS.md w Orchard, wygląda w ten sposób.

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

Most wyświetla nazwę, ścieżkę i opis każdej umiejętności. Agenty inne niż Claude nie mają wbudowanej funkcji stopniowego ujawniania tych informacji, więc podsumowanie w bloku umiejętności służy jako ich interfejs: narzędzie czytające AGENTS.md znajduje ten blok, odczytuje warunki aktywacji i dowiaduje się, gdzie na dysku szukać informacji potrzebnych do przeprowadzenia migracji.

Nadal brakuje mostu umożliwiającego Claude Code na bezpośrednie czytanie AGENTS.md, bez konieczności importu lub tworzenia symlińków. Na Manifold nadal funkcjonuje rynek prognoz dotyczący tego, czy Anthropic doda taką funkcjonalność do końca roku. Ta luka wskazuje, że twórcy narzędzi chcą kontrolować własną warstwę kontekstu. Anthropic posiada CLAUDE.md, natomiast społeczność – AGENTS.md. Kompatybilność między narzędziami będzie nadal zależeć od dostępnych rozwiązań i pipeline’ów CI, a nie od wymogów specyfikacji.

System ostatecznie

Przegląd monorepo ogrodu jabłkowego pokazuje skutecznie działającą konfigurację. Wewnątrz znajdują się pliki AGENTS.md, które przechowują wspólne zasady strukturalne. Plik CLAUDE.md o jednej linii zajmuje się specyficznymi importami dla Claude. Plik SKILL.md do migracji bazy danych czeka za swoją bramką opisową na zadanie z bazy danych, które je uruchomi, a GitHub Action łączy wszystko razem, dzięki czemu żaden programista nie musi pisać tej samej zasady dwa razy.