Skille agenta: jak dodać własną procedurę do OpenClaw

Czym jest skill, a czym na pewno nie jest

Skill to katalog z plikiem SKILL.md, który OpenClaw wkłada do promptu agenta. Dokumentacja nazywa go pakietem instrukcji i nic więcej za tym nie stoi. W środku siedzi nagłówek YAML z dwoma wymaganymi polami i zwykły tekst pod nim. Ten tekst czyta model, nie interpreter.

Różnicę między skillem a narzędziem myli na starcie prawie każdy. Narzędzie to typowana funkcja, którą model wywołuje — exec, browser, web_search, message, image_generate. Skill nie dodaje ani jednej takiej funkcji. Opisuje procedurę: po które narzędzie sięgnąć, w jakiej kolejności i czego przy okazji nie robić.

Konsekwencja jest niewygodna i lepiej ją poznać przed spędzeniem wieczoru na pisaniu. Jeśli agent nie ma w polityce narzędzia exec, skill z instrukcją „uruchom skrypt czyszczący” nie zadziała. Model przeczyta instrukcję, spróbuje wykonać krok i odbije się od polityki. Skille dokładasz wtedy, gdy agent ma już czym pracować, a brakuje mu opisanej procedury.

Nazwa skilla i jego komenda ukośnikowa biorą się z pola name we frontmatterze, a gdy tego pola brakuje — z nazwy katalogu. Skille mogą też przyjść razem z pluginem, który listuje swoje katalogi skills w pliku openclaw.plugin.json i ładuje je, kiedy jest włączony. To nadal ten sam plik tekstowy, tylko dostarczony w paczce.

Z czego składa się SKILL.md

Plik zaczyna się nagłówkiem YAML zamkniętym między dwiema liniami myślników. Wymagane pola są dwa: name i description. Pierwsze to slug złożony z małych liter, cyfr i myślników. Drugie to jedna linia opisu — i jest to jedyna rzecz, którą model widzi, zanim zdecyduje, czy w ogóle sięgnąć po ten skill.

Dlatego description pisze się jak wpis do indeksu, nie jak hasło reklamowe. „Pomaga w pracy z dokumentami” nie mówi modelowi niczego. „Zamienia faktury PDF na wiersze CSV i zapisuje je w katalogu ksiegowosc” mówi wszystko, co potrzebne do wyboru. Skill Workshop trzyma zresztą twardy limit 160 bajtów na opis, więc krótko wyjdzie i tak.

Pól opcjonalnych jest kilkanaście, w praktyce używasz dwóch. user-invocable domyślnie ma wartość true i wystawia skill jako komendę ukośnikową, a disable-model-invocation domyślnie jest false; ustawione na true trzyma instrukcje skilla poza normalnym promptem agenta, więc odpala się on tylko z ręki. Rzadziej sięgniesz po resztę: command-dispatch ustawione na „tool” razem z command-tool omija model i kieruje komendę prosto do narzędzia, command-arg-mode domyślnie stoi na „raw”, a homepage to adres pokazywany w interfejsie na macOS.

Wewnątrz bloku metadata.openclaw siedzą bramki, które decydują, czy skill w ogóle się pokaże. os przyjmuje tablicę z wartościami „darwin”, „linux”, „win32”. requires.bins wymaga binariów na PATH, requires.anyBins wystarcza jedno z listy, requires.env wymaga zmiennych środowiskowych, a requires.config wskazuje ścieżki w openclaw.json, które muszą mieć wartość prawdziwą. Pole always pomija wszystkie pozostałe bramki. Do plików leżących obok SKILL.md odwołujesz się przez {baseDir}, dzięki czemu katalog da się przenieść bez przepisywania ścieżek.

---
name: raport-tygodniowy
description: Sklada raport sprzedazowy z arkusza CSV i wysyla go na Slacka
user-invocable: true
---

## Kiedy uzywac
...

Gdzie położyć katalog i dlaczego to zmienia wynik

OpenClaw szuka pliku SKILL.md pod skonfigurowanymi katalogami głównymi, schodząc maksymalnie sześć poziomów w głąb. Podkatalogi są więc czystą organizacją — możesz trzymać skille pogrupowane tematycznie i nic się nie zepsuje. Znaczenie ma natomiast to, który katalog główny wybierzesz, bo od tego zależy pierwszeństwo.

Źródeł jest sześć i mają ustaloną kolejność. Gdy ten sam skill o tej samej nazwie leży w dwóch miejscach, wygrywa źródło wyżej na liście — pozostałe są po prostu niewidoczne. To wygodny mechanizm nadpisywania: bierzesz skill z paczki i kładziesz własną wersję w katalogu workspace, nie ruszając oryginału.

