Jak zbudować skill dla agenta SI. Instruktaż od pustego folderu do pełnej automatyzacji

Przez ostatni rok nauczyłem mojego agenta SI wielu rzeczy, których żaden model nie ma w standardzie. Zbudowałem między innymi takie skille jak zbieranie faktur z różnych skrzynek pocztowych i katalogowanie ich na Dysku Google, kontrola, czy do każdej operacji na wyciągu bankowym istnieje dokument, redagowanie tekstów na tego bloga, ich publikacja na stronie oraz generowanie wersji audio. W tym tekście pokażę Ci, jak działa mechanizm skilli, jak zbudujesz swój pierwszy skill i jak z czasem rozbudujesz go do poziomu, na którym agent obsługuje pełne przepływy z zewnętrznymi API i bazami danych. Po drodze podzielę się wnioskami z własnych wdrożeń, także tymi, do których dochodziłem dłużej, niż wypada się przyznać.

Zacznijmy od rozbrojenia samego słowa. Skill nie jest żadną magią, wtyczką ani osobnym programem. To zwykły folder z plikiem tekstowym w środku. Ten plik nazywa się SKILL.md i zawiera instrukcję napisaną ludzkim językiem, dokładnie taką, jaką napisałbyś dla nowego pracownika w pierwszym dniu pracy. Najlepsza analogia, jaką znam, brzmi właśnie tak, że skill to przewodnik wdrożeniowy dla nowego członka zespołu. Nowy pracownik jest inteligentny i zna swój fach, ale nie zna Twojej firmy. Nie wie, że oferty piszesz według konkretnego szablonu, że klientów, którzy nie podpisali zlecenia, nie przenosi się w lejku sprzedaży do wygranych, nawet jeśli potwierdzili współpracę, a faktury od jednego uciążliwego dostawcy przychodzą zawsze z tygodniowym opóźnieniem. Agent SI jest w identycznej sytuacji. Model wie, jak się programuje i jak wygląda faktura, ale nie wie, jak to się robi u Ciebie. Skill jest miejscem, w którym mu to opowiadasz, raz, a nie w każdej rozmowie od nowa.

Jest w tym mechanizmie jeden pomysł, który robi całą różnicę, i warto go zrozumieć, zanim napiszesz pierwszą linijkę. Nazywa się progressive disclosure, czyli stopniowe odsłanianie. Agent nie trzyma wszystkich Twoich instrukcji w głowie przez cały czas, bo jego pamięć robocza, czyli okno kontekstu, jest zasobem wspólnym i drogim. Na starcie sesji agent widzi tylko wizytówki skilli, to znaczy nazwę i jednozdaniowy opis każdego z nich. Dopiero gdy uzna, że zadanie pasuje do opisu, sięga po pełną instrukcję. A jeśli instrukcja odsyła do dodatkowych plików, przeczyta je tylko wtedy, gdy naprawdę będą potrzebne. Możesz więc zbudować skill z setkami stron materiałów pomocniczych, a agent zapłaci pamięcią tylko za te strony, po które faktycznie sięgnie. To trochę jak z segregatorem procedur w firmie. Nikt nie czyta go codziennie od deski do deski, ale każdy wie, że stoi na półce i co mniej więcej jest w którym rozdziale.

Wyjaśnię jeszcze, dlaczego w ogóle uprawiamy tę gimnastykę, zamiast wgrać agentowi całą wiedzę od razu. Okno kontekstu działa jak biurko o skończonej powierzchni, a wszystko, co na nie trafi, leży tam do końca rozmowy. Na tym samym blacie musi się zmieścić Twoje polecenie, dotychczasowa wymiana zdań, treść plików, nad którymi właśnie pracujesz, i wyniki uruchamianych narzędzi. Każdy akapit instrukcji wgrany na zapas zabiera miejsce właściwej pracy. Nie chodzi przy tym wyłącznie o pojemność. Model czyta całe to biurko od nowa przy każdej swojej odpowiedzi, więc za nadmiar płacisz nie raz, a przy każdym obrocie rozmowy. Co gorsza, agent przeciążony materiałem zaczyna gubić polecenia, bo im więcej rzeczy leży w kontekście na wszelki wypadek, tym łatwiej przeoczyć tę jedną naprawdę ważną. Zauważysz to zresztą sam, bo długo prowadzona rozmowa z agentem robi się z czasem dziwnie rozkojarzona i to jest dokładnie ten mechanizm. Przy dziesięciu skillach, z których każdy ma po kilkaset linii, wgranie wszystkiego na start pochłonęłoby budżet uwagi agenta, zanim doczytałby Twoje pierwsze zdanie. Dlatego w pamięci na stałe mieszkają tylko wizytówki, a instrukcje, referencje i narzędzia czekają na dysku, gotowe do użycia i nic niekosztujące, dopóki nikt po nie nie sięga. Powolne doładowywanie nie jest więc fanaberią inżynierów, tylko warunkiem tego, żeby agent z dziesiątkami skilli myślał równie jasno jak agent z jednym.

