Nasze Claude Code skills i co jest w środku

Opublikowaliśmy pięć Claude Code skills na github.com/timerise-ai/skills. Każdy to osobne repozytorium, które uczy agenta kodującego zbudować jeden moduł: centrum pomocy, wielojęzyczny blog, ekrany w lokalu, płatności marketplace, polskie e-fakturowanie.

Ten wpis opisuje, co w nich faktycznie jest, skąd pochodzą 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. Claude Code ładuje go, kiedy zadanie pasuje do jego opisu, można go też wywołać komendą slash.

To nie jest biblioteka. 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 mamy na produkcji, razem z fragmentami, które nabierają sensu dopiero wtedy, gdy wiesz, co poszło źle za pierwszym razem.

Co jest w środku

Wszystkie pięć ma 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.

Pięć skills

Skąd pochodzą

Skill nie zaczyna się jako pusty dokument, który ktoś zapełnia dobrymi praktykami. Zaczyna się jako moduł w systemie, który już działa u klienta.

Wyjęcie go to audyt. Czytamy oryginalny kod, znajdujemy, co jest w nim nie tak, i zapisujemy w skillu wersję poprawioną. Każdy błąd, który ten audyt znajdzie, trafia do provenance.md, obok zasady, która go od teraz uniemożliwia.

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 to błąd, za który ktoś już zapłacił, a zapis mówi który.

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ą

Błąd naprawia się raz. Kiedy projekt trafi na defekt, poprawka staje się zasadą w skillu, a nie commitem w jednym repozytorium. Następny projekt już tego błędu nie ma. Bez tej pętli zespół po cichu odtwarza te same pomyłki u kolejnych klientów.

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ę poprawioną. Nie moduł napisany od zera, który wygląda wiarygodnie, tylko ten, który przeszedł przez produkcję, z wyprostowanymi już defektami.

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.

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

Sklonuj skill do swojego 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.

Dlaczego są publiczne

Nie sprzedajemy skills i żaden z nich 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 moduły stabilizują się na produkcji. Każdy trafia do indeksu w dniu publikacji, więc obserwuj repozytorium, jeśli chcesz je widzieć na bieżąco.