Nasze Agent Skills i co jest w środku

Budujemy publiczną bibliotekę Agent Skills: github.com/timerise-ai/skills. Siedem jest już na zewnątrz. Każdy to osobne repozytorium, które uczy agenta kodującego zbudować jeden moduł: centrum pomocy, wielojęzyczny blog, ekrany w lokalu, kiosk samoobsługowy, serwer zapasowy w lokalu, płatności marketplace, polskie e-fakturowanie. Agent Skills to otwarty format, więc ten sam katalog działa w Claude Code, Codex CLI, Gemini CLI i innych agentach, które czytają skills.

Ten wpis opisuje, co w nich faktycznie jest, skąd biorą się reguły w środku i gdzie mają granice. Jeśli chcesz tylko zainstalować któryś, komendy są na dole.

Czym jest skill

Skill to katalog z plikami markdown, który agent czyta, zanim napisze kod. Agent ładuje go, kiedy zadanie pasuje do jego opisu, można go też wywołać wprost. Nic w nim nie jest przypisane do jednego dostawcy. SKILL.md deklaruje nazwę i opis, wszystko poniżej to zwykły markdown o Next.js, Postgresie, Firestore albo czyimś API, a żaden plik nie wywołuje modelu.

To nie jest paczka. Nic nie instaluje się w Twojej aplikacji, nie ma zależności do pilnowania ani licencjonowania. Agent czyta skill i pisze moduł do Twojego repozytorium: w Twoim stacku, z Twoją autoryzacją, Twoim nazewnictwem i Twoim design systemem.

Różnica jest wąska, ale realna. Bez skilla agent napisze centrum pomocy, które wygląda poprawnie. Ze skillem napisze to, które budują nasi inżynierowie, razem z fragmentami, które nabierają sensu dopiero wtedy, gdy wiesz, co poszło źle za pierwszym razem.

Co jest w środku

Wszystkie mają ten sam układ, więc agent, który przeczytał jeden, wie jak czytać kolejny.

Z góry czytany jest tylko SKILL.md. Reszta ładuje się na żądanie, więc zadanie o parowaniu urządzeń nie wciąga do kontekstu rozdziału o rozliczeniach.

Każdy skill ma własną linię wersji i jeden standard wydania: tag vX.Y.Z, wpis w changelogu i release na GitHubie. Indeks opisuje ten standard w STANDARD.md, razem z układem plików i zasadami pisania, które musi spełnić każdy nowy skill.

Skills, które już są

Skąd pochodzą

Skill nie zaczyna się jako pusty dokument, który ktoś zapełnia dobrymi praktykami. Zaczyna się od inżyniera z zespołu, który ten sam moduł budował kilka razy i wie, jak ma się zachowywać.

Spisanie go to osobny przegląd. Inżynier wraca do wcześniejszego wdrożenia, które sam robił, pisze moduł tak, jak zbudowałby go dzisiaj, i każdą własność, którą moduł musi trzymać, zapisuje jako to, co sprawdzają szablony i testy. Co ten przegląd zmienił, co zostało świadomie, a co jest nowe, trafia do provenance.md.

Nic z tego nie jest syntetyczne. Żaden skill nie powstał z promptu do modelu i żaden nie niesie kodu z projektu klienta.

Dlatego część zasad wygląda dziwnie konkretnie. Zahaszuj token urządzenia przed zapisem. Wyślij do przeglądarki podsumowanie wyszukiwania, nigdy cały korpus. Zwiąż NIP sprzedawcy na fakturze z uwierzytelnionym podatnikiem. Żadna z nich nie jest preferencją stylistyczną. Każda pochodzi z prawdziwego wdrożenia, a zapis mówi z którego.

Każdy skill wymienia też krótką listę rzeczy nienegocjowalnych: zasad, które jadą z modułem do każdego projektu. Cała reszta jest do adaptacji i skill jasno mówi, co jest czym.

Co dają

Wniosek zapisuje się raz. Kiedy projekt czegoś nas nauczy, staje się to zasadą w skillu, a nie commitem w jednym repozytorium. Wszystko, co budujemy potem, zaczyna od tego miejsca. Bez tej pętli ta sama droga jest przechodzona od nowa w każdym projekcie.

Moduł jest udokumentowany, zanim powstanie. Skill jest dokumentacją. Przy przekazaniu projektu deweloperzy, którzy go przejmują, dostają uzasadnienia stojące za kodem, a nie sam kod.

Mniej w wycenie jest zgadywania. Duża część systemu rezerwacyjnego to praca, którą już wykonaliśmy, w formie, którą agent potrafi odtworzyć. Do oszacowania zostaje logika, która faktycznie różni się między projektami, czyli też ta ciekawsza inżyniersko.

