Jak stworzyć własną umiejętność agenta krok po kroku

Tworzenie własnej umiejętności agenta na podstawie rzeczywistej awarii

Najlepszym sposobem na stworzenie własnej umiejętności agenta jest wyodrębnienie jej z rzeczywistej awarii. Znajdź zadanie, w którym Twój agent programistyczny pomylił się dwukrotnie, zapisz poprawkę, którą wprowadziłeś za każdym razem, i zachowaj ją jako plik SKILL.md, który agent może samodzielnie załadować. Wszystko poza tym to kwestie techniczne: struktura pliku oraz pojedyncza linia decydująca o tym, czy umiejętność zostanie uruchomiona.

Ta kolejność ma znaczenie. Umiejętność napisana na podstawie wyobraźni dokumentuje problem, którego nigdy nie miałeś, a mimo to zużywa kontekst w każdej sesji. Umiejętność wyodrębniona z zaobserwowanej awarii posiada własny test: zadaj to samo pytanie ponownie i sprawdź, czy agent tym razem wykona je poprawnie. Jeśli sam format jest dla Ciebie nowy, najpierw przeczytaj czym są umiejętności agenta i jak agent je ładuje, a następnie wróć i stwórz własną.

Rozpocznij od zadania, w którym agent dwukrotnie popełnił błąd

Raz to przypadek. Dwa razy to wzorzec, a wzorzec jest wart stworzenia pliku.

Oto błąd, który powtarza się na rzeczywistych serwerach. Polecasz agentowi dodać blok reverse proxy do nginx. Edytuje on /etc/nginx/conf.d/app.conf, a następnie uruchamia sudo systemctl restart nginx. Edycja zawiera literówkę, więc nginx odmawia startu, a witryna jest niedostępna do momentu naprawy:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Poprawiasz to na czacie. Przetestuj konfigurację za pomocą sudo nginx -t przed ingerencją w usługę, a następnie zastosuj ją za pomocą reload zamiast restart. Tydzień później, przy innym zadaniu, ten sam błąd. Ten drugi raz jest sygnałem.

Zapisz dwie rzeczy, dopóki błąd jest widoczny: zapytanie, które wpisałeś, oraz poprawkę, której udzieliłeś, używając własnych słów. Te dwie linie stają się umiejętnością. Zapytanie określa, co musi pasować do wyzwalacza. Poprawka stanowi pełną treść.

Własne wytyczne autorskie Anthropic stawiają to na pierwszym miejscu. Uruchom agenta w reprezentatywnych zadaniach bez umiejętności, zarejestruj, gdzie występuje błąd, a następnie napisz minimalne instrukcje, które naprawią te błędy. Błędy są specyfikacją, więc umiejętność, której nie można przypisać do konkretnego błędu, jest zazwyczaj umiejętnością, której nikt nie potrzebował.

Aby zapoznać się z przykładem takiej destylacji, Ponytail zmienia jeden powtarzający się błąd, polegający na tym, że agent nadpisuje znacznie więcej, niż oczekiwano, w umiejętność, możesz przeczytać całość przed napisaniem własnej.

Anatomia umiejętności

Umiejętność to katalog zawierający jeden wymagany plik.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md otwiera się blokiem metadanych, czyli kilkoma ustawieniami zapisanymi w formacie YAML (tym samym, którego używają pliki Docker Compose) pomiędzy znacznikami ---, po których następują instrukcje w formacie markdown. Poniżej znajduje się kompletna umiejętność dla powyższego błędu.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Plik ten ma mniej niż dwadzieścia linii i stanowi kompletną umiejętność. Jego elementy:

• name: maksymalnie 64 znaki, wyłącznie małe litery, cyfry i myślniki; nie może zawierać słów claude ani anthropic. W umiejętnościach osobistych lub projektowych jest to tylko etykieta wyświetlana użytkownikowi. Komenda wywoływana jest na podstawie nazwy katalogu, więc w tym przypadku odpowiada na /nginx-config-changes.
• description: opis działania umiejętności oraz sytuacji, w których należy jej użyć, maksymalnie 1024 znaki. Ta linia wykonuje faktyczną pracę, a kolejna sekcja dotyczy wyłącznie tego zagadnienia.
• Treść: instrukcje ładowane tylko w momencie uruchomienia umiejętności.
• reference/: dodatkowe pliki odczytywane przez agenta na żądanie. Należy linkować je z SKILL.md i utrzymywać głębokość linków na jednym poziomie, ponieważ plik przywołany z innego przywołanego pliku jest często odczytywany tylko częściowo.
• scripts/: pliki wykonywane przez agenta zamiast odczytywania ich treści. Tylko ich wynik obciąża kontekst, więc 300-liniowy skrypt jest mało kosztowny.

Umiejętność rozrasta się do pełnego układu, gdy korygowane zachowanie jest na tyle uporczywe, że wymaga rozbudowy, a niezoptymalizowana umiejętność wykorzystuje to miejsce na drzewo głębokości (Depth Tree), zestaw plików bramek (gates) oraz kontrakt PLAN.md, aby zapobiec sytuacji, w której agent ogłasza zakończenie pracy, podczas gdy całe gałęzie zadań pozostają nietknięte.

Lokalizacja katalogu decyduje o tym, kto ma dostęp do umiejętności.

• .claude/skills/<name>/SKILL.md w repozytorium: tylko ten projekt; umiejętność jest dostępna dla każdego, kto sklonuje repozytorium.
• ~/.claude/skills/<name>/SKILL.md: wszystkie projekty na danej maszynie; niedostępne dla nikogo innego.
• <plugin>/skills/<name>/SKILL.md: dostarczane wewnątrz wtyczki; dostępne wszędzie tam, gdzie wtyczka jest włączona.

Utwórz umiejętność za pomocą mkdir -p .claude/skills/nginx-config-changes i zapisz plik. Claude Code monitoruje te katalogi, więc edycja istniejącej umiejętności odnosi skutek wewnątrz trwającej sesji. Utworzenie katalogu najwyższego poziomu dla umiejętności, który nie istniał w momencie rozpoczęcia sesji, wymaga restartu, ponieważ w chwili startu sesji nie było obiektu do monitorowania.

Pole opisu jest najważniejszym wierszem w pliku

Podczas uruchamiania agent wczytuje name oraz description każdej dostępnej umiejętności do swojego kontekstu. Nie wczytuje treści samych funkcji. Gdy nadejdzie żądanie, ten jeden wiersz stanowi wyłączną podstawę decyzji o tym, czy dana umiejętność jest istotna, więc doskonała implementacja ukryta za niejasnym opisem nigdy nie zostanie odczytana.

Opis należy pisać w trzeciej osobie. Konstrukcja "Testuje i przeładowuje nginx w bezpieczny sposób" jest poprawna. "Pomogę ci z nginx" jest błędna, ponieważ tekst jest wstrzykiwany do system prompt, gdzie pierwsza osoba sugeruje, że model mówi o samym sobie.

Opis musi zawierać dwie informacje: co robi umiejętność oraz warunki, w których ma zastosowanie. Najważniejszy przypadek użycia należy umieścić na początku, ponieważ Claude Code ucina listę wpisów po 1 536 znakach. Istnieje opcjonalne pole when_to_use na dodatkowe frazy wyzwalające i przykładowe żądania; jest ono dołączane do opisu w ramach tego samego limitu.

Należy używać słów, które faktycznie zostaną wpisane. description: Helps with nginx nie dopasuje niczego, ponieważ nikt nie wpisuje "pomaga z". Powyższa wersja wymienia /etc/nginx, server block, reverse proxy oraz TLS (transport layer security) certificate path, co stanowi przybliżony zasób słownictwa każdego żądania, które powinno wywołać tę umiejętność.

Oto test poprawności opisu. Należy przekazać ten jeden wiersz osobie, która nigdy nie widziała treści funkcji, wraz z żądaniem, które zamierzasz wpisać, a następnie zapytać, czy umiejętność ma zastosowanie. Jeśli ta osoba nie potrafi tego stwierdzić, model również nie będzie w stanie.

Utrzymuj niewielki rozmiar treści, ponieważ pozostaje ona w kontekście

Gdy umiejętność zostaje wywołana, jej wygenerowana treść wchodzi do konwersacji jako jedna wiadomość i pozostaje w niej przez resztę sesji. Claude Code nie odczytuje ponownie pliku w kolejnych turach. Każda napisana linia stanowi koszt ponoszony przez całą sesję, a nie tylko za jedną odpowiedź.

Anthropic zaleca utrzymywanie SKILL.md poniżej 500 linii i przenoszenie szczegółów do oddzielnych plików. Kompresja pokazuje, dlaczego ta liczba nie jest przypadkowa. Gdy konwersacja jest podsumowywana w celu zwolnienia kontekstu, Claude Code ponownie dołącza ostatnie wywołanie każdej umiejętności, zachowuje tylko pierwsze 5000 tokenów każdej z nich i wypełnia łączny budżet 25000 tokenów, zaczynając od umiejętności wywołanej najpóźniej. Długa umiejętność zostanie ucięta w trakcie. Kilka długich umiejętności wypchnie się nawzajem całkowicie.

Dlatego pisz tylko to, czego model jeszcze nie wie. Wie, czym jest nginx i do czego służy reverse proxy. Nie zna Twojej wewnętrznej zasady dotyczącej reload ponad restart, a ta zasada jest jedynym powodem istnienia tego pliku.

Jeśli umiejętność nakazuje agentowi uruchomienie dołączonego skryptu, wskaż ścieżkę za pomocą ${CLAUDE_SKILL_DIR}, aby rozwiązywała się niezależnie od miejsca instalacji umiejętności, oraz wstępnie zatwierdź to samo polecenie, aby uruchomienie nie zatrzymało się na monicie o uprawnienia.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

Zezwolenie obejmuje turę, w której wywołano umiejętność, i wygasa po wysłaniu kolejnej wiadomości, dzięki czemu nie staje się ono po cichu stałym uprawnieniem.

Jak zweryfikować uruchomienie umiejętności

Obserwacja ładowania umiejętności potwierdza jedynie, że agent ją wykrył. Nie oznacza to, że odpowiedź uległa zmianie. Należy sprawdzić oba aspekty w nowej sesji, ponieważ sesja, w której tworzono umiejętność, przechowuje całą historię konwersacji. Pozostały kontekst maskuje luki w pliku.

1. Rozpocznij nową sesję za pomocą claude w projekcie.
2. Wpisz żądanie w sposób typowy dla codziennej pracy, własnymi słowami, nie wymieniając nazwy umiejętności.
3. Obserwuj wywołanie. Jeśli umiejętność nie uruchamia się, popraw opis. Problem nie leży jeszcze w treści.
4. Wywołaj ją ręcznie za pomocą /nginx-config-changes jako kontrolę. Prawidłowe działanie przy wywołaniu ręcznym przy jednoczesnym błędnym działaniu przy wywołaniu przez żądanie potwierdza problem z wyzwalaczem, a nie z instrukcjami.
5. Uruchom to samo żądanie przy wyłączonej umiejętności i porównaj obie odpowiedzi. W menu /skills zaznacz umiejętność, naciśnij Space, aby zmienić jej stan na off, a następnie Enter, aby zapisać. Spowoduje to zapisanie wpisu skillOverrides w .claude/settings.local.json, a ponowne naciśnięcie Space przywróci stan on po zakończeniu pracy.
6. Przygotuj kilka żądań, które nie powinny wyzwalać umiejętności, i sprawdź, czy pozostaje ona nieaktywna.

Aby zautomatyzować ten cykl, zainstaluj wtyczkę skill-creator z oficjalnego marketplace.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Jeśli wynik instalacji wskazuje Run /reload-plugins to activate., wykonaj to polecenie. Następnie poproś Claude o ocenę umiejętności według nazwy. Wtyczka przechowuje przypadki testowe w evals/evals.json wewnątrz katalogu umiejętności i uruchamia każdy przypadek w osobnym podagencie, dzięki czemu każde uruchomienie rozpoczyna się z czystym kontekstem. Następnie generowane jest porównanie odpowiedzi z użyciem umiejętności i bez niej, co stanowi wiarygodny wskaźnik: poprawę skuteczności mierzoną względem kosztu tokenów i czasu pracy umiejętności.

Umiejętność może również zawierać własny dowód działania, zamiast polegać na oddzielnym uruchomieniu oceny, co robi umiejętność Old Coder, zmuszając agenta do zwrócenia raportu z dowodami, który można samodzielnie uruchomić ponownie.

Tryb awarii: umiejętność nigdy się nie uruchamia

Wprowadzasz żądanie, agent wykonuje poprzednie błędne działanie, a wiersz umiejętności się nie pojawia. Przeanalizuj poniższe punkty w podanej kolejności.

• Opis określa, co robi umiejętność, ale nie wskazuje, kiedy jej użyć, więc nic w Twoim żądaniu do niej nie pasuje.
• Opis nie zawiera słów, które wpisujesz. Jeśli wpiszesz "nginx", opis musi zawierać słowo nginx.
• disable-model-invocation: true jest ustawione w metadanych (frontmatter). Powoduje to całkowite wykluczenie opisu z kontekstu modelu i sprawia, że umiejętność może zostać wywołana tylko przez Ciebie za pomocą /name.
• Wzorzec paths w metadanych ogranicza aktywację do pasujących plików, a plik, nad którym pracujesz, nie spełnia tego warunku.
• Umiejętność znajduje się w zagnieżdżonym katalogu .claude/skills/ poniżej katalogu startowego. Takie umiejętności są ładowane dopiero po tym, jak agent odczyta lub edytuje plik wewnątrz tego podkatalogu, więc do tego momentu umiejętność jest niedostępna.

Tryb awarii: umiejętność uruchamia się bez przerwy

Odwrotnym problemem jest opis tak ogólny, że umiejętność aktywuje się przy niezwiązanych zadaniach. „Użyj podczas pracy na serwerze” pasuje do niemal każdego żądania w repozytorium serwerowym. Treść jest wtedy ładowana do zadań, w których nie może pomóc, i pozostaje w kontekście przez resztę sesji.

Należy zawęzić opis do warunku, który faktycznie ma znaczenie, oraz wskazać pliki lub polecenia, których dotyczy. Należy dodać wzorzec paths, gdy umiejętność ma zastosowanie tylko do określonych plików. W przypadku operacji z efektami ubocznymi, takich jak wdrożenie lub commit, należy ustawić disable-model-invocation: true i wywoływać je samodzielnie za pomocą /name, aby agent nigdy samodzielnie nie decydował, że nadszedł odpowiedni moment na wdrożenie.

Tryb awarii: umiejętność powinna znajdować się w pliku reguł

Plik reguł, taki jak CLAUDE.md lub AGENTS.md, wczytuje się na początku każdej sesji i ma zastosowanie do każdego zadania. Treść umiejętności wczytuje się tylko wtedy, gdy umiejętność zostaje wywołana. Częstotliwość użycia jest kluczowym czynnikiem decyzyjnym. Fakt dotyczący każdego zadania w repozytorium, na przykład używany menedżer pakietów, powinien znajdować się w pliku reguł. Procedura mająca zastosowanie do niewielkiego wycinka zadań, jak wspomniana wyżej reguła dla nginx, powinna znajdować się w umiejętności, gdzie nie generuje kosztów w dniach, w których nikt nie edytuje konfiguracji nginx.

Prawdziwym błędem jest umieszczanie instrukcji w obu miejscach. Dwie kopie z czasem stają się niespójne, a gdy agent wykonuje błędne działanie, nie można ustalić, którą wersją się kierował. Należy wybrać jedno miejsce dla każdej instrukcji. Reguła, która znajduje się już w jednym miejscu, a mimo to jest ignorowana, stanowi inny problem. Warto sprawdzić mechanizmy stojące za zignorowaną instrukcją przed przeniesieniem jej do umiejętności w nadziei, że zmiana rozwiąże problem. Artykuł granica między umiejętnościami, serwerami MCP a plikami reguł omawia trudniejsze przypadki, w tym sytuacje, w których właściwym rozwiązaniem jest serwer MCP (model context protocol), dostarczający agentowi nowe narzędzie zamiast nowej instrukcji.

Udostępnianie sprawdzonych rozwiązań

Umiejętność, która sprawdza się w tygodniu realnej pracy, jest warta utrwalenia. Umiejętności projektowe w .claude/skills/ podlegają przeglądowi tak jak kod i są dostarczane wraz z repozytorium, dzięki czemu członek zespołu po sklonowaniu repozytorium otrzymuje poprawkę bez konieczności dodatkowej konfiguracji. Przenoszenie umiejętności między repozytoriami bez kopiowania i wklejania stanowi odrębne zagadnienie, omówione w jak udostępniać umiejętności agenta między repozytoriami.

Uwaga dotycząca przenośności. Claude Code akceptuje długą listę pól frontmatter, jednak standard Agent Skills dopuszcza tylko sześć: name, description, license, compatibility, metadata oraz allowed-tools. Przesłanie umiejętności do claude.ai lub spakowanie jej dla Skills API z jakimkolwiek innym polem we frontmatter spowoduje błąd zamiast zignorowania pola:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Ograniczenie się do tych sześciu pól zapewnia, że ten sam plik wczyta się w Claude Code oraz w każdym innym narzędziu obsługującym ten standard. Miejsce wczytania pliku nadal determinuje jego możliwości, ponieważ Cowork działa w piaskownicy Anthropic, podczas gdy Claude Code uruchamiany jest na własnej maszynie lub VPS, więc powyższa umiejętność nginx jest przydatna w środowisku członka zespołu, ale bezużyteczna w piaskownicy, która nie ma dostępu do serwera. Tworzenie instrukcji w sposób zapewniający ich działanie po przeniesieniu do innego modelu to osobne zadanie, opisane w tworzenie umiejętności działających z dowolnym modelem.

FAQ

Jaka powinna być długość pliku SKILL.md?

Należy utrzymać ją poniżej 500 linii; większość przydatnych umiejętności jest znacznie krótsza. Treść pliku trafia do konwersacji w momencie wywołania umiejętności i pozostaje w niej do końca sesji, więc każda linia stanowi koszt powtarzalny, a nie jednorazowy. Długie materiały referencyjne należy przenosić do oddzielnych plików w katalogu umiejętności i linkować je z poziomu SKILL.md, zachowując jeden poziom zagłębienia, aby agent odczytywał je tylko w razie potrzeby. Dołączone skrypty są wykonywane, a nie czytane, więc ich koszt ogranicza się jedynie do wygenerowanego wyniku.

Dlaczego moja umiejętność nie uruchamia się?

Najczęstszą przyczyną jest opis, ponieważ jest to jedyna część umiejętności dostępna w kontekście, gdy model podejmuje decyzję. Należy upewnić się, że opis wskazuje, kiedy użyć umiejętności, a nie tylko co ona robi, oraz że zawiera słowa faktycznie wpisywane w zapytaniach. Jeśli opis wydaje się poprawny, należy sprawdzić frontmatter pod kątem disable-model-invocation: true, który całkowicie ukrywa umiejętność przed modelem, oraz paths, który ogranicza ją do plików, z którymi użytkownik nie pracuje. Inną przyczyną może być umieszczenie umiejętności w zagnieżdżonym katalogu .claude/skills/ poniżej katalogu początkowego: ładuje się ona dopiero po odczytaniu lub edycji pliku w tym podkatalogu przez agenta.

Czy to powinna być umiejętność, czy linia w pliku reguł?

Należy zadać sobie pytanie, do ilu zadań ma ona zastosowanie. Plik reguł ładuje się w każdej sesji, więc powinien zawierać fakty prawdziwe dla każdego zadania, takie jak menedżer pakietów czy konwencja nazewnictwa gałęzi. Umiejętność ładuje się tylko wtedy, gdy zostanie wywołana, więc jest to właściwe miejsce dla procedury istotnej tylko w niewielkiej części zadań. Nigdy nie należy zapisywać tej samej instrukcji w obu miejscach, ponieważ kopie mogą się rozbiec, co uniemożliwi ustalenie, którą z nich kierował się agent.

Skąd wiadomo, że umiejętność faktycznie pomogła?

Należy porównać wynik z wartością bazową. Trzeba zebrać kilka rzeczywistych zapytań, uruchomić każde z nich w nowej sesji z dostępną umiejętnością, a następnie uruchomić je ponownie z wyłączoną umiejętnością w menu /skills i porównać obie odpowiedzi. Nowa sesja jest istotna, ponieważ konwersacja, w której tworzono umiejętność, nadal zawiera wyjaśnienia użytkownika, co sprawia, że niekompletny plik wydaje się kompletny. Wtyczka skill-creator wykonuje to porównanie automatycznie i raportuje wskaźnik powodzenia obok kosztu tokenów.

Czy mogę użyć tego samego pliku SKILL.md z innym agentem?

Tak, o ile zachowane zostaną pola zdefiniowane w standardzie Agent Skills: name, description, license, compatibility, metadata oraz allowed-tools. Claude Code akceptuje znacznie więcej pól i obsługuje funkcje treści, takie jak wstrzykiwanie poleceń powłoki, których inne narzędzia nie uruchamiają. Przesłanie umiejętności z polem spoza standardu kończy się błędem z listą dozwolonych właściwości, dlatego należy wcześniej zdecydować, czy umiejętność ma pozostać w Claude Code, czy być przenośna.