Przez jakieś dwa lata moja kuchnia działała na trzech systemach. Półka na przyprawy, która przyszła razem z mieszkaniem, przykręcona do ściany nad płytą. Szuflada, którą sam zorganizowałem, kiedy półka się zapełniła. I półka w spiżarni na wszystko, co nie zmieściło się ani tu, ani tam.
We wszystkich trzech była papryka. Wiem, bo kupiłem ją trzy razy.
To nie katastrofa; da się z tym żyć. Złamała mnie sobota, kiedy u mnie gotował kolega, a ja przez cały wieczór stałem za jego plecami — nie, dobra patelnia jest pod zlewem, ta sól jest gruboziarnista, daj połowę, piekarnik grzeje za mocno. Gotuje lepiej ode mnie. Po prostu nie potrafił pracować w mojej kuchni beze mnie w środku.
Dwa tygodnie temu zrozumiałem, że nasze repozytoria są dokładnie w tym stanie.
Trzy półki, jedna kuchnia
OwlMeans Common to biblioteka, na której stoi każdy projekt, jaki budujemy, a każdy z tych projektów buduje agent. Repozytorium nie zawiera więc samego kodu — zawiera też instrukcje, które agent czyta w pierwszej kolejności: jak układamy rzeczy, czego nigdy nie wolno robić, który skrypt za co odpowiada.
Wspieraliśmy dwa agenty, Claude Code i GitHub Copilota, a każdy chciał własnej półki. Więc każda reguła powstawała dwa razy — raz jako .claude/skills/<nazwa>/SKILL.md, raz jako .github/instructions/<nazwa>.instructions.md. Dwa zawsze wczytywane pliki kontekstu, będące niemal kopiami. Dwie mapy repozytorium. Ten sam skrypt powłoki leżący bajt w bajt w dwóch katalogach. Dwa foldery pamięci, po cichu rozjeżdżające się.
Podatek widać wprost w historii: jeden commit z tamtego okresu dotyka dwunastu plików umiejętności i ich jedenastu zdublowanych bliźniaków. Nikt nie uznał, że to dobry pomysł. To narosło — tak jak narasta trzecia półka na przyprawy.
Jedna półka, jedna karteczka
Więc to wyrwałem. Wszystko trafiło do jednego folderu — .agents/, mieszczącego umiejętności, reguły, skrypty i pamięć — a wszystko, co agent musi przeczytać przed startem, trafiło do jednego pliku w katalogu głównym: AGENTS.md. W OwlMeans Common skasowało to dwieście trzynaście zdublowanych plików instrukcji. CLAUDE.md, wcześniej osiemdziesiąt sześć linii wszystkiego, ma dziś sześćset bajtów.
Nie wymyśliłem tej półki. Wziąłem tę, na którą wszyscy zdążyli się już umówić — a to, jak się umówili, jest powodem, dla którego jej ufam.
W maju 2025 Amp zaproponował jeden plik o nazwie AGENT.md, w liczbie pojedynczej. Potem OpenAI wybrało dla Codeksa liczbę mnogą — i w tej mnogości tkwi sedno, bo jeden plik dzieli między siebie wiele agentów. Amp mógł walczyć o swoją nazwę. Zamiast tego napisali: „zamiast upierać się przy tym, co sami wymyśliliśmy, uznaliśmy, że wolimy jeden standard” — pod warunkiem, że OpenAI zabezpieczy domenę agents.md. OpenAI to zrobiło, a Amp się przesiadł.
Z dwudziestu tysięcy repozytoriów w sierpniu 2025 urosło do ponad sześćdziesięciu tysięcy dzisiaj, a w grudniu standard trafił do Agentic AI Foundation pod skrzydłami Linux Foundation. Dwadzieścia trzy narzędzia czytają go dziś natywnie — Codex, Cursor, Copilot, Gemini CLI, Zed, Windsurf, Devin, Jules, Aider.
Druga połowa półki przyszła z przeciwnej strony. Agent Skills — format SKILL.md — należał do Anthropic i został otwarty jako publiczna specyfikacja w grudniu 2025, pod opieką tej samej fundacji. Definiuje dokładnie, jak wygląda folder umiejętności, i nie mówi ani słowa o tym, gdzie ten folder ma leżeć. Więc każdy dostawca wybrał sobie katalog nadrzędny. Codex skanuje .agents/skills. Copilot akceptuje .agents/skills. To przesądziło sprawę.
Gość, który przynosi własne noże
Jeden agent nie czyta karteczki na drzwiach.
Claude Code czyta CLAUDE.md i wyłącznie CLAUDE.md. Prośba, żeby czytał również AGENTS.md, wisi od marca — zgłoszenie #34235 w repozytorium Claude Code, w wątku z tysiącami głosów poparcia — i wisi nadal. Co jest o tyle zabawne, że to Anthropic napisał format umiejętności leżący w drugiej połowie tego samego folderu.
Kuszące rozwiązanie to druga kopia. Każdy, kto próbował, opowiada to samo zakończenie: dwa pliki edytowane ręcznie zawsze się rozjeżdżają, a plik instrukcji, który rozjechał się z rzeczywistością, jest gorszy niż jego brak, bo agent w niego wierzy.
Zbudowaliśmy więc mostek. CLAUDE.md przetrwał — sześćset dziesięć bajtów, bajt w bajt identyczne w każdym repozytorium — a jego pierwsza linia to @AGENTS.md. Reszta to notatka mówiąca, że umiejętności mieszkają w .agents/skills/ i nigdy nie wolno pisać ich gdzie indziej. Mały skrypt powłoki generuje potem po jednym symlinku na umiejętność do ignorowanego przez gita .claude/skills/, a hook sesji odtwarza je przy każdym uruchomieniu. Po jednym na umiejętność, nie na katalog — Claude Code przyjmuje zasymlinkowany wpis umiejętności, ale nie zasymlinkowany folder umiejętności; takich rzeczy dowiadujesz się wyłącznie przez próbę.
Przepisy moją własną ręką
Druga zmiana znaczy więcej niż folder.
Książka kucharska mówi: piec dwadzieścia pięć minut w stu osiemdziesięciu stopniach. Karteczka w mojej szafce mówi: dwadzieścia dwie minuty, tylna lewa strona, ten piekarnik grzeje za mocno. Obie są prawdziwe; tylko jedna dotyczy mojej kuchni.
Projekty OwlMeans nie instalują generycznych umiejętności — każdy hoduje własne. Nasze repozytorium platformy ma ich dziewiętnaście, stojące obok repozytorium agenta dwadzieścia trzy, a tam, gdzie nazwy się pokrywają, treść już nie: execution w jednym znaczy abstrakcję, w drugim jej użycie po stronie platformy. To nie duplikacja. To dwie różne kuchnie.
Kłopot z karteczką przyklejoną do drzwi polega na tym, że piekarniki się zmieniają. Harness domyka więc pętlę. Zatwierdzenie planu jest jednocześnie zatwierdzeniem przebiegu, który po nim następuje: kiedy praca ląduje, agent wraca po śladach do umiejętności, których dotknęła, przepisuje te, które przestały być prawdą, a raport końcowy musi zawierać tabelę tego, co zaktualizował, co utworzył i co niczego nie wymagało — z uzasadnieniem. Raport bez tej tabeli liczy się jako niedokończony.
Jeszcze jedna reguła, którą polubiłem bardziej, niż się spodziewałem: umiejętność opisuje reguły obowiązujące teraz, nigdy to, co się zmieniło. Żadnych datowanych biuletynów, żadnego dawniej X, teraz Y. Sprawdzian jest taki, że gotowa umiejętność ma się czytać tak, jakby ta funkcja zawsze wyglądała właśnie tak.
Półki według dania, nie według daty zakupów
Trzecia zmiana to ta, której oddałbym się ostatniej.
Agenci mają dziś pamięć, a zostawieni sami sobie prowadzą ją jak pamiętnik. Nasza tak właśnie wyglądała — pliki nazwane od tego, co się wydarzyło, w rodzaju slot-status-reconciler.md albo null-error-investigation.md, każdy zaczynający się od tego, co robiliśmy w danym tygodniu. To lista zakupów. Doskonale zapisuje, kiedy coś kupiłeś, i nie mówi nic o tym, czego potrzebuje dzisiejsza kolacja.
Przegrupowaliśmy więc półki według dań. Węzeł pamięci nazywa się dziś od realnej części projektu — podsystemu, zagadnienia w rodzaju routingu czy tłumaczeń, usługi zewnętrznej albo samego repozytorium — i nigdy od zdarzenia, daty czy zadania. Jego treść dzieli się na to, co jest prawdą, co musi być spełnione, co potrafi ugryźć i gdzie szukać, a daty są dopuszczone dokładnie w jednej sekcji: przy pracy będącej w toku.
Prawdziwą robotę wykonuje indeks. Najwyżej pięćdziesiąt linii, jedna na węzeł, każda ze ścieżkami, które ten węzeł obejmuje. Agent czyta go na starcie sesji i nic poza tym; kiedy przychodzi zadanie, dopasowuje jego ścieżki do tych linii i otwiera ten jeden czy dwa węzły, które pasują. Nigdy nie czyta całego magazynu.
A zapisy są scaleniami. Kiedy coś się zmienia, przepisujesz linię na miejscu — nigdy nie dopisujesz pod spodem datowanej poprawki, bo wtedy plik po cichu znowu staje się pamiętnikiem. Nasze repozytorium platformy przeszło z dwudziestu chronologicznych plików do jedenastu strukturalnych węzłów i szukanie czegokolwiek przestało być wykopaliskami.
Możesz to po prostu mieć
Zrób krok w tył, a nic z tego nie jest egzotyczne. Jeden folder zamiast trzech. Karteczka na drzwiach mówiąca, jak działa to miejsce. Przepisy własną ręką, utrzymywane na bieżąco. Półki pogrupowane według tego, co naprawdę gotujesz.
I tak kosztowało to dwa tygodnie, z czego większość poszła na rzeczy, których nie da się wyszukać — że standard istnieje i który z nich wygrał, że zasymlinkowany katalog umiejętności zawodzi tam, gdzie symlinki na pojedyncze umiejętności działają, że pamięć uporządkowana wokół zdarzeń gnije, a uporządkowana wokół struktury nie.
Więc uczciwa oferta.
Jeśli budujesz z agentem cokolwiek prawdziwego, dojdziesz do tego samego. Dodasz drugiego agenta i zaczniesz pisać wszystko dwa razy. Wyhodujesz folder pamięci, który czyta się jak pamiętnik, którego nikt nie chce otwierać. Możesz zrobić to, co ja, i spalić dwa tygodnie. Mnie się to opłaciło — to moja praca.
To nie jest Twoja praca.
To właśnie dostarcza OwlMeans. Każdy projekt zbudowany przez Platformę wychodzi z harnessem już w środku — .agents/, AGENTS.md, umiejętności skrojone pod ten projekt, graf pamięci w kształcie jego własnego kodu — a OwlMeans Services dokłada to samo do kodu, który już masz. Wszystko należy do Ciebie. Żadnego vendor lock-inu i żadnego agenta-gospodarza: Codex, Copilot, Claude Code, cokolwiek pojawi się w przyszłym kwartale — wszyscy czytają tę samą półkę.
Każdy kucharz, każda kuchnia. Pomiń moje dwa tygodnie — możesz to po prostu mieć.
OwlMeans buduje pełnostackowe aplikacje TypeScript SaaS na podstawie Twoich historyjek użytkownika — typowane, gotowe na SSO i Twoje do dalszego rozwijania z dowolnym agentem. Zobacz, co potrafi →