Jak napisać 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. Należy znaleźć zadanie, z którym agent programistyczny nie poradził sobie dwukrotnie, zapisać poprawkę wprowadzoną za każdym razem i zapisać ją jako plik SKILL.md, który agent może samodzielnie załadować. Wszystko pozostałe to kwestie techniczne: struktura pliku oraz pojedyncza linia decydująca o tym, czy umiejętność zostanie uruchomiona.

Kolejność ma znaczenie. Umiejętność napisana na podstawie wyobrażeń dokumentuje problem, który nigdy nie wystąpił, a mimo to zużywa kontekst w każdej sesji. Umiejętność wyodrębniona z zaobserwowanej awarii posiada własny test: wystarczy zadać to samo pytanie ponownie i sprawdzić, czy agent tym razem wykona je poprawnie. Jeśli sam format jest nowy, należy najpierw przeczytać czym są umiejętności agenta i jak agent je ładuje, a następnie wrócić i stworzyć własną.

Rozpocznij od zadania, w którym agent pomylił się dwukrotnie

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 dodanie bloku reverse proxy do nginx. Agent edytuje /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 pozostaje niedostępna do czasu 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, pojawia się ten sam błąd. To drugie wystąpienie jest sygnałem.

Zapisz dwie rzeczy, gdy błąd jest wciąż 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 użycia umiejętności, zarejestruj miejsca, w których zawodzi, a następnie napisz minimalne instrukcje, które naprawią te błędy. Błędy stanowią 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ł.

Przykład takiej destylacji, Ponytail zamienia jeden powtarzający się błąd – agenta, który nadpisuje znacznie więcej, niż oczekiwano – w umiejętność, można przeczytać w całości 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ści osobistej lub projektowej jest to tylko etykieta wyświetlana. Polecenie wywoływane jest nazwą katalogu, więc w tym przypadku odpowiada na /nginx-config-changes.
• description: opis działania umiejętności i sytuacji, w których należy jej użyć, maksymalnie 1024 znaki. Ta linia wykonuje właściwą 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 je podlinkować z SKILL.md i utrzymywać linki na jednym poziomie zagłębienia, ponieważ plik przywołany z innego przywołanego pliku jest często odczytywany tylko częściowo.
• scripts/: pliki wykonywane przez agenta zamiast odczytywania. Tylko ich wynik obciąża kontekst, więc 300-liniowy skrypt jest tani w użyciu.

Lokalizacja katalogu decyduje o tym, kto otrzyma 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: każdy projekt na danej maszynie; niedostępne dla innych użytkowników.
• <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 w ramach 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 elementem pliku

Podczas uruchamiania agent wczytuje name oraz description każdej dostępnej umiejętności do swojego kontekstu. Nie wczytuje on treści tych umiejętności. W momencie nadejścia żądania, to właśnie ten jeden wiersz stanowi podstawę decyzji o tym, czy dana umiejętność jest istotna. Z tego powodu doskonała treść ukryta za niejasnym opisem nigdy nie zostanie odczytana.

Opis należy pisać w trzeciej osobie. Sformułowanie "Bezpiecznie testuje i przeładowuje nginx" jest poprawne. Sformułowanie "Pomogę ci z nginx" jest błędne, ponieważ tekst jest wstrzykiwany do promptu systemowego, w którym pierwsza osoba jest interpretowana jako model mówiący o samym sobie.

Opis powinien zawierać dwie informacje: co robi umiejętność oraz w jakich warunkach ma zastosowanie. Najważniejszy przypadek użycia należy umieścić na początku, ponieważ Claude Code ucina listę wpisów po 1536 znakach. Dostępne jest 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 znaków.

Należy używać słów, które faktycznie zostaną wpisane. description: Helps with nginx nie dopasuje niczego, ponieważ nikt nie wpisuje frazy "helps with". Powyższa wersja wymienia /etc/nginx, server block, reverse proxy oraz TLS (transport layer security) certificate path, co w przybliżeniu stanowi słownictwo 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 umiejętności, wraz z żądaniem, które zamierzasz wpisać, a następnie zapytać, czy dana 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 zawartość trafia 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 osobnych 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ść zostaje ucięta w połowie. Kilka długich umiejętności wypiera się nawzajem całkowicie.

Należy więc pisać tylko to, czego model jeszcze nie wie. Model wie, czym jest nginx i do czego służy reverse proxy. Nie zna natomiast 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, należy wskazać ścieżkę za pomocą ${CLAUDE_SKILL_DIR}, aby rozwiązywała się ona niezależnie od miejsca instalacji umiejętności, oraz wstępnie zatwierdzić to samo polecenie, aby proces nie zatrzymał 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 *)
---

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

Jak zweryfikować wyzwalanie umiejętności

Obserwacja ładowania umiejętności potwierdza jedynie, że agent ją odnalazł. Nie oznacza to jednak, że odpowiedź uległa zmianie. Należy sprawdzić oba te aspekty w nowej sesji, ponieważ sesja, w której tworzono umiejętność, przechowuje całą historię konwersacji z etapu pisania. 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. Treść nie jest jeszcze problemem.
4. Wywołaj ją ręcznie za pomocą /nginx-config-changes w celach kontrolnych. Prawidłowe działanie przy wywołaniu ręcznym i błędne przy wywołaniu przez żądanie potwierdza problem z wyzwalaczem, a nie z instrukcjami.
5. Uruchom to samo żądanie z wyłączoną 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 testów.
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., uruchom to polecenie. Następnie poproś Claude o ocenę umiejętności po jej nazwie. Wtyczka przechowuje przypadki testowe w evals/evals.json wewnątrz katalogu umiejętności i uruchamia każdy przypadek w osobnym subagencie, dzięki czemu każde uruchomienie rozpoczyna się od czystego kontekstu. 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.

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

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

• Opis określa, co robi umiejętność, ale nie wskazuje, kiedy jej użyć, więc treść żądania nie pasuje do żadnego z kryteriów.
• 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 początkowego. Takie umiejętności są ładowane dopiero po odczytaniu lub edycji pliku 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 zbyt ogólny opis, przez co umiejętność aktywuje się przy niezwiązanych z nią zadaniach. Opis „Użyj podczas pracy na serwerze” pasuje do niemal każdego żądania w repozytorium serwerowym. W rezultacie treść jest ł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 warunków, które faktycznie mają znaczenie, oraz wskazać pliki lub polecenia, których dotyczy. Należy dodać wzorzec paths, jeśli umiejętność ma zastosowanie tylko do określonych plików. W przypadku operacji wywołujących skutki uboczne, takich jak wdrożenie (deploy) czy zatwierdzenie zmian (commit), należy ustawić disable-model-invocation: true i wywoływać je samodzielnie za pomocą /name. Dzięki temu agent nigdy samodzielnie nie zdecyduje, ż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ą z nich się kierował. Należy wybrać jedno miejsce dla każdej instrukcji. 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), który dostarcza agentowi nowe narzędzie zamiast nowej instrukcji.

Udostępnianie po sprawdzeniu przydatności

Umiejętność, która sprawdza się w tygodniu realnej pracy, jest warta utrwalenia. Umiejętności projektowe w .claude/skills/ są recenzowane tak samo jak kod i trafiają do 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 całkowity 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. Przygotowanie samych instrukcji w sposób zapewniający ich działanie po przeniesieniu do innego modelu to odrębne zadanie, które opisano w pisanie umiejętności działających z dowolnym modelem.

FAQ

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

Należy zachować limit 500 linii, przy czym większość przydatnych umiejętności jest znacznie krótsza. Treść pliku jest ładowana do konwersacji w momencie wywołania umiejętności i pozostaje w niej do końca sesji, więc każda linia generuje powtarzalny koszt, a nie jednorazowy. Długie materiały referencyjne należy przenosić do osobnych plików w katalogu umiejętności i łączyć je za pomocą 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ż 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 używane w zapytaniach. Jeśli opis jest 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 jej działanie do plików, nad którymi nie pracujesz. Inną przyczyną może być umieszczenie umiejętności w zagnieżdżonym katalogu .claude/skills/ poniżej katalogu startowego: ł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 zastosowanie dany element. 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 po wywołaniu, więc jest odpowiednim miejscem dla procedur istotnych 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 wykonał agent.

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

Należy porównać wynik z punktem odniesienia. 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 kluczowa, 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 automatyzuje to porównanie 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śnie zdecydować, czy umiejętność ma pozostać w Claude Code, czy być przenośna.