Lista skilli jest zamrażana w momencie startu sesji i używana we wszystkich kolejnych turach. Zmiana pliku w połowie rozmowy domyślnie nic nie da, chyba że działa obserwator — skills.load.watch ma domyślnie wartość true i odświeża zdjęcie stanu, gdy wykryje zmianę w SKILL.md, z wbudowanym opóźnieniem 250 ms. Drugi przypadek odświeżenia to podłączenie nowego zdalnego węzła. Jeśli nie masz pewności, otwórz nową sesję.

Pierwszego wieczoru straciłem na tym godzinę: poprawiasz literówkę, pytasz agenta, dostajesz starą odpowiedź i zaczynasz przepisywać instrukcję, która była poprawna od początku. Zanim zaczniesz szukać błędu w treści, sprawdź, czy skill w ogóle się załadował.

• <workspace>/skills — najwyższe pierwszeństwo
• <workspace>/.agents/skills — skille projektowe
• ~/.agents/skills — skille osobiste
• <katalog stanu>/skills, domyślnie ~/.openclaw/skills
• skille dostarczone z instalacją
• skills.load.extraDirs i skille z pluginów — najniższe pierwszeństwo

openclaw skills list

Kiedy skill, a kiedy zwykłe zdanie w promptcie

Reguła jest prosta i sprawdza się w praktyce. Rzecz jednorazowa idzie do promptu. Procedura, którą przepisujesz trzeci raz tymi samymi słowami, idzie do skilla. Reguła obowiązująca zawsze, w każdej sesji i niezależnie od zadania, idzie do standing orders — czyli do pliku w workspace wstrzykiwanego do każdej sesji.

Za tym podziałem stoi arytmetyka promptu, a nie estetyka. Każdy widoczny skill zajmuje miejsce w kontekście, a budżet znaków na sekcję skilli ustawia klucz skills.limits.maxSkillsPromptChars. Dwadzieścia skilli, z których agent używa trzech, to siedemnaście opisów zjadających kontekst w każdej turze. Widziałem takie konfiguracje i za każdym razem kończyło się to czyszczeniem po miesiącu.

Jest też trzecia droga, o której mało kto pamięta. Skill z disable-model-invocation ustawionym na true nie trafia do normalnego promptu agenta i odpalasz go wyłącznie komendą ukośnikową. Nadaje się do procedur długich, rzadkich i takich, przy których to Ty decydujesz o starcie — na przykład zamknięcia miesiąca.

Krótki test przed napisaniem: czy potrafisz opisać procedurę tak, żeby ktoś inny wykonał ją bez dopytywania? Jeśli tak, masz materiał na skill. Jeśli nie, masz materiał na rozmowę z agentem, po której dopiero powstanie skill.

Pierwszy skill w dziesięć minut

Zacznij od katalogu w workspace, bo ma najwyższe pierwszeństwo i najmniej rzeczy może pójść nie tak. Nazwa katalogu nie musi zgadzać się z polem name, ale zgodność oszczędza późniejszego zamieszania. Wewnątrz tworzysz jeden plik: SKILL.md.

Treść pod nagłówkiem pisz tak, jak pisałbyś instrukcję dla nowej osoby w zespole. Najpierw krótka sekcja o tym, kiedy tej procedury użyć. Potem kroki po kolei, każdy z konkretną nazwą narzędzia albo pliku. Na końcu lista rzeczy, których robić nie wolno — to zwykle najbardziej użyteczny fragment całego pliku.

Po zapisaniu sprawdzasz obecność skilla na liście, a dopiero potem odpalasz go pojedynczą wiadomością do agenta. Rozdzielenie tych dwóch kroków ma sens: jeśli skill nie jest na liście, testowanie treści to strata czasu. Odpowiedź agenta pokaże Ci, czy opis w polu description trafił w intencję.

Dobra praktyka na start: pierwszy skill zrób nudny. Coś, co robisz co tydzień, ma jedno wejście i sprawdzalny wynik. Ambitne procedury pisze się dopiero wtedy, gdy wiesz już, jak zachowuje się mechanizm ładowania.

mkdir -p ~/.openclaw/workspace/skills/hello-world
openclaw skills list
openclaw agent --message "uzyj skilla hello-world"

Jak przetestować, że skill naprawdę wchodzi do gry

Test skilla ma dwie warstwy i ludzie sprawdzają tylko drugą. Pierwsza: czy skill jest widoczny. Druga: czy model po niego sięga. Do pierwszej służy openclaw skills list oraz openclaw skills check, który pokazuje stan skilli. Do drugiej — pytanie zadane naturalnym językiem, bez podawania nazwy skilla.

