Strona główna / Artykuły

Tworzenie dobrych umiejętności agenta Claude: lekcje z projektu trenera biegowego

Tworzenie umiejętności agenta Claude, która jest wytrzymała: precyzyjne opisy, oceny przed pisaniem tekstu, plik SKILL.md jako router, skrypty zamiast tekstu oraz rozdzielenie uprawnień w procesie CI.

Wydawca: REACTAPP.TOP13 min czytania3097 słów

Źródła: I Missed My Running Goal Three Years Running. So I Built an Agent Skill.

Załóżmy biegacza, który przez trzy lata z rzędu stawiał sobie cel 1000 km, ale za każdym razem go nie osiągał, kończąc te trzy lata z łączną odległością około 2500 km. Problemem nie była motywacja. Zdarzały się kontuzje, konieczność restartu oraz intensywne tygodnie. Brakowało planu, ponieważ motywacja działa dobrze dopóki, aż nagle przestaje.

Jedną z rozwiązań jest przestanie polegania na sile woli i stworzenie systemu. W ten sposób powstało running-coach – umiejętność agenta Claude, która planuje poszczególne wybiegania i całe tygodnie na podstawie własnej historii osoby, przekształca każdy tydzień w podsumowanie e-mailowe w stylu artykułu prasowego, a nawet dostosowuje długość listy odtwarzania do długości nadchodzącego biegu.

Bieganie jest tu jedynie tłem. Bardziej istotnym tematem jest to, co jest potrzebne do rozwoju dobrej umiejętności – takiej, która działa niezawodnie, oszczędnie wykorzystuje kontekst, zachowuje się identycznie na każdej platformie i nie traci efektywności z upływem czasu. Poniżej każda z opublikowanych przez Anthropic praktyk tworzenia została powiązana z sposobem, w jaki projekt je stosuje.

Czym jest umiejętność agenta

Umiejętność to folder. W jego korzeniu znajduje się plik SKILL.md, który zaczyna się od danych YAML zawierających name i description, a następnie zawiera instrukcje w formacie Markdown. Obok niego mogą znajdować się dokumenty referencyjne, skrypty, szablony oraz inne zasoby.

Ciekawą kwestią jest sposób ładowania umiejętności, przy użyciu trójpoziomowego modelu zwanego stopniowym ujawnianiem informacji:

  • Poziom 1, metadane. Zawsze ładowane przy uruchomieniu, po około 100 tokenów na umiejętność. Składają się one wyłącznie z nazwy i opisu.
  • Poziom 2, instrukcje. Ładowane tylko w momencie aktywacji umiejętności i utrzymywane w granicach około 5 tysięcy tokenów. To treść pliku SKILL.md.
  • Poziom 3, zasoby. Ładowane na żądanie za pomocą bash, dostępne do użycia dopóki nie zostaną zmodyfikowane. Tutaj znajdują się pliki referencyjne, skrypty i zasoby.

Anthropic porównuje umiejętność do przewodnika wprowadzającego napisanego dla nowego pracownika. Podstawową zasadą jest to, że okno kontekstowe jest wspólne i stanowi dobro publiczne. To, co jest zużywane przez daną umiejętność, nie jest dostępne dla reszty informacji, które agent próbuje zapamiętać.

1. Opis pełni rolę API

Na poziomie 1 całe to, co model widzi dotyczące danej umiejętności, to jej opis. Pełni on raczej rolę tabeli routingu niż dokumentacji, ponieważ model porównuje przychodzącą prośbę z tym opisem, aby zdecydować, czy uruchomić daną umiejętność. Opis musi określać, co robi ta umiejętność i kiedy należy jej używać, być napisany w trzeciej osobie oraz mieć długość poniżej 1 024 znaków, przy czym praktycznym limitem jest około 200 znaków, jeśli chcesz, aby został wyświetlony w całości w narzędziu wyboru claude.ai. Oto opis używany przez running-coach:

name: running-coach
description: >-
  Plans a run or a whole week as Google Calendar blocks, builds a weekly
  running digest email, and makes playlists — from Strava, Spotify, AccuWeather
  and Calendar. Use for pacing or planning a week.

