Paprykę kupiłem trzy razy, bo trzymałem ją w trzech miejscach.
W mieszkaniu była już półka na przyprawy nad płytą kuchenną. Kiedy się zapełniła, zrobiłem miejsce w szufladzie. Potem doszła półka w spiżarni. Każde z tych rozwiązań miało sens, kiedy je wprowadzałem. Wszystkie razem sprawiły, że paprykę zaskakująco trudno było znaleźć.
Problem wyszedł na jaw, kiedy gotował u mnie znajomy. Cały wieczór stałem mu za plecami: dobra patelnia jest pod zlewem, ta sól jest gruboziarnista, piekarnik grzeje za mocno. Gotuje lepiej ode mnie. Potrzebował tylko wskazówek, jak poruszać się po mojej kuchni.
W sierpniu zrozumiałem, że to samo zrobiłem z naszymi repozytoriami.
Zdublowane zasady
W projektach OwlMeans oprócz kodu źródłowego są instrukcje dla agenta programistycznego: gdzie co leży, jakie polecenia uruchamiać i co musi przetrwać edycję.
Obsługiwaliśmy Claude Code i GitHub Copilota. Zasada dla jednego stawała się umiejętnością w .claude/skills/, a drugi dostawał jej kopię w .github/instructions/. Mapy projektu, skrypty powłoki i pamięć dorobiły się własnych bliźniaków.
Jeden commit zmieniał dwanaście plików umiejętności i jedenaście ich lustrzanych wersji. Każdej poprawce towarzyszyło drobne pytanie: czy poprawiłem też drugą kopię?
Przy porządkach w OwlMeans Common zniknęło 213 zdublowanych plików z instrukcjami. Ta liczba opisuje zmianę w naszym repozytorium. Nie mówi nic o tym, o ile szybszy stał się agent.
Zastąpił je jeden kanoniczny folder .agents/ i AGENTS.md w katalogu głównym. Swoje miejsce dostały umiejętności, zasady, skrypty i wspólna pamięć. Pliki przeznaczone dla konkretnych agentów stały się pomostami do tego źródła.
Wspólny format
AGENTS.md przekazuje agentowi instrukcje projektu w zwykłym pliku Markdown. Specyfikacja Agent Skills określa strukturę folderu umiejętności i jego pliku SKILL.md.
Każde z nich rozwiązuje inny problem. Plik w katalogu głównym mówi agentowi, jak pracować w tym repozytorium. Umiejętność zawiera procedurę, którą agent może wczytać do konkretnego zadania.
Specyfikacja umiejętności nie narzuca katalogu nadrzędnego. Wybór .agents/skills/ to nasza konwencja, dobrana pod narzędzia, których używaliśmy. Nie powinienem przedstawiać tego katalogu tak, jakby każdy agent obiecał go odnajdywać.
O tej różnicy trzeba pamiętać, kiedy dodajesz kolejne narzędzie. Wspólny tekst pomaga tylko wtedy, gdy narzędzie rzeczywiście go wczytuje.
Pomost dla Claude’a
W sierpniowej konfiguracji zostawiliśmy mały plik CLAUDE.md, którego pierwszą instrukcją było @AGENTS.md. Skrypt generował w .claude/skills/ po jednym dowiązaniu symbolicznym na każdą umiejętność.
Dzięki temu Claude Code dostawał oczekiwane punkty wejścia, a my nie mieliśmy kolejnego zestawu instrukcji do utrzymania. Dowiązania odświeżał hook sesji.
Do osobnych dowiązań dla każdej umiejętności doszliśmy w testach. Dowiązanie całego katalogu umiejętności w naszej konfiguracji nie zadziałało. To obserwacja dotycząca tamtego układu, a nie trwała reguła dla każdej przyszłej wersji Claude Code.
Zgłoszenie z prośbą o natywną obsługę AGENTS.md sprawdziłem ponownie 15 października 2026 r. Wciąż było otwarte. Jeśli instalujesz to dziś, zajrzyj do aktualnej dokumentacji pamięci Claude Code i sprawdź, co narzędzie faktycznie wczytuje. Nasz pomost wprost wskazuje źródło, które importuje.
Instrukcje warte zachowania
Przenosząc pliki, pozbyłem się duplikatów. Ich treść nie stała się jednak przez to przydatna.
Ogólna umiejętność o pisaniu dobrego kodu niewiele powie agentowi o naszych punktach wejścia czy slotach projektu. Przydatne instrukcje objaśniają tę konkretną bazę kodu: który pakiet odpowiada za zasób, jakiej granicy zmiana nie może naruszyć i która kontrola wyłapie błąd.
Pakiety OwlMeans Common trzymają wytyczne tuż obok kodu. Wygenerowany projekt może je zainstalować przez @owlmeans/agent-skills. Metadane pakietu dostarczają instrukcji, a repozytorium – lokalnego kontekstu.
Jedno i drugie ktoś nadal musi utrzymywać.
U nas obowiązuje zasada: po większej zaplanowanej pracy wracamy do odpowiednich umiejętności. Jeśli zmieniło się polecenie, ścieżka albo zachowanie, przepisz instrukcję, która je opisuje. Umiejętność podaje obowiązującą zasadę. Datowana notka, że stara zasada przestała działać, każe następnemu agentowi rozstrzygać, który akapit wygrywa.
To kosztuje. Bywa, że kod przechodzi już kontrole, a zadanie wymaga jeszcze pracy nad dokumentacją. Wolę jednak zapłacić tę cenę, póki pamiętam, dlaczego implementacja się zmieniła.
Pamięć według podsystemów
W pamięci duplikacja miała inną postać. Prowadziliśmy kronikę zadań.
Plik nazwany od jakiejś analizy mówił mi, co działo się w tamtym tygodniu. Żeby ustalić, co obecnie obowiązuje w routingu, musiałem przeczytać kilka takich analiz i rozgryźć, która z nich zastąpiła pozostałe.
Ułożyliśmy pamięć na nowo według części projektu: routing, tłumaczenia, wdrożenie, usługi zewnętrzne. Indeks przypisuje te węzły do ścieżek, które obejmują. Agent najpierw czyta tę mapę, a potem otwiera właściwe węzły.
Zapis aktualizuje odpowiedni fakt tam, gdzie już jest, zamiast dopisywać kolejną datowaną relację pod nieaktualną. Praca, która jeszcze trwa, może mieć datę, ale ustalone wytyczne nie powinny zmuszać do odtwarzania przebiegu sesji.
W repozytorium platformy dwadzieścia plików chronologicznych zamieniło się w jedenaście węzłów strukturalnych. Tyle naliczyliśmy w trakcie reorganizacji. Pożytek był taki, że wiedziałem, gdzie szukać.
Pamięć wciąż wymaga poprawiania. Jej kształt nie uchroni przed zapisaniem błędnego założenia, a krótki indeks nie zagwarantuje, że agent wczyta właściwą stronę. Za to mamy miejsce, w którym naprawimy założenie, kiedy je znajdziemy.
Dwa tygodnie
Reorganizacja zajęła dwa tygodnie. Część tego czasu poświęciłem konwencjom katalogów, a część drobnym problemom ze zgodnością, które wychodzą dopiero wtedy, gdy uruchamiasz innego agenta.
Projekty generowane przez OwlMeans mają wytyczne dla agentów. W ramach Usług dopasowujemy też umiejętności i metadane do dostarczanego projektu. Żeby te wytyczne dalej się przydawały, musi o nie dbać ten, kto utrzymuje repozytorium.
Znajomy nadal musi wiedzieć, że piekarnik grzeje za mocno. Przynajmniej mam teraz jedno miejsce, w którym mogę to zapisać.
Pierwsza publikacja: 13 sierpnia 2026 r. Poprawiono 15 października 2026 r., żeby oddzielić wspólne formaty od naszej konwencji katalogów i opatrzyć datami obserwacje dotyczące zgodności narzędzi.