Dlaczego przestałem ładować każdy skill do każdej sesji Claude Code

TL;DR: Do każdej sesji Claude Code ładowało mi się około 25 skilli, kilka subagentów i kilka serwerów MCP, bez względu na to, który projekt otwierałem. Objaw wracał jak bumerang: "agent gubi kontekst". Przyczyną nie był brak dokumentacji, tylko brak warstw. Wszystko było globalne, więc każda sesja płaciła za narzędzia, których nigdy nie użyje. Rozwiązanie to trzy warstwy: malutki globalny rdzeń, magazyn, z którego nic nie jest włączane, i manifest per projekt, który dociąga tylko to, czego dane repo potrzebuje. Ten artykuł jest o tym, co naprawdę wchodzi do okna kontekstu i kiedy. Bez tej wiedzy optymalizujesz nie to, co trzeba.

Co się naprawdę ładuje i kiedy

Cały projekt opiera się na jednym rozróżnieniu, które łatwo przeoczyć: opisy ładują się od razu, treść dopiero na żądanie. Skill nie wrzuca do kontekstu pełnych instrukcji na starcie. Wrzuca jednozdaniowy opis, żeby model wiedział, że skill istnieje i kiedy po niego sięgnąć. Treść jest czytana dopiero wtedy, gdy skill zostanie faktycznie wywołany.

Kiedy to zrozumiesz, model kosztów układa się sam:

Wniosek: opisy się sumują. Dwadzieścia pięć skilli to dwadzieścia pięć opisów w każdej sesji, łącznie z tymi dwudziestoma, które nie mają nic wspólnego z repo, nad którym właśnie siedzisz. To podatek płacony przy każdym starcie. Plik instrukcji w podkatalogu działa odwrotnie: ładuje się leniwie, więc nic nie kosztuje, dopóki nie zaczniesz pracować w tym katalogu. Kto wie, co jest czym, ten tnie tłuszcz, a nie mięśnie.

Trzy warstwy

Warstwa pierwsza: globalna. Tylko to, co dotyczy każdego repo, jakie kiedykolwiek otworzę: uniwersalne standardy kodu, tożsamość i konwencje gita, domyślne ustawienia bezpieczeństwa, zasady językowe. Najwyżej dwa uniwersalne skille. Test jest prosty: jeśli reguła nie dotyczy każdego projektu, nie ma tu czego szukać. To, co przejdzie ten test, zasługuje na stałe miejsce w oknie kontekstu. Nic innego.

Warstwa druga: magazyn. Jeden katalog, w którym trzymam wszystkie skille i subagenty i z którego nic nie jest włączane. To biblioteka, nie środowisko uruchomieniowe. Nowe skille trafiają najpierw tutaj. Oddzielenie katalogu od tego, co aktywne, trzyma całość w ryzach: mogę mieć pięćdziesiąt skilli, a żadna sesja nie płaci za pięćdziesiąt opisów.

Warstwa trzecia: per projekt. Każde repo deklaruje w małym, commitowanym manifeście skille i agenty, których naprawdę używa, do tego własne ustawienia i własną konfigurację MCP. Jednolinijkowy skrypt czyta manifest i odtwarza linki do magazynu. Manifest jest w repo, a wygenerowane linki są w gitignore, bo zawierają ścieżki bezwzględne, które na innej maszynie nie mają sensu. Źródło prawdy podróżuje więc razem z repo, a odtworzenie całej konfiguracji gdziekolwiek to jedna komenda.

Sam manifest jest celowo nudny: lista nazw, jedna w linii, bez kombinowania:

# <repo>/.claude/skills.manifest
code-standards
nextjs
supabase-postgres
ui-design-system

To cały interfejs. Dopisujesz nazwę, uruchamiasz skrypt do linków, restartujesz. Prawdziwa wartość siedzi w samych skillach, które zostają w prywatnym magazynie. Manifest mówi tylko, które z nich to repo może zobaczyć.

Liczy się to, skąd uruchamiasz agenta