Spójrz, jak to zostało skonstruowane. Zaczyna się od tego, co umie ta umiejętność (planowanie wyprawy, tworzenie streszczeń, tworzenie list odtwarzania), następnie wskazuje, kiedy należy z niej skorzystać (do ustalania tempa lub planowania tygodnia), oraz opisuje źródła danych, dzięki czemu pytanie w stylu Stravy odwołuje się do tej umiejętności. Nazwa jest pisana małymi literami i jest identyczna z nazwą katalogu – to surowa zasada, a nie preferencja stylistyczna, której przestrzega proces budowania projektu, jak pokażemy później.

Nie można z góry wiedzieć, czy opis będzie skuteczny. Trzeba go przetestować, dlatego pierwszą rzeczą w repozytorium jest zbiór ocen, a nie dokumentacja.

2. Napisz oceny przed dopracowaniem tekstu

Porada firmy Anthropic polega na tym, aby najpierw stworzyć mechanizmy oceny, dzięki czemu rozwiązuje się istniejące problemy, a nie te, które sobie wyobrażono. Projekt zawiera cztery pliki z scenariuszami w folderze evals/ – po jednym dla każdej umiejętności. Nie są to testy jednostkowe. Są to umowy behawioralne napisane prostym językiem. Oto plik przeznaczony do planowania wykonywania testów:

{
  "skills": ["running-coach"],
  "query": "I'm heading out for 8k this evening, how long is that going to take me?",
  "expected_behavior": [
    "Triggers the running-coach skill without being named, and routes to the planning capability",
    "Reads references/run-planning.md and does not read the digest or playlist references",
    "Runs scripts/cache.py status before projecting…",
    "Executes scripts/planning/plan_run.py 8 rather than reading its source or reimplementing Riegel inline",
    "Reports the projected finish time, the pace, and the recommended effort band…",
    "Never asks for or uses a Strava access token"
  ]
}

Każde stwierdzenie koduje najlepszą praktykę. Uruchamianie testów bez podania ich nazwy sprawdza jakość opisu testów. Czytanie tylko odpowiednich testów referencyjnych to przykład stopniowego ujawniania informacji. Uruchomienie skryptu bez jego ponownej implementacji sprawdza preferencję za skryptami zamiast tekstem opisowym. Nie dotykanie żadnego tokena sprawdza granice uprawnień. Razem przekształcają one całą filozofię projektowania w obserwowalne zachowanie, a reszta procesu budowy polega na zapewnieniu, by te zachowania były spełniane.

3. Utrzymywanie SKILL.md jako routera

Najczęstszym sposobem marnowania zasobów kontekstowych danej umiejętności jest umieszczanie tam wszystkiego. Lepszym podejściem jest traktowanie tego pliku jako spisu treści, który w razie potrzeby odsyła do bardziej szczegółowych materiałów. Trzymaj go krótkim i umieszczaj odniesienia na jednym poziomie głębokości, ponieważ agenci zazwyczaj czytają głęboko zagnieżdżone pliki tylko częściowo, w rezultacie mając tylko część obrazu całości.

Cztery z tych umiejętności wymagałyby po jednej stronie na wyjaśnienie, więc SKILL.md nie opisuje żadnej z nich. Skierowuje on do:

| Capability     | Reference                        | Entry point                       |
| -------------- | -------------------------------- | --------------------------------- |
| Plan a run     | references/run-planning.md       | scripts/planning/plan_run.py      |
| Plan the week  | references/week-planning.md      | scripts/planning/plan_week.py     |
| Weekly digest  | references/weekly-digest.md      | scripts/digest/run_pipeline.py    |
| Run playlist   | references/run-playlist.md       | scripts/playlist/build_playlist.py|

Work out which one is wanted, then read only that capability's reference.

Prosząc o playlistę, agent otwiera plik run-playlist.md i nic więcej. Specyfikacja procesu pracy digest, jego pułapki oraz uwagi dotyczące szablonów nigdy nie trafiają do kontekstu, ponieważ nie używany zawartość nie kosztuje nic. Poziom 2 pozostaje prosty, a poziom 3 dostarcza dokładnie jeden plik. Wiersz „czyta X, nie czyta Y” w procesie ewaluacji dokładnie to weryfikuje.

4. Skrypty zamiast tekstu: uruchamiaj je, nie czytaj