Code review jest krótsze. Łatwiej przeglądać wygenerowany kod, kiedy zasady, których miał się trzymać, są spisane. Zamiast dyskutować, czy podejście jest sensowne, sprawdzasz je z listą.

Możesz przeczytać części, zanim się zdecydujesz. Indeks jest publiczny i każdy skill w nim też. To, z czego zbudowany jest system Timerise, da się sprawdzić z góry, bez pytania nas o to.

Zainstalowany samodzielnie skill daje Ci wersję po przeglądzie. Nie moduł napisany od zera, który wygląda wiarygodnie, tylko taki, jak buduje go inżynier, który wdrażał go wiele razy, z poprawkami już w środku.

Czego nie zrobią

Warto wiedzieć, zanim któryś sklonujesz.

Zakładają Next.js App Router. Model danych i zasady utrzymaniowe przeniosą się wszędzie. Rozdziały o routingu i renderowaniu już nie. Wyjątkiem jest island-mode-server, który buduje serwer w Node stojący obok aplikacji, a nie w niej.

To instrukcje, nie paczka. Kiedy agent napisze moduł, kod jest Twój. Nie ma wersji w Twojej aplikacji do podbicia, a późniejszy git pull w katalogu skilla poprawia następną rzecz, którą zbudujesz, a nie tę, którą już masz.

Nadal przeglądasz wynik. Skill mocno zawęża przestrzeń błędnych odpowiedzi. Nie zdejmuje z Ciebie code review i nie zamienia agenta w inżyniera.

Backend wybierasz sam. Warstwa danych siedzi za jawnym stykiem, a Firestore, Supabase/Postgres i własny adapter są opisane obok siebie. Wybór i adaptacja są po Twojej stronie, nie po stronie skilla.

ksef odstaje od reszty. Opakowuje cudze API, a nie moduł UI, więc zaczyna się od specyfikacji Ministerstwa Finansów poprawionej o zgłoszenia z działającej integracji, a zapisem poprawek jest changelog, nie provenance.md.

Instalacja

Najkrócej przez CLI z skills.sh. Bierze repozytorium z GitHuba wprost i zapisuje skill do tych agentów, których wskażesz, bez ręcznego klonowania i bez pamiętania ścieżek:

Możesz też sklonować skill sam. Do katalogu skills w Claude Code:

Żeby ograniczyć go do jednego projektu, sklonuj go do katalogu .claude/skills/ w tym projekcie. Skill włącza się sam, kiedy zadanie do niego pasuje, można go też wywołać komendą slash: /help-center-markdown. Aktualizujesz przez git pull w jego katalogu, a CHANGELOG.md mówi, co się zmieniło.

Codex CLI, Gemini CLI i inni agenci

Codex CLI i Gemini CLI czytają ten sam układ, razem z ładowaniem references/ na żądanie, dzięki któremu długi skill nie zjada kontekstu. Obydwa szukają skills w ~/.agents/skills:

Jeśli skill jest już sklonowany dla Claude Code, zrób dowiązanie zamiast drugiej kopii, żeby jedno git pull aktualizowało wszystkich agentów:

Wywołanie wygląda inaczej: $ksef w Codeksie, /skills w Gemini CLI. Dwie rzeczy też nie przenoszą się same. Każdy host po swojemu dopasowuje zadanie do opisu, więc za pierwszym razem wywołaj skill wprost, zamiast zakładać, że sam się włączył. A rzeczy nienegocjowalne z references/adaptation.md to miejsce, w którym modele różnią się najmocniej, więc sprawdź, czy te ważne dla Twojego modułu przetrwały budowę.

Dlaczego są publiczne

Nie sprzedajemy skills, wszystkie są na licencji MIT i żaden nie zawiera niczego specyficznego dla klienta.

Nasi klienci mają kod na własność, więc uznaliśmy, że części, z których jest złożony, powinny dać się przeczytać bez pytania nas o zgodę. Poza tym moduł jest bardziej użyteczny udostępniony niż trzymany u siebie. Każda poprawka zrobiona w projekcie wraca do skilla, a to samo repozytorium instaluje każdy inny.

O reszcie tego, jak pracujemy, piszemy w Jak budujemy.

Co dalej

Kolejne skills, dodawane w miarę jak nasi inżynierowie spisują moduły, które wdrażali. Każdy trafia do indeksu w dniu publikacji, więc obserwuj repozytorium, jeśli chcesz je widzieć na bieżąco. Cała paczka trafia też na skills.sh, otwarty katalog Agent Skills, żeby dało się je znaleźć obok reszty ekosystemu.