Ta druga warstwa jest właściwym testem, bo w codziennej pracy nikt nie pisze „użyj skilla raport-tygodniowy”. Ludzie piszą „zrób mi ten raport”. Jeśli agent po skill nie sięgnął, winne jest zwykle pole description, nie treść instrukcji. Przepisz opis tak, żeby zawierał słowa, których naprawdę używasz.

Osobna kategoria zgłoszeń to skille, które zniknęły bez śladu. Prawie zawsze odpowiadają za to bramki z metadata.openclaw. Brakująca binarka z requires.bins, nieustawiona zmienna z requires.env albo klucz z requires.config o wartości fałszywej sprawiają, że skill po prostu się nie pokazuje. Skill zniknął, bo nie przeszedł bramki requires.

Trzeci powód jest banalny i wart sprawdzenia jako pierwszy: sesja. Skille zamrażane są na starcie sesji, więc plik poprawiony przed chwilą może jeszcze nie działać. Otwórz nową sesję i powtórz test, zanim zaczniesz przepisywać instrukcję.

openclaw skills check

Skille z ClawHuba, z gita i z katalogu obok

Nie wszystko trzeba pisać samemu. openclaw skills install przyjmuje trzy źródła: pakiet z ClawHuba zapisany jako @owner/<slug>, repozytorium gita w formie git:owner/repo@ref oraz zwykłą ścieżkę lokalną z flagą --as ustawiającą nazwę. Flaga --global instaluje skill poza workspace. Aktualizacja wszystkiego naraz to openclaw skills update --all, a openclaw skills verify @owner/<slug> sprawdza pakiet.

Zanim zainstalujesz cudzy skill, przeczytaj jego SKILL.md od początku do końca. To instrukcja, którą Twój agent wykona posiadanymi narzędziami — z exec włącznie, jeśli je ma. Nie jest to plugin działający w piaskownicy, tylko tekst wpuszczony prosto do promptu. Traktuj to jak wklejanie cudzego skryptu do terminala.

Zachowanie instalatora ustawia blok skills.install. preferBrew domyślnie ma wartość true, nodeManager domyślnie to „npm”, a allowUploadedArchives domyślnie jest false — czyli wgrywanie archiwów jest wyłączone i to dobra wartość domyślna. Jeśli trzymasz skille jako dowiązania symboliczne, katalogi docelowe musisz wymienić w skills.load.allowSymlinkTargets.

Własny skill opublikujesz osobnym narzędziem. Instalujesz clawhub globalnie przez npm, a potem uruchamiasz clawhub skill publish ze ścieżką do katalogu. Publikacja nie jest częścią CLI OpenClaw i to jedno z tych miejsc, gdzie dokumentacja mogłaby prowadzić za rękę mocniej.

openclaw skills install @owner/nazwa-skilla
openclaw skills install ./sciezka/do/skilla --as moj-skill
openclaw skills update --all

Kto pisze skille i kto je widzi

Agent może zaproponować skill sam, ale nigdy nie zapisze go od razu. Skill Workshop zapisuje wygenerowaną treść jako PROPOSAL.md, nie jako SKILL.md, a jedynym zapisem na żywo jest komenda apply. Propozycje przeglądasz przez openclaw skills workshop list oraz inspect, a decydujesz komendami apply, reject albo quarantine. Przed zastosowaniem uruchamiany jest skan bezpieczeństwa i tylko ustalenia krytyczne blokują zapis.

Limity Workshopu ustawia blok skills.workshop. maxSkillBytes domyślnie wynosi 40 000 przy suficie 200 000, maxPending domyślnie 50 w zakresie od 1 do 200, a approvalPolicy przyjmuje „pending” albo „auto”. Zapis przez dowiązania symboliczne kontroluje allowSymlinkTargetWrites, domyślnie wyłączony.

Tryb samouczenia jest domyślnie wyłączony i włączasz go kluczem skills.workshop.autonomous.enabled. Wychwytuje trwałe poprawki — sformułowania w rodzaju „od teraz” czy „następnym razem” — oraz przegląda zakończoną pracę po okresie bezczynności. Nie trenuje wag modelu, nie edytuje żywych skilli i niczego nie zmienia po cichu. Wszystko ląduje jako propozycja do zatwierdzenia.

Ostatnia warstwa to widoczność. agents.defaults.skills ustawia wspólną listę dozwolonych skilli, a agents.entries.*.skills ustawia listę finalną dla konkretnego agenta. Finalną, czyli zastępującą domyślne — listy się nie sumują. Pominięcie agents.defaults.skills zostawia wszystkie skille bez ograniczeń, a pusta lista przy agencie odcina go od wszystkich. Pojedynczy skill wyłączysz kluczem skills.entries.<nazwa>.enabled.

openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>