Skille zmieniają styl pracy agenta, ale to CLAUDE.md decyduje o wyniku

Skąd to się bierze

Pracuję w kilku repozytoriach dziennie i za każdym razem powtarzałem agentowi te same rzeczy: nie buduj abstrakcji na zapas, nie pisz elaboratów, pokaż mi diff a nie opowieść o diffie. Skill to miejsce, w którym taka instrukcja zostaje na stałe. Dokumentacja Claude Code opisuje to od strony kosztu: treść skilla ładuje się dopiero wtedy, gdy jest potrzebna, więc długa procedura nic nie kosztuje, dopóki jej nie użyjesz.

Cztery, które mam włączone najczęściej, robią cztery różne rzeczy.

Cztery skille, cztery zadania

Ponytail pilnuje zakresu rozwiązania. Wymusza drabinę: czy to w ogóle musi powstać, czy nie ma tego już w repozytorium, czy nie załatwi tego biblioteka standardowa albo natywna funkcja platformy, czy da się to zrobić jedną linijką. Efekt jest taki, że zamiast klasy z fabryką i konfiguracją dostaję jedną funkcję, a przy okazji zdanie, czego świadomie nie zrobiono i kiedy to dopisać. To jedyny skill, który regularnie każe mi coś usunąć zamiast dopisać.

Caveman zajmuje się formą odpowiedzi. Wycina zwroty grzecznościowe, asekuracje i narrację wokół wywołań narzędzi. Treść techniczna zostaje bez zmian, znika obudowa. Praktyczna korzyść jest prozaiczna: w oknie kontekstu zostaje miejsce na kod zamiast na uprzejmości.

Codex gate to zewnętrzna recenzja. Po każdym commicie inny model przegląda zmianę i zgłasza zastrzeżenia. Sens polega na tym, że recenzent nie brał udziału w pisaniu, więc nie broni swoich decyzji. Ten sam mechanizm, który w zespole daje code review, tylko dostępny o drugiej w nocy. U mnie robi to własny hook po commicie, ale oficjalna wtyczka Codex do Claude Code ma wbudowaną bramkę uruchamianą na koniec odpowiedzi.

Design taste, u mnie skill własny, bez publicznego repozytorium, trzyma front z dala od domyślnych rozwiązań, które zdradzają, że interfejs wygenerował model: wyśrodkowany hero, trzy równe kafle, fioletowa poświata, Inter wszędzie. Zamiast tego wymusza asymetrię, jeden stonowany akcent i ograniczenia dotyczące animacji. Ta strona powstała właśnie z jego użyciem.

Dlaczego to i tak za mało

Skill mówi, jak pracować. Nie mówi, jak działa konkretny system. Tę część musi nieść repozytorium, i to jest różnica między agentem, który dowozi, a takim, który zgaduje.

W Dentrio, systemie dla gabinetów stomatologicznych, plik CLAUDE.md ma 381 linii, README.md prawie tysiąc, a dokumentacja procesów kolejne kilkaset. To nie jest ozdoba, tylko trzy rzeczy, których agent nie odkryje sam:

Pułapki, które nie rzucają błędu. Dodanie nowej przestrzeni nazw tłumaczeń wymaga zarejestrowania jej w tablicy modules. Bez tego loader po cichu pomija plik, wypisując jedynie ostrzeżenie w konsoli. Aplikacja się buduje, testy przechodzą, tłumaczeń nie ma. Jedno zdanie w dokumentacji zamyka temat, którego debugowanie kosztowałoby godzinę.

Definicje, które dla wszystkich znaczą to samo. Status zadania mówi o tym, gdzie fizycznie leży kod, a nie o tym, jak bardzo skończona wydaje się praca. Na gałęzi znaczy, że commity powstały, ale nie trafiły jeszcze do gałęzi integracyjnej. W dev znaczy, że są już scalone. Czeka na PROD znaczy, że są scalone, ale klient nadal ich nie widzi, bo została migracja albo krok wdrożeniowy. Wdrożone znaczy tyle i tylko tyle, że gabinet może z danej funkcji korzystać. Kiedy takiego słownika nie ma, każdy podstawia własną interpretację, a słowo „gotowe" przestaje cokolwiek znaczyć.

Reguły, które i tak egzekwuje maszyna. Hook przed commitem blokuje pisanie prosto do gałęzi integracyjnych i formatuje pliki, hook przed pushem uruchamia sprawdzanie typów i testy, a commitlint pilnuje konwencji nazw commitów. Do tego każdy pull request musi nieść wpis w CHANGELOG i aktualizację dokumentacji procesu. Napisanie tego w dokumentacji sprawia, że agent zna reguły, zanim je złamie, a nie po tym, jak hook odrzuci mu pracę.

Warto też zapisać, czego świadomie nie używamy. W Dentrio to sprinty, story pointy i śledzenie czasu. Bez tej listy co jakiś czas ktoś uprzejmie proponuje, że je doda.

Jeden plik, wielu agentów

Kłopot zaczyna się wtedy, gdy w tym samym repozytorium pracuje więcej niż jedno narzędzie. Każde czyta co innego: Claude Code sięga po CLAUDE.md, część agentów po AGENTS.md, Gemini po GEMINI.md, a edytory pokroju Cursora po własnym katalogu z regułami. Trzy kopie tej samej wiedzy rozjeżdżają się w tydzień, a rozjechana dokumentacja jest gorsza od żadnej, bo agent ufa temu, co przeczytał.

Trzymam więc jedno źródło prawdy i resztę sprowadzam do wskaźnika. CLAUDE.md jest plikiem właściwym, a AGENTS.md ma jedną linijkę: zasady tego repozytorium opisuje CLAUDE.md, przeczytaj go, zanim zaczniesz. Brzmi prymitywnie, ale działa w każdym narzędziu i nie wymaga niczego od systemu plików. Dowiązanie symboliczne jest elegantsze, tylko na Windowsie i w części klonów potrafi wylądować w repozytorium jako plik tekstowy ze ścieżką w środku, więc używam go tylko tam, gdzie cały zespół pracuje na tym samym systemie.

Do tego dwie zasady, które oszczędzają kłótnie. Pierwsza: w pliku głównym siedzą wyłącznie fakty o tym repozytorium, czyli komendy, granice modułów, pułapki i definicje. Procedury, które da się powtórzyć gdzie indziej, idą do skilla, bo inaczej ten sam opis wdrożenia mieszka w czterech projektach naraz. Druga: aktualizacja dokumentacji jest częścią pull requesta, tak samo jak wpis w CHANGELOG. Bez tego plik po dwóch miesiącach opisuje architekturę, której już nie ma, a wtedy agent nie tyle zgaduje, co pewnym głosem powtarza nieaktualne rzeczy.

Podział, który się sprawdza

Trzymam to tak: skill to sposób pracy, przenośny między projektami. Dokumentacja repozytorium to wiedza o tym jednym systemie, nieprzenośna. Jeśli fragment CLAUDE.md zmienia się z faktu w procedurę, przenoszę go do skilla, i to samo radzi dokumentacja Claude Code.

Test jest prosty. Wpuść agenta do repozytorium z zadaniem, którego nie zna, i zobacz, o co zapyta. Każde pytanie, które musiałeś odbić, to brakująca linijka w dokumentacji. Po kilku takich rundach zostaje plik, który skraca wdrożenie nowej osoby dokładnie tak samo jak wdrożenie modelu.