Zanim to zrozumiałem, sporo się naszukałem. Katalog roboczy, z którego startujesz, decyduje o tym, co się załaduje, a nie wszystko dziedziczy się w górę. Pliki instrukcji i skille są szukane od bieżącego katalogu aż do korzenia repo (i leniwie w dół). Plik ustawień i konfiguracja MCP są natomiast czytane tylko z katalogu, w którym faktycznie wystartowałeś. Nie idą w górę drzewa.

Pułapka jest bardzo konkretna. Uruchom agenta z głęboko zagnieżdżonego podkatalogu, a dostaniesz pliki instrukcji i skille, ale po cichu stracisz ustawienia projektu i konfigurację MCP. A to właśnie ta warstwa trzyma reguły bezpieczeństwa i blokady uprawnień. Zdejmujesz zabezpieczenia i nic cię o tym nie ostrzega. Dziś trzymam się prostej zasady: zawsze startuję z korzenia repo.

Pamięć ma własny haczyk, który warto znać. Identyfikator pamięci per projekt powstaje na podstawie repozytorium gita, a nie katalogu, z którego akurat startujesz, więc wszystkie podkatalogi repo dzielą jedną pamięć. Folder, który tylko zawiera wiele repo, ale sam repo nie jest, dostaje własny identyfikator. I dobrze, bo pamięć całej rodziny produktów trzymasz wtedy w jednym miejscu, a nie rozrzuconą po dwudziestu szufladach.

Kilka ostrych krawędzi

Dwie rzeczy, których nauczyłem się w irytujący sposób. Po pierwsze, nie kopiuj uniwersalnych reguł do pliku instrukcji projektu, tylko linkuj do globalnych. Zduplikowany dokument się rozjeżdża, a rozjechany dokument zaczyna cię okłamywać. To ta sama zasada DRY, którą stosujesz w kodzie, tyle że zastosowana do instrukcji. Po drugie, pamiętaj, że niektóre zewnętrzne instalatory skilli kopiują swoje pliki naraz do katalogów konfiguracyjnych kilku różnych narzędzi AI. To duplikaty jednej rzeczy, a nie osobne zasoby. Jeśli potraktujesz je jak osobne, pomylisz się w rachunku tego, co naprawdę się ładuje.

Co to dało

W jednym projekcie ta zmiana zeszła z około 25 opisów skilli w sesji do 12 plus 2 globalnych, z 5 subagentów do 4 i z 4 serwerów MCP do 2. Te dwa, których projekt nigdy nie dotyka, po prostu przestały się ładować. W samym modelu nic się nie zmieniło. Okno kontekstu przestało być zapchane opisami narzędzi bez związku z pracą, a "agent gubi kontekst" przestało wracać jako stała skarga.

Jeśli jest z tego jakaś ogólna lekcja, to taka: przy narzędziach dla agentów więcej zainstalowanych rzeczy nie znaczy więcej możliwości. Wszystko, co ładuje się od razu, konkuruje o tę samą, skończoną uwagę modelu. Zadanie polega na tym, żeby w pokoju było dokładnie to, czego potrzebuje bieżące zadanie, a cała reszta była o jeden wpis w manifeście stąd, zamiast siedzieć tam na stałe.

Co warto przenieść do siebie

• Znaj koszty ładowania od razu i na żądanie. Opisy sumują się przy każdym starcie, docsy w podkatalogach są darmowe, dopóki ich nie użyjesz. Optymalizuj te ładowane od razu.
• Globalnie tylko to, co uniwersalne. Jeśli reguła nie dotyczy każdego repo, należy do warstwy projektu, a nie do okna kontekstu każdej sesji.
• Biblioteka to nie środowisko uruchomieniowe. Trzymaj w magazynie tyle skilli, ile chcesz, a włączaj je per projekt przez commitowany manifest.
• Startuj z korzenia repo. Ustawienia i konfiguracja MCP nie dziedziczą się w górę, a to w tej warstwie mieszkają twoje zabezpieczenia.
• Linkuj, nie kopiuj. Zduplikowane instrukcje się rozjeżdżają, a rozjechane instrukcje wprowadzają agenta w błąd.