Twój pierwszy skill

Dość teorii, zbudujmy coś. Załóż w swoim projekcie folder skills/przygotowanie-ofert, a w nim plik SKILL.md. Dokładna lokalizacja zależy od środowiska, w którym pracuje Twój agent, bo każde ma swój katalog skilli i samo go przeszukuje; jedno zdanie w dokumentacji Twojego narzędzia rozstrzygnie, gdzie go założyć. Do środka wpisz coś takiego.

---
name: przygotowanie-ofert
description: Przygotowuje oferty handlowe firmy wedlug obowiazujacego
  szablonu i biezacych cen z CRM. Uzyj zawsze, gdy user prosi o oferte,
  wycene, propozycje wspolpracy albo odpowiedz na zapytanie ofertowe.
---

# Przygotowanie oferty

Zanim zaczniesz pisac, ustal z userem trzy rzeczy: dla kogo jest oferta,
czego dotyczy i do kiedy ma byc wazna. Nie zgaduj, zapytaj.

Uklad i styl oferty bierz z pliku szablon-oferty.md, ktory lezy obok
tej instrukcji. Przeczytaj go przed pisaniem i trzymaj sie jego sekcji.

Przy ofercie nietypowej, na przyklad lacznej wycenie kilku uslug,
zajrzyj dodatkowo do pliku przyklady-ofert.md. Przy zwyklej ofercie
nie jest Ci potrzebny.

Ceny pobieraj WYLACZNIE narzedziem pobierz-ceny.py, uruchamiajac:
python pobierz-ceny.py --produkt <nazwa>. Skrypt laczy sie po API
z naszym CRM i zwraca biezaca cene. Nie czytaj jego kodu, nie bierz cen
z pamieci ani ze starych ofert. Jesli narzedzie nie zna produktu,
oznacz pozycje jako "do wyceny indywidualnej" i wypisz na koncu.

Przed oddaniem oferty sprawdz liste kontrolna: czy kazda pozycja ma cene
z narzedzia, czy jest data waznosci, czy dane firmy sa zgodne ze stopka
w szablonie. Jesli cokolwiek sie nie zgadza, popraw i sprawdz jeszcze raz.

Gotowa oferte pokaz userowi do akceptacji. Nie wysylaj niczego sama.

Obok połóż trzy pliki, szablon-oferty.md z układem dokumentu, przyklady-ofert.md z wzorami nietypowych wycen i narzędzie pobierz-ceny.py, które łączy się po API z Twoim CRM i zwraca bieżące ceny. I to jest wszystko. Właśnie zbudowałeś skill z kompletną architekturą, jaką stosują duże wdrożenia, bo masz w nim instrukcję główną, referencje wczytywane na żądanie, narzędzie uruchamiane zamiast czytane, punkt kontrolny z człowiekiem i pętlę sprawdzania własnej pracy. Od teraz, gdy poprosisz agenta o ofertę, sam sięgnie po tę procedurę. A gdybyś chciał mieć pewność, możesz go wywołać ręcznie, wpisując nazwę skilla po ukośniku.

