CLAUDE.md, SKILL.md i MCP: Która warstwa przechowuje jakie instrukcje
Dlaczego jeden ogromny plik CLAUDE.md zawodzi agenty do kodowania, co powinno znaleźć się w zasadach, umiejętnościach i połączeniach MCP, zakresach i ścieżkach, drzewie decyzyjnym oraz pułapce nazewnictwa AGENTS.md.
Źródła: CLAUDE.md vs SKILL.md vs MCP: The Modern Agent Stack Explained
Nowi użytkownicy Claude Code oraz podobnych narzędzi do programowania mają tendencję do popełniania tego samego błędu w pierwszym miesiącu. Otwierają plik CLAUDE.md i ciągle piszą: wytyczne dotyczące stylu, kroki implementacji, listy kontrolne do przeglądu, surowe schematy bazy danych – aż plik osiąga 600 lub 900 wierszy. Zakłada się, że im więcej informacji na początku, tym narzędzie będzie mądrzejsze.
Jest jednak inaczej. Pamięć robocza się przepełnia, odpowiedzi stają się mniej dokładne, a polecenia, które wcześniej działały poprawnie, przestają funkcjonować. Coś jest nie tak, ale trudno określić co dokładnie. Przy każdej prostej prośbie model musi najpierw przejrzeć setki wierszy nieistotnych instrukcji, zanim dotrze do choćby jednego wiersza kodu. To nie wina modelu ani polecenia – po prostu od pojedynczego pliku tekstowego zażądano wykonywania trzech różnych zadań.
Współczesne agenty do kodowania działają najlepiej, gdy instrukcje są podzielone na trzy oddzielne warstwy: zasady projektu, które są zawsze aktywne, umiejętności do zadań ładowane na żądanie oraz połączenia z narzędziami w czasie rzeczywistym za pośrednictwem MCP. Dzięki takiej strukturze model otrzymuje tylko to, czego potrzebuje, i to w momencie, gdy tego potrzebuje.
Dlaczego trzy warstwy
Sprawiedliwe jest zapytanie, dlaczego trzy warstwy, a nie jeden duży plik albo dziesięć małych, specjalistycznych plików. Każda warstwa rozwiązuje inny problem, a te problemy mniej się nakładają, niż można by oczekiwać.
- CLAUDE.md zajmuje się informacjami, które muszą zawsze być prawdziwe.
- SKILL.md obsługuje dane, które mają znaczenie tylko czasami.
- MCP zarządza danymi, które stają się przestarzałe w momencie zapisania.
To są trzy odrębne tryby awarii, a nie trzy warianty jednego. Jeśli połączymy umiejętności z plikiem CLAUDE.md, rezultatem będzie jeden rozdęty plik, który jest ładowany w całości przy każdej sesji, niezależnie od tego, czy potrzebna jest lista kontrolna wdrożenia, czy nie. Każda dodatkowa warstwa okazuje się podziałem jednego z tych trzech trybów, a nie nowym zadaniem.
Co powinno znajdować się w CLAUDE.md lub AGENTS.md
Wyobraźmy sobie CLAUDE.md jako notatkę pozostawioną dla inżyniera już pierwszego dnia. To nie jest pełny dokument wprowadzający, lecz zbiór kilku niepisanych zasad, których wszyscy w zespole już znają, takich jak brak komponentów klasowych czy konieczność korzystania z warstwy usługowej zamiast bezpośredniego dostępu do bazy danych.
Plik znajduje się w korzeniu projektu, a Claude Code odczytuje go automatycznie na początku każdej sesji. Nikt go nie wywołuje ani o niego nie prosi. Po prostu tam jest, tak jak pamięć o zasadach zespołu jest obecna, gdy ktoś siada do pisania kodu.
Dobrymi przykładami są konwencje kodowania, struktura projektu, sztywne ograniczenia, zasady bezpieczeństwa, takie jak nigdy nie ujawnianie kluczy API w kodzie, oraz persona, którą agent powinien przyjąć podczas przeglądania pracy.
Złymi przykładami są 40-krotny przewodnik wdrażania, schemat bazy danych oraz wszystko, co ma znaczenie tylko raz na dziesięć dni. To właśnie do tej drugiej grupy należą większość osób, które popełniają błędy. Jeśli coś nie jest aktualne na każdej sesji, prawdopodobnie nie powinno tam znajdować się. PLIK CLAUDE.md, który próbuje być wszystkim, kończy się jako powolna, przeciążona wersja niczego.
Istnieje również wersja globalna w pliku ~/.claude/CLAUDE.md, która ma zastosowanie we wszystkich projektach. Ludzie zazwyczaj przechowują tam swoje osobiste nawyki, takie jak ulubiony styl komunikatów commit lub język używany w odpowiedziach, a zasady specyficzne dla projektu umieszczają w pliku projektu.
Plik, który prawidłowo wykonywa swoje zadanie, wygląda następująco – jest to adaptacja powszechnie dostępnych wytycznych dotyczących zachowania.
# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## 2. Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## 3. Surgical Changes
**Touch only what you must. Clean up only your own mess.**
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
Jest krótki i konkretny, i nie ma w nim nic, co wymagałoby poprawek w przyszłym tygodniu. Oto jak wygląda, gdy coś idzie nie tak – to wzorzec powszechny we wczesnych wersjach.
# Project Notes
Our database has these tables: users, orders, products, sessions,
audit_log (schema pasted below, 340 lines)...
To deploy, first SSH into staging, then run these 47 commands...
Here's our Slack webhook URL for notifications: hooks.slack.com/...
When reviewing PRs, check for: [12 paragraphs of instructions]
Każdy element z tego drugiego przykładu jest błędny w kontekście CLAUDE.md, a każdy z innej przyczyny. Schemat staje się przestarzały, gdy tylko ktoś dodaje kolumnę. Kroki implementacji opisują jedno określone zadanie. Adres webhooka jest tajemnicą i powinien znajdować się w zmiennej środowiskowej, a nie w zapisanym pliku markdown. Instrukcje dotyczące przeglądu PR to umiejętność ubrana w szaty CLAUDE.md.
Praktyczny test: czy ta informacja nadal byłaby prawdziwa, gdyby przeczytać ją ponownie za trzy miesiące, w dowolny wtorek, podczas wykonywania czegoś zupełnie innego? Jeśli nie, to nie powinna znajdować się w tym pliku.
SKILL.md: ekspertyza, która pojawia się tylko w razie potrzeby
Agent Skills trafił od Anthropic w październiku 2025 roku i został zaprojektowany tak, aby instrukcje dotyczące konkretnej zadania mogły znajdować się w folderze i być ładowane w razie potrzeby, zamiast cały czas zajmować przestrzeń kontekstową. W grudniu 2025 roku ten format został otwarty jako niezależny standard, a inne narzędzia szybko go przyjęły. VS Code, Cursor, Antigravity IDE firmy Google, Gemini CLI, Goose oraz kilka innych agentów do programowania obsługują teraz ten sam format SKILL.md, który używa Claude Code. To właśnie dzięki niemu MCP stał się powszechnym standardem w branży do łączenia narzędzi.
Idea ta okazuje się przydatna, gdy już ją zrozumiemy: nie wszystkie informacje muszą cały czas znajdować się w pamięci agenta. Większość wiedzy inżyniera staje się istotna tylko przy wykonywaniu określonego zadania. Nikt nie przypomina sobie listy kontrolnej przed wdrożeniem podczas pisania funkcji pomocniczej. Umiejętności działają zgodnie z tą samą logiką. Folder zawierający plik SKILL.md pozostaje nieużywany, dopóki nie nadejdzie prośba typu „przeczytaj ten PR”, a wtedy Claude wykorzystuje właściwą listę kontrolną do przeglądu.
Plik z umiejętnością zaczyna się od krótkiego opisu, zwanego frontmatter, który określa, co robi dana umiejętność i kiedy powinna zostać uruchomiona. Gdy wiadomość odpowiada temu opisowi, Claude ładuje pozostałą część. Gdy tak nie jest, żaden z tych elementów nie zajmuje miejsca w rozmowie. Dlatego umiejętności wydają się lżejsze niż przechowywanie wszystkiego w pliku CLAUDE.md. Umiejętność do przeglądania pull requestów, inna do migracji bazy danych oraz jeszcze jedna do notatek o wydaniu nie konkurują ze sobą o przestrzeń, chyba że dokładnie ta sama zadanie jest aktualnie wykonywana.
.claude/skills/
├── code-review/
│ └── SKILL.md
├── pr-description/
│ └── SKILL.md
└── anti-sycophancy/
└── SKILL.md
Nawyki na poziomie projektu znajdują się w katalogu .claude/skills/ wewnątrz repozytorium. Osobiste umiejętności, które powinny towarzyszyć użytkownikowi wszędzie, znajdują się w katalogu ~/.claude/skills/. Taki podział odzwierciedla strukturę pliku CLAUDE.md: projekty w przeciwieństwie do ustawień globalnych. Oto jego skrócona wersja:
---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---
# Production Code Validation Checklist
**Run this checklist before pushing code to GitHub.**
This is not optional. This is how you prevent broken repositories.
## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore
## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time
## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work
**If you cannot check a box, you are not done.**
Zwróć uwagę, czego unika. Nie przestrzega również konwencji kodowania ani schematu bazy danych. Ma jedną nazwaną czynność, uruchamianą przy określonym wydarzeniu, i to właśnie sprawia, że jest umiejętnością, a nie wersją CLAUDE.md o mniejszych możliwościach. Prostym kryterium jest to, czy coś jest potrzebne tylko podczas wykonywania konkretnej, nazwanej czynności. Jeśli tak, jest to umiejętność, a nie zasada.
MCP: dostęp, a nie tylko wiedza
CLAUDE.md i SKILL.md to pliki markdown napisane przez kogoś. MCP jest inny – łączy Claude’a, gdy ten działa, z zasobem poza czatem, czy to bazą danych, GitHubem, Slackiem, systemem plików lub czymkolwiek innym, co zostało podłączone.
W projekcie opartym na technologii RAG typowym przypadkiem jest bezpośrednie połączenie z Chromą. Oficjalny serwer chroma-mcp udostępnia kolekcje jako narzędzia, których Claude może używać do wyszukiwania informacji.
{
"mcpServers": {
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type", "persistent",
"--data-dir", "/path/to/your/chroma/data"
]
}
}
}
W Claude Code konfiguracja odbywa się za pomocą jednego polecenia, bez konieczności ręcznej edycji pliku JSON.
claude mcp add --scope project chroma \
-- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data
Zarejestrowuje serwer i zapisuje konfigurację do pliku .mcp.json w projekcie, który można zapisać, dzięki czemu cały zespół uzyskuje tę samą połączenie bez konieczności ręcznej konfiguracji. Claude Code oferuje trzy zakresy dostępu: lokalny, oznaczający jednego użytkownika na jednym komputerze; projektowy, oznaczający plik zapisany w repozytorium i udostępniony; oraz użytkownikowy, oznaczający wszystkie projekty, z którymi dana osoba pracuje. Ten sam schemat projektowy kontra globalny pojawia się po raz trzeci, co ułatwia jego zapamiętanie po pierwszym zauważeniu.
Protokół rozwija się tak szybko, że ten wzrost sam w sobie stanowi istotną część jego historii. Oficjalny rejestr serwerów zawiera ponad 9 000 serwerów, a miesięczne liczby pobieranych wersji SDK wzrosły z około 2 milionów do prawie 100 milionów w ciągu około 16 miesięcy, według danych udostępnionych przez Anthropic. To już nie jest funkcja typu niszowa. Każdy, kto nadal wkleja schemat lub propozycję zmian z GitHuba do promptu, ręcznie wykonuje to, co połączenie MCP robi w czasie rzeczywistym, a wklejona treść staje się przestarzała, gdy tylko coś zmieni się w źródle.
Drzewo decyzyjne
- Czy to powinno obowiązywać we wszystkich sesjach, niezależnie od zadania? Jeśli tak, umieść to w pliku CLAUDE.md. Jeśli nie, kontynuuj.
- Czy jest to konkretne, nazwane, powtarzalne zadanie z własnymi krokami? Jeśli tak, utwórz plik SKILL.md. Jeśli nie, kontynuuj.
Pułapka nazewnictwa
Każdy, kto zmienia narzędzia, w pewnym momencie na to natrafi. Claude Code i Cursor czytają plik CLAUDE.md, podczas gdy Codex CLI oraz kilka innych środowisk uruchomieniowych czyta AGENTS.md, które pełni tę samą funkcję pod inną nazwą. Antigravity firmy Google, stworzone przez były zespół Windsurf po umowie zawartej z nimi w połowie 2025 roku, również używa własnej konwencji AGENTS.md. Mimo to wszystkie one – Claude Code, Cursor, Codex i Antigravity – czytają ten sam format SKILL.md dla umiejętności. Dlatego warstwa zasad różni się w zależności od narzędzia, ale warstwa umiejętności pozostaje jednolita. To ma znaczenie, zanim założymy, że umiejętność napisana dla jednego agenta musi zostać przepisana dla innego.
Nawyk, który to rozwiązuje
Zanim dodasz akapit do CLAUDE.md, zapytaj, do których z trzech kategorii należy. Duża część materiałów umieszczonych w CLAUDE.md to w rzeczywistości umiejętności, które nigdy nie otrzymały własnej folderu. To jest forma projektowania kontekstu poprzez inne oznaczenia: decydujesz, co agent ma zobaczyć i w którym momencie, zamiast wrzucać wszystko do pierwszego otwartego pliku i mieć nadzieję, że model to uporządkuje. Otwórz CLAUDE.md i policz, ile akapitów to w rzeczywistości umiejętności używające niewłaściwej rozszerzenia pliku. Liczba ta jest zazwyczaj wyższa, niż się spodziewa.
Literatura pokrewna
- Wyjaśnienie WebMCP: Dostarczanie narzędzi agentom AI w przeglądarce zamiast domysłów — WebMCP umożliwia stronie internetowej określenie narzędzi dostępnych dla agentów AI. Jak je zarejestrować, ocenić ryzyko, przetestować w Chrome oraz zarządzać bezpieczeństwem, a także jaki jest stan wsparcia przeglądarek w 2026 roku.
- Praktyczne notatki: Trzy poziomy usługi Google Cloud RAG: wyszukiwanie wektorowe, silnik RAG i odzyskiwanie informacji przez agenty — Szczegółowy przewodnik po Praktycznych notatkach: Trzech poziomach usługi Google Cloud RAG: wyszukiwanie wektorowe, silniku RAG oraz mechanizmie odzyskiwania informacji przez agenty: umowy, sprawdzenia oraz gotowe fragmenty kodu do wykorzystania.