To może być najcenniejsza idea w projektowaniu umiejętności. Gdy agent uruchamia skrypt za pomocą bash, do kontekstu trafia tylko wynik, a nigdy sam kod źródłowy. Z góry napisane skrypty są również bardziej niezawodne niż kod tworzony na bieżąco, a zawsze dają ten sam wynik.

Zatem logika running-coach znajduje się w Pythonie, a instrukcje wyraźnie mówią agentowi, aby nie zajmował się kodem źródłowym:

**Run the scripts, don't read them.** They print everything needed; every one
takes --help and most take --json. Reading their source wastes context.

Prognoza czasu ukończenia przez Riegel, obliczenia związane z zakresem wysiłku oraz analiza streszczenia są wykonywane za pomocą deterministycznego Pythona i zwracają zwięzłą odpowiedź. Agent koordynuje te procesy, a nie przelicza je ponownie. Porównaj agenta, który ocenia twoją prędkość – która jest wolna, zmienna i wymagająca dużej ilości zasobów – z agentem, który używa kalkulatora prędkości i podaje wynik; ten drugi działa szybko i zawsze daje ten sam rezultat.

5. Każdy skrypt to prawidłowa interfejs CLI z wspólnymi konwencjami

Aby zasada „uruchom to, nie czytaj tego” funkcjonowała, agent musi uruchamiać skrypt, którego otwieranie jest mu zabronione. To wymaga jednolitej, samoodnoszącej się interfejsu, dzięki czemu każdy skrypt stosuje te same konwencje:

  • jeden argument pozycyjny dla elementu zawsze wymaganego (odległość, przy planowaniu i tworzeniu list odtwarzania);
  • --data DIR we wszystkich miejscach, dzięki czemu każdy skrypt może odwoływać się do innego cache’u, co umożliwia testowanie offline oraz użycie sandboxów na poziomie sesji;
  • --json w niemal wszystkich z nich, tak że wynik jednego skryptu może być użyty przez następny;
  • --help w każdym z nich – to opcja awaryjna agenta, gdy nie jest pewien co do danej flagi. Agent czyta tekst pomocy, co jest tanie i nie wymaga dostępu do źródła kodu, który jest kosztowny i niedostępny.

Oto opis poszczególnych funkcji.

Planowanie wykonywania wykorzystuje plan_run.py:

python3 scripts/planning/plan_run.py 8                 # 8 km, defaults
python3 scripts/planning/plan_run.py 8 --band steady   # force an effort band
python3 scripts/planning/plan_run.py 8 --start-in 3    # start 3h from now (weather-aware)
python3 scripts/planning/plan_run.py 8 --json          # machine-readable plan

Jedynym obowiązkowym argumentem jest distance_km. Opcjonalnymi flagami są --exp, która dostosowuje wykładnik zmęczenia Riegel, oraz --band, która określa konkretny zakres wysiłku. Jeśli nie zostaną podane żadne specjalne ustawienia, program wyznacza ten zakres na podstawie dotychczasowego obciążenia treningowego biegacza. Część heurystyczna zapewnia pewną swobodę, podczas gdy dokładna projekcja pozostaje deterministyczna.

Lista odtwarzania jest obsługiwana przez build_playlist.py, który celowo naśladuje strukturę planera:

python3 scripts/playlist/build_playlist.py 8                    # size to the 8 km finish
python3 scripts/playlist/build_playlist.py 8 --genre "lo-fi"
python3 scripts/playlist/build_playlist.py 8 --minutes 55       # size by time instead
python3 scripts/playlist/build_playlist.py 8 --band hard

Ponieważ obie operacje zajmują tę samą odległość pozycyjną, te dwie funkcje się łączą: czas zakończenia plan_run odpowiada czasowi trwania build_playlist, który określa długość listy odtwarzania. Skrypt wytwarza polecenie, a nie listę odtwarzania, a agent przekazuje to polecenie do łącznika Spotify. Tutaj ponownie pojawia się rozróżnienie między funkcjami – skrypt zajmuje się obliczeniami, natomiast agent zajmuje się operacjami wejścia/wyjścia.

Weekly Digest to niewielki pipeline, a nie monolit. run_pipeline.py weryfikuje pamięć cache, a następnie uruchamia dwa etapy:

python3 scripts/digest/run_pipeline.py                 # validate → analyse → render
python3 scripts/digest/run_pipeline.py --plan-km 8     # lead the digest with a planned run
python3 scripts/digest/run_pipeline.py --seed 3        # pin the masthead title choice
python3 scripts/digest/run_pipeline.py --skip-validate # skip the pre-flight cache check

Poniżej tego analyze.py agreguje zapisaną w pamięci tymczasowej informację o tygodniu do pliku digest_data.json, a build_email.py przekształca ten plik JSON w samodzielny e-mail w formacie HTML. Rozdzielenie analizy od renderowania oznacza, że e-mail można przestylizować bez ingerencji w proces analizy, a flaga --seed umożliwia powtarzalne wybór jednej losowej wartości – tytułu nagłówka – co jest przydatne przy robieniu dwóch zrzutów ekranu tego samego tygodnia.

Planowanie tygodnia to najciekawszy interfejs wiersza poleceń, ponieważ stanowi łańcuch operacji: planowanie, weryfikacja i wykonywanie, wyrażony jako podpolecenia, przez które agent przechodzi w określonej kolejności:

python3 scripts/planning/plan_week.py goal       # show the weekly goal in force
python3 scripts/planning/plan_week.py propose    # propose the split of runs (as JSON)
python3 scripts/planning/plan_week.py draft   --split -   # lay the split across the days
python3 scripts/planning/plan_week.py brief   --draft -   # hand the agent a per-run contract
python3 scripts/planning/plan_week.py events  --draft - --content -   # emit calendar blocks

Każdy etap wyświetla JSON, który następny etap odbiera ze stdin. Tam, gdzie to możliwe, etapy przyjmują również powszechne opcje modyfikacji (--km, --runs) oraz opcje planowania, takie jak --start-date, --time, --weekend-time, --location i --tz. Wytyczne zalecają tę formę „sprawdzalnych wyników pośrednich” dla złożonych zadań: agent nigdy nie tworzy planu samodzielnie. Wysyła on ustrukturyzowany plan, skrypt go sprawdza i kształtuje, a dopiero potem przekształca go w wydarzenia kalendarzowe.

W połowie procesu następuje celowe przekazanie obowiązków. Na etapie brief skrypt oblicza odległość, przedział tempa i dzień wykonywania zadania, a następnie przekazuje agentowi umowę dla każdego z wyścigów. Agent wpisuje słowa brzmiące naturalnie, dzięki czemu opisy wyścigów nie są identyczne. Skrypt odpowiada za to, co musi być dokładne, natomiast model za to, co powinno brzmieć jak tekst napisany ręcznie. Niska swoboda w przypadku skomplikowanych obliczeń matematycznych i wysoka swoboda w przypadku prozy to zasada „odpowiednich stopni swobody” w ramach jednego polecenia.

6. Rozwiązywaj problemy, nie odkładaj ich

Słaba umiejętność powoduje, że trudne przypadki trafiają do agenta wraz z niejasnymi poleceniami typu „jeśli dane wydają się przestarzałe, znajdź rozwiązanie”. Sformułowanie w Anthropic zakłada rozwiązanie problemu, a nie jego odkładanie: należy obsłużyć warunki błędów w skrypcie i nie delegować ich innym. running-coach stosuje to za pomocą modelu świeżości – dla każdego zasobu danych w pamięci podręcznej rejestruje jego wiek, a status określa dokładną funkcję MCP, która pozwoli załatać każdą lukę:

python3 scripts/cache.py status                 # what's cached, how stale, what to call
python3 scripts/cache.py put streams --file -    # ingest an MCP response from stdin
python3 scripts/cache.py show week --json        # a compact summary, not the raw blob
python3 scripts/cache.py validate --for digest   # shape-check before a run

cache.py zawiera cztery funkcje (status, put, show, validate), z których każda stanowi kolejny etap w procesie odświeżania danych. Funkcja status wyświetla każdą kluczową wartość wraz z jej limitem aktualności – ten limit jest krótki dla bieżącego tygodnia, ponieważ zmienia się przy każdym uruchomieniu, natomiast dla zakończonych tygodni oraz danych sportowców wynosi tydzień; w przypadku starych lub brakujących danych wyświetla konkretny narzędzie MCP do wywołania. Agent wykonuje to wywołanie i przekazuje uzyskaną odpowiedź bezpośrednio do funkcji put. Następnie funkcja validate --for <capability> sprawdza, czy wynik jest użyteczny, zanim zostanie uruchomiony kolejny skrypt, dzięki czemu błędne pobranie danych zostaje zatrzymane natychmiast z komunikatem o błędzie, zamiast pojawić się później jako nieprawidłowy zbiór danych.

Dodatkowe zabezpieczenia: funkcja put przyjmuje tylko klucze z ustalonej listy dozwolonych, funkcja show wyświetla streszczenie, a nie surowy JSON, dzięki czemu inspekcja pamięci cache nie wprowadza do kontekstu megabajtów danych GPS, a agent otrzymuje instrukcję, by nie edytować tych plików JSON ręcznie. W rezultacie agent nie musi decydować, czy pobrać dane ponownie ani co pobrać, ponieważ to określa skrypt. Subiektywna ocena ("czy to wystarczająco świeże?") zamienia się w precyzyjną instrukcję, co dokładnie ma na myśli komenda cache.py status przed przetwarzaniem danych.

7. Granice uprawnień

To kluczowa decyzja architektoniczna, a także praktyka bezpieczeństwa: kontrola nieoczekiwanych połączeń sieciowych i wzorców dostępu do plików. Ta technologia sprawia, że taka kontrola jest z natury prosta, ponieważ nic w jej składzie nie przechowuje danych uwierzytelniających ani nie otwiera połączeń sieciowych.

agent --(Strava / Spotify / AccuWeather MCP)--> cache.py put --> the cache
the cache --> plan_run.py / run_pipeline.py / build_playlist.py --> output

Tylko agent komunikuje się z konektorami MCP, a tylko cache.py zapisuje dane w pamięci cache. Wszystkie pozostałe skrypty jedynie przetwarzają dane z pamięci cache offline, bez żadnego klienta HTTP, bez kluczy API oraz bez tokenów dostępu w całym pakiecie.

# cache.py — the only gateway to the running-coach data cache.
# The agent is the only thing that talks to MCP; this script is the only thing
# that reads or writes the cache. Nothing here needs an access token.

Wynikają z tego trzy zalety. Pod względem bezpieczeństwa nie ma nic, co mogłoby wyciec, a powierzchnia sieci do audytu jest pusta. Jeśli chodzi o przenośność, umiejętność ta nie zależy od tego, czy połączenia są lokalne, zdalne czy ich brakuje, ponieważ korzysta jedynie z pamięci cache. Co do testowalności, wypełniona pamięć cache umożliwia pełne uruchomienie każdego skryptu offline, co sprawia, że możliwe stają się testy wstępne w środowisku CI.

8. Jeden wymóg sprzętowy: Python 3.10

Umiejętności nie synchronizują się między różnymi powierzchniami, a każda z nich ma własne ograniczenia sprzętowe. API Claude nie oferuje dostępu do sieci ani możliwości instalacji pakietów, podczas gdy Claude Code posiada wszystko to. Aby umiejętność mogła działać wszędzie, należy projektować ją z myślą o najbardziej ograniczonym środowisku.

Dlatego running-coach nie łączy się z żadnymi zewnętrznymi zasobami. Nie ma pliku requirements.txt, nie ma środowiska virtualenv ani etapu instalacji. W instrukcjach podano, że wystarczy Python 3.10 lub nowsza wersja, a prosty python3 działa bez żadnych zmian, nawet w hostowanym środowisku sandbox, gdzie instalacja pakietów jest niemożliwa.

Wszystko, czego potrzebuje ta umiejętność, znajduje się w katalogu skills/running-coach/. Umieszczenie tego folderu w ~/.claude/skills/ umożliwia korzystanie z Claude Code, a przesłanie go w formie pliku .zip służy do pracy z Cowork lub claude.ai – zachowanie jest identyczne we wszystkich przypadkach. Wszystkie ścieżki zawierają tylko kreski przedrostkowe, co pozwala uniknąć problemów międzyplatformowych. Pliki cache i wyników są przechowywane poza katalogiem umiejętności, dzięki czemu zainstalowana kopia pozostaje tylko do odczytu, i nigdy nie są zapisywane do git, ponieważ cache zawiera rzeczywiste poliliny GPS, które po dekodowaniu tworzą trasy zaczynające się przy drzwiach wejściowych danej osoby.

9. Sprawdzanie opakowania i CI wspierające twierdzenia

Opakowanie to krok, który ludzie pomijają. Umiejętność z niewłaściwym zainstalowaniem wygląda na uszkodzoną w sposób niewidoczny na pierwszy rzut oka: archiwum z luźnymi plikami u jego korzenia jest cicho odrzucane podczas przesyłania. Dlatego projekt zawiera plik package.py – walidator bez zależności, który powtarza sprawdzenia znajdujące się w własnym repozytorium umiejętności Anthropic. Walidator sprawdza dozwolone klucze frontmatter, nazwę w formacie kebab-case odpowiadającą katalogowi, długość opisu zgodną z specyfikacją (z ostrzeżeniem przy granicy około 200 znaków w narzędziu claude.ai) oraz archiwum zawierające dokładnie jeden katalog najwyższego poziomu z plikiem SKILL.md u jego korzenia.

Następnie GitHub Actions blokuje każdą publikację na podstawie tych sprawdzeń. Gdy zostanie wrzucona tagowa nazwa v*, proces działania:

  1. byte-compiles każdy skrypt (python -m compileall) w celu wykrycia błędów składniowych;
  2. sprawdza frontmatter zgodnie z specyfikacją;
  3. uruchamia każdy punkt wejścia z opcją --help, co przynajmniej pokazuje, że każdy skrypt importuje i parsuje kod w czystym środowisku Python 3.10;
  4. weryfikuje, czy plik running-coach/SKILL.md znajduje się w korzeniu archiwum;
  5. i dopiero po tym wszystkim publikuje plik zip.
# 3.10 is the version the skill claims to support, so building on it is
# also how that claim stays honest.
- uses: actions/setup-python@v5
  with:
    python-version: "3.10"

Lekcje, które uogólniają

Z całego procesu budowy wyróżnia się kilka kluczowych punktów:

Opis składa się z około 100 tokenów, które realizują 90% pracy. Ponieważ to jedyna część, która zawsze jest ładowana, brak jej uruchomienia sprawia, że wszystko inne staje się bez znaczenia. Należy poświęcić mu szczególną uwagę oraz dodać testy sprawdzające uruchomienie bez wymieniania nazwy umiejętności.

Przenieś logikę z promptów do deterministycznych skryptów. Tekst, który czyta agent, jest zmienny i kosztuje tokeny, natomiast skrypt, który jest wykonywany, jest tani i zawsze daje ten sam wynik. Zasada brzmi: należy wykonywać, a nie czytać.

Zaufaj granicy, którą można sformułować w jednym zdaniu. „Tylko agent komunikuje się z MCP, jeden skrypt zapisuje cache, wszystko inne działa offline” jest cenniejsze niż mnóstwo kodu obronnego, ponieważ całe grupy błędów i wycieków stają się strukturalnie niemożliwe do wystąpienia.

Niech proces budowania sprawdzi twoje twierdzenia. Umiejętność, która obiecuje Python 3.10 i zerowe zależności, powinna być budowana dokładnie w ten sposób w środowisku CI przy każdym wydaniu. Bez tego obietnica pozostaje jedynie nadzieją.

Sam cel biegania pozostaje otwarty, ale teraz istnieje „trener”, który planuje tydzień, daje szczere oceny w poniedziałek rano i co tydzień ponownie oblicza cel na podstawie przebiegu z poprzedniego tygodnia. Bieganie stało się rozwiązywalnym problemem inżynieryjnym, gdy zaczęto je tak traktować.

Każdy, kto instaluje taką umiejętność, musi mieć włączoną możliwość wykonywania kodu oraz własnego łącznika Strava, ponieważ umiejętność nie zawiera żadnych danych uwierzytelniających. To samo dotyczy źródeł, które warto przeczytać: przegląd umiejętności Agent Skills firmy Anthropic oraz strona z zasadami tworzenia umiejętności, obie dostępne w dokumentacji Claude Platform.

Literatura pokrewna

  • Hermes i Obsidian: Skarbiec wiedzy z trzema agentami i ludzką weryfikacją — W Hermesie konfiguruje się orkiestratora, badacza i bibliotekarza, którzy przenoszą notatki z poziomu Brązu na Srebro, a następnie na Złoto do skarbcu w Obsidianie, przy użyciu izolacji Docker i weryfikacji.