Zatrzymajmy się przy nagłówku pliku, bo te kilka linijek między kreskami decyduje o wszystkim. Pole name to identyfikator pisany małymi literami, cyframi i dywizami, do 64 znaków. Pole description może mieć do 1024 znaków i jest jedyną rzeczą, którą agent widzi, zanim zdecyduje się otworzyć Twoją instrukcję. Z moich doświadczeń i z doświadczeń setek osób, które dzielą się wdrożeniami w sieci, wyłania się tu zgodny wniosek. Opis ma mówić dwie rzeczy, co skill robi i kiedy go użyć, i ma być napisany w trzeciej osobie, jak wpis w katalogu, a nie jak rozmowa. Ma też być, nie bójmy się tego słowa, nachalny. Agenty bywają nieśmiałe w sięganiu po skille i potrafią zignorować idealnie pasujący, jeśli opis jest zbyt delikatny. Dlatego zamiast "pomaga przy dokumentach" napisz "przygotowuje oferty handlowe, użyj zawsze, gdy user prosi o ofertę, wycenę albo odpowiedź na zapytanie". Wymień słowa, którymi ludzie naprawdę opisują to zadanie, bo to po nich agent rozpoznaje sytuację. Sam przeszedłem etap, na którym mój skill leżał nieużywany jak karnet na siłownię, i w dziewięciu przypadkach na dziesięć winny był właśnie zbyt skromny opis.

Druga rzecz, która decyduje o jakości, jest przeciwintuicyjna, bo polega na pisaniu mniej. Model jest już mądry. Wie, czym jest PDF, jak działa poczta i co to jest marża. Każde zdanie w skillu powinno przejść prosty test, którego nauczyła mnie praktyka, a który dokumentacje czołowych dostawców agentów podnoszą do rangi zasady. Zadaj sobie pytanie, czy agent zrobiłby to samo bez tego zdania. Jeśli tak, skasuj je. Instrukcja główna powinna zmieścić się grubo poniżej pięciuset linii, a wszystko, co potrzebne tylko czasami, powinno wyjechać do osobnych plików, do których SKILL.md jedynie odsyła. Tu jedna praktyczna uwaga, na którą sam się naciąłem. Odsyłacze powinny prowadzić z instrukcji głównej bezpośrednio do pliku docelowego, bez łańcuszków, w których plik A odsyła do B, a B do C, bo w takich łańcuszkach agent czyta pliki wyrywkowo i gubi resztę. Warto też wiedzieć, że skille używane przez wiele osób obrastają osadem, czyli warstwami dopisków, których nikt nie ma odwagi skasować. Przeglądaj je co jakiś czas z tą samą bezwzględnością, z jaką sprzątasz garaż. Materiał ważny dla jednej gałęzi zadania przenieś do tej gałęzi, materiał nieaktualny wyrzuć bez sentymentów.

Jest jeszcze jedno pokrętło, o którym mało kto mówi wprost, a które dokumentacja nazywa stopniami swobody. Chodzi o to, ile wolności zostawiasz agentowi w danym kroku. Wyobraź sobie robota idącego przez teren. Tam, gdzie teren jest otwartym polem, wystarczy wskazać kierunek, bo wiele dróg prowadzi do celu i agent sam wybierze sensowną. Tak jest z przeglądem kodu albo z researchem. Ale tam, gdzie ścieżka jest wąskim mostkiem nad przepaścią, na przykład przy migracji bazy danych albo wysyłce czegokolwiek do klienta, instrukcja ma podawać dokładną komendę i zabraniać improwizacji. Dobry skill świadomie miesza oba tryby. Mój skill od ofert zostawia agentowi swobodę w redagowaniu tekstu, ale ceny każe pobierać wyłącznie narzędziem z CRM, a wysyłkę blokuje całkowicie. Swoboda w słowach, dyscyplina w liczbach.

Cztery reguły pisania skilli

Doszliśmy teraz do punktu, w którym opiszę cztery kluczowe reguły. Powinieneś o nich pamiętać za każdym razem, gdy piszesz skill, a nazywają się kolejno wyzwalacz, struktura, sterowanie i przycinanie.

Wyzwalacz to świadoma decyzja, kto uruchamia skill. Możesz zostawić tę decyzję agentowi, który sam po niego sięgnie, gdy opis pasuje do zadania, albo zarezerwować ją dla siebie i wywoływać skill wyłącznie ręcznie. Żadna z opcji nie jest darmowa. Skill uruchamiany przez agenta obciąża jego pamięć, bo wizytówka wisi w kontekście każdej rozmowy, i bywa nieprzewidywalny, bo agent potrafi go nie zauważyć w idealnie pasującym momencie. Skill wywoływany ręcznie obciąża za to Twoją głowę, bo to Ty musisz pamiętać, że istnieje i kiedy go użyć. Wybieraj świadomie, na przykład automatyzm dla codziennych procedur, a ręczne wywołanie dla zadań rzadkich i ryzykownych. Nasz skill od ofert gra na oba sposoby, bo nachalny opis pozwala agentowi sięgać po niego samodzielnie, a przed ważną wyceną i tak możesz wywołać go ręcznie.

Każdy skill dzieli się naturalnie na dwie jednostki, na kroki, przez które agent przechodzi po kolei, i na referencje, czyli materiał pomocniczy do tych kroków, a więc szablony, definicje i przykłady. Pisz najpierw kroki, a potem przy każdym z nich zadaj pytanie, jakiej referencji potrzebuje. Instrukcja główna ma zostać możliwie mała, a referencje potrzebne tylko w niektórych wariantach zadania przenieś do osobnych plików i zostaw po nich sam odsyłacz. Referencję używaną przy każdym przebiegu też lepiej trzymać w osobnym pliku, gdy jest obszerna, bo instrukcja ma odsyłać, a nie pęcznieć. Dokładnie tak zrobiliśmy w skillu od ofert, gdzie obszerny szablon mieszkał obok instrukcji, a po przykłady nietypowych wycen agent sięga wyłącznie wtedy, gdy oferta jest nietypowa.

Sterowanie odpowiada na pytanie, jak sprawić, żeby agent naprawdę robił to, co chcesz. Najskuteczniejszym narzędziem są słowa wiodące, krótkie i gęste znaczeniowo frazy branżowe, które pakują cały akapit intencji w dwa słowa. Zamiast tłumaczyć agentowi na pół strony, żeby nie budował systemu warstwa po warstwie, tylko zaczął od małego działającego wycinka, wystarczy konsekwentnie używać frazy vertical slice, a agent podchwyci ją we własnym rozumowaniu i realnie zmieni zachowanie. Test skuteczności jest prosty, bo jeśli fraza pojawia się w tym, jak agent relacjonuje swoje myślenie o zadaniu, to działa. Zanim więc dopiszesz do skilla kolejny akapit tłumaczeń, sprawdź, czy nie wystarczy jedno dobrze dobrane i konsekwentnie powtarzane pojęcie. W naszym skillu od ofert takim słowem jest lista kontrolna, która ustawia agenta w trybie odhaczania punktów przed oddaniem pracy, bez rozpisywania tego rytuału na akapit.

Przycinanie jest sprzątaniem po trzech poprzednich regułach. Każdy fragment, szablon czy definicja ma występować w skillu dokładnie raz, także między plikami referencyjnymi, bo duplikat to dwa miejsca do aktualizacji i któreś z nich zawsze się zestarzeje. Do tego dochodzą znane Ci już porządki, czyli wynoszenie osadu i test usunięcia dla akapitów, które tylko udają instrukcje. Skill po takim przejściu robi się krótszy, a paradoksalnie skuteczniejszy, bo agentowi zostaje mniej okazji, żeby skupić się na rzeczach bez znaczenia. Nasz skill od ofert przechodzi ten test, bo nie tłumaczy agentowi, czym jest oferta handlowa ani jak pisać uprzejme zdania, bo to akurat agent wie sam.

Podłączamy prawdziwe narzędzia, czyli kiedy kod bije instrukcję

Skill z samą instrukcją zajdzie daleko, ale w pewnym momencie trafisz na ścianę, którą znam bardzo dobrze. Niektórych rzeczy nie chcesz opisywać słowami, bo chcesz, żeby działy się dokładnie tak samo za każdym razem. Właśnie dlatego w naszym skillu od ofert obok instrukcji położyliśmy plik pobierz-ceny.py, a teraz wyjaśnię Ci dokładnie, co się tam wydarzyło. Do folderu skilla można włożyć programy, na przykład skrypty w Pythonie, a w instrukcji napisać, kiedy agent ma je uruchomić i czego się po nich spodziewać, dokładnie tak, jak my zrobiliśmy to z cenami. Agent nie musi nawet czytać ich kodu. Uruchamia narzędzie, patrzy na wynik i prowadzi proces dalej. Pamięcią płaci tylko za wynik, nie za kod. Moim zdaniem to jest najmocniejsza strona całego mechanizmu skilli.

To otwiera drogę do rzeczy naprawdę poważnych, bo taki skrypt może obsługiwać kompletny przepływ z zewnętrznymi API i bazami danych. Opowiem Ci, jak wygląda to w moim systemie do faktur, który opisywałem w osobnym artykule i który udostępniam jako paczkę startową. W folderze skilla leży kilkanaście narzędzi. Jedno łączy się z Gmailem przez API i pobiera maile, drugie robi to samo przez IMAP dla skrzynki prywatnej, trzecie kataloguje pliki na Dysku Google, czwarte prowadzi rejestr w Arkuszu, a osobny weryfikator porównuje faktury z wyciągami bankowymi i buduje listę braków dla księgowej. Każde z tych narzędzi to zwykły program, który można uruchomić i przetestować bez żadnego agenta. Agent siedzi piętro wyżej. Czyta instrukcję, w której napisałem, że główne narzędzie przetwarza wskazany miesiąc, że przed pierwszym uruchomieniem uruchamia się sondę sprawdzającą dostępy i że duże zaległości przerabia się małymi oknami po tygodniu. Agent nie klasyfikuje faktur ręcznie, tylko dyryguje narzędziami, które robią to szybciej i zawsze tak samo.

Granica między tym, co piszesz w instrukcji, a tym, co zamykasz w kodzie, jest prostsza, niż się wydaje, i praktycy są tu wyjątkowo zgodni. Wszystko, co deterministyczne, powtarzalne i kruche, pakuj w skrypt, bo skrypt nie ma gorszych dni i nie pomija kroków. Wszystko, co wymaga oceny sytuacji, zostaw w instrukcji, bo od tego masz model. Parsowanie pliku, wywołanie API, zapis do bazy i walidacja formatu to praca dla kodu. Decyzja, czy dokument jest fakturą kosztową, czy przychodową, i co zrobić z przypadkiem, którego nikt nie przewidział, to praca dla agenta. W instrukcji zaznaczaj przy tym wyraźnie, czy dany plik agent ma uruchomić, czy przeczytać jako materiał, bo to dwie różne czynności i agentowi trzeba tę intencję podać wprost.

Najpiękniejsze w tej architekturze jest to, że narzędzia są wymienne jak klocki. W skillu od faktur zapisałem to zresztą jako oficjalną procedurę adaptacji. Masz pocztę u innego dostawcy, nie w Gmailu? Piszesz albo prosisz agenta o nowy moduł o tym samym interfejsie, podmieniasz plik w folderze skilla, dopisujesz w instrukcji, co ten plik potrafi i jak się go woła, i cała reszta systemu działa dalej, bo nie musi wiedzieć, skąd przychodzi mail. W ten sam sposób podłączysz źródła zupełnie innego rodzaju, choćby KSeF, czyli Krajowy System e-Faktur, bo moduł pobierający faktury prosto z systemu ministerstwa zamiast ze skrzynki to po prostu kolejny klocek o tym samym interfejsie. Chcesz archiwum w innej chmurze albo rejestr w innej bazie? Ta sama operacja. Wymieniasz jeden klocek i jeden akapit instrukcji. Skill rośnie razem z firmą, zamiast być spisany na nowo przy każdej zmianie dostawcy.

Logika biznesowa ponad narzędziami

I tu dochodzimy do rzeczy, którą uważam za sedno całego tematu, a którą łatwo przeoczyć, gdy człowiek ekscytuje się techniką. W dobrze zbudowanym skillu są dwie warstwy i nie wolno ich mylić. Warstwa niższa to instrukcje obsługi narzędzi, a więc informacje o tym, że taki plik istnieje, co potrafi, jakie ma parametry i co zwraca. Warstwa wyższa to procedury nadrzędne, czyli logika biznesowa, która mówi, po co to wszystko i w jakiej kolejności wolno się tym posługiwać. To jest dokładnie różnica między instrukcją obsługi wiertarki a projektem domu. Możesz mieć najlepiej opisaną wiertarkę świata i nadal wywiercić dziurę w złym miejscu.

W moim skillu od faktur ta warstwa wyższa mówi na przykład, że przed jakąkolwiek pracą agent ma przeprowadzić wywiad z użytkownikiem i ustalić, ile jest skrzynek, czyje one są i gdzie mają lądować dokumenty. Mówi, że skanowanie cudzej skrzynki wysyła jej treść do modelu, więc wymaga świadomej zgody właściciela, zapisanej w notatce z ustaleń, zanim cokolwiek ruszy. Mówi, że pierwszy przebieg robi się zawsze na sucho i na dziesięciu mailach, ogląda z człowiekiem, a dopiero potem na poważnie. I mówi rzecz moim zdaniem najważniejszą, którą nazwałem zasadą akumulacji. Każdy błąd klasyfikacji i każdy przeoczony nadawca ma zostać zamieniony w trwałą regułę, wpis do konfiguracji albo poprawkę promptu, bo błąd ma prawo wystąpić raz. Zauważ, że żadna z tych reguł nie dotyczy obsługi konkretnego pliku. Wszystkie dotyczą tego, jak w tej firmie prowadzi się ten proces. Narzędzia możesz wymienić co do jednego, a te zasady zostaną, bo to one są wdrożeniem. Ta warstwa jest też najlepszym zabezpieczeniem, jakie znam, bo bramki w rodzaju "pokaż userowi do akceptacji" i "niczego nie wysyłaj sama" pilnują procesu niezależnie od tego, jak sprytne klocki włożysz pod spód.

Na koniec trzy lekcje, które oszczędzą Ci siwych włosów. Po pierwsze, jeden skill ma wykonywać jedno zadanie. Pokusa, żeby dopisywać kolejne obowiązki do rosnącego pliku, jest ogromna, ale skill od wszystkiego jest jak pracownik od wszystkiego, niby jest, a nic nie dowozi. Gdy widzisz, że agent notorycznie skraca któryś krok, bo śpieszy się do efektu końcowego, wydziel ten krok do osobnego skilla, a nagle zacznie go traktować poważnie. Po drugie, nie pisz instrukcji na zapas. Najlepsza kolejność jest odwrotna, niż podpowiada intuicja. Najpierw przejdź zadanie z agentem bez skilla i zobacz, gdzie naprawdę sobie nie radzi, potem poproś go, żeby sam spisał skill z tego, co właśnie wspólnie z nim wypracowałeś, a Ty go tylko zredaguj i odchudź. Agent zaskakująco dobrze wie, czego nie wiedział. Potem obserwuj skill w prawdziwej pracy jak nowego pracownika na okresie próbnym i poprawiaj na podstawie tego, co widzisz, a nie tego, co sobie wyobrażasz. Po trzecie, traktuj cudze skille jak cudze pendrive'y, a co dokładnie mam na myśli, rozwijam w uwadze na samym końcu.

Cała ta technologia sprowadza się ostatecznie do bardzo starej prawdy o delegowaniu. Firmy od zawsze rosły dzięki temu, że wiedza przestawała mieszkać w głowach i zaczynała mieszkać w procedurach. Skille robią z agentem dokładnie to, co dobra procedura robi z zespołem, tyle że pierwszy raz w historii procedura sama czyta samą siebie i sama się wykonuje. Twoja przewaga nie będzie polegała na tym, że masz dostęp do lepszego modelu, bo ten sam model ma cały świat. Będzie polegała na tym, że Twój agent wie o Twojej firmie coś, czego nie wie żaden inny. A to, ile wie, zależy już tylko od tego, ile mu spiszesz. Zacznij od jednego folderu i jednego pliku. Nowy pracownik właśnie usiadł przy biurku i, wyjątkowa rzadkość, naprawdę przeczyta wszystko, co mu zostawisz. A gdybyś chciał, żeby ktoś napisał skille dla Twojej firmy razem z Tobą, od pierwszego wywiadu po gotowe wdrożenie, zapraszam do kontaktu.