Umiejętności agenta to kod: określ zakres, ujawnij informacje, napisz skrypt i przetestuj je

Plik SKILL.md przypomina dokumentację, ale jego edycja zmienia zachowanie agenta. Dzięki temu jest bliższy kodowi niż prozie i powinien być projektowany, definiowany oraz testowany zgodnie z tymi kryteriami.

Umiejętności to nie dokumentacja

Zwykłą pierwszą reakcją przy tworzeniu umiejętności w modelu LLM jest chęć napisania więcej: wyjaśnienia architektury, dodania przykładów, opisania przypadków krawędziowych oraz dostarczenia kontekstu, aby model zrozumiał, dlaczego rzeczy działają w określony sposób. Ta reakcja jest zazwyczaj błędna.

Umiejętność to nie podręcznik dla programisty uczącego się twojego systemu. To kontekst wprowadzany do agenta, który jest zajęty realizacją jakiegoś zadania. Ta różnica kształtuje cały projekt. Kluczowe pytanie nie brzmi, jak wyjaśnić system modelowi, ale co agent musi wiedzieć, aby prawidłowo podjąć następną decyzję.

Z tego punktu widzenia kilka wyborów staje się prostszych:

• pisać instrukcje w formie procedur
• określać dokładnie warunki aktywacji
• ładować informacje stopniowo
• przenosić zadania deterministyczne do skryptów
• testować umiejętności na rzeczywistych zadaniach

Tylko wiedza proceduralna

Współczesne agenty kodujące już obsługują zaskakująco dużą ilość zadań związanych z ogólnym inżynierią oprogramowania. Znają Git i npm, a także rozumieją Angular, React, TypeScript, SQL, REST API, frameworki do testowania oraz konfigurację CI. Umiejętność polegająca jedynie na powtarzaniu tych elementów prawie nic nie wnosi:

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Spala kontekst, nie dostarczając niczego, czego brakowało modelowi. Umiejętności, które warto posiadać, obejmują wiedzę specyficzną dla twojego środowiska:

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Tutaj agent nauczył się czegoś, czego nie mógł wiarygodnie wywnioskować z publicznej dokumentacji Angular, a mianowicie tego, jak powinna przebiegać praca w konkretnym repozytorium. W tym właśnie celu przydają się umiejętności.

Format Agent Skills organizuje to jako katalog zawierający plik SKILL.md oraz opcjonalne skrypty i zasoby. Metadane są dostępne w celach odkrywania, a pełne instrukcje i pliki pomocnicze ładują się tylko wtedy, gdy jest to konieczne. Format pliku nie jest kluczowym elementem – kluczowym jest rozróżnienie między ogólnymi możliwościami modelu a wiedzą, którą musi dostarczyć środowisko.

Kontekst to „budżet”

Wszystko, co jest przekazywane agentowi, wymaga kontekstu. Opisy narzędzi, schematy narzędzi MCP, instrukcje dotyczące repozytorium, historia rozmów oraz opisy umiejętności – wszystko to go zużywa, a treść aktywowanej umiejętności zużywa jeszcze więcej. Dlatego pytanie nie brzmi tylko o to, czy jakieś informacje są przydatne, ale o to, czy są one przydatne do wykonywanej zadania.

Załóżmy, że te umiejętności są zainstalowane:

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Gdy zadaniem jest naprawa niepracującego testu jednostkowego w Angular, agent nie musi znać procesu wypuszczania aplikacji ani kroków debugowania w PostgreSQL. Dlatego właśnie poznanie tych informacji jest niemal tak ważne jak sam content. Porównaj dwa opisy – ten tutaj można uruchomić z największą łatwością:

---
name: testing
description: Helps run tests in our repository.
---

To jest o wiele dokładniejsze:

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

Druga descripcja robi więcej niż tylko opisuje, czym jest dana umiejętność. Określa ona granice routingu, które chronią nieistotne instrukcje przed dostępem do kontekstu pracy. Wykład na temat projektowania umiejętności dla agentów LLM dobrze ilustruje ten punkt: metadane umiejętności nie są jedynie dekoracją administracyjną. Niedbale sformułowane reguły aktywacji wprowadzają przydatne instrukcje do niewłaściwych zadań, natomiast reguły zbyt restrykcyjne uniemożliwiają w ogóle znalezienie danej umiejętności.

Krok po kroku zamiast ogromnego SKILL.md

Częstym błędem jest pozwolenie, by plik SKILL.md przerodził się w małą wewnętrzną witrynę informacyjną. Zaczyna się od dwudziestu linijek, potem ktoś dodaje kroki implementacji, następnie rozwiązania problemów, przykłady i opcje konfiguracji. Po trzech miesiącach agent musi przeczytać 1 500 linijek, aby zmienić jeden plik.

Zamiast tego strukturyzuj go w taki sposób, jak strukturyzowałbyś oprogramowanie:

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md zawiera wtedy jedynie logikę routingu:

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

Szczegółowe instrukcje testowe pojawiają się w kontekście tylko wtedy, gdy zadanie wymaga testowania. Anthropic określa to jako stopniowe ujawnianie informacji: agent najpierw ładuje metadane, czyta treść główną, gdy umiejętność okazuje się istotna, a pliki odniesione otwiera później, tylko w razie potrzeby. Celem nie jest przekazanie jak największej ilości wiedzy, lecz dostarczenie właściwej wiedzy we właściwym momencie.

Niech skrypty egzekwują to, co mogą egzekwować

Pomaga również inne rozróżnienie: instrukcje służą do podejmowania decyzji, natomiast skrypty do wykonywania zadań deterministycznych. Wyobraźmy sobie umiejętność, która mówi coś takiego:

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Agent może to wykonać, ale tylko poprzez wielokrotne sprawdzanie katalogów, interpretację plików, określanie tego, co stanowi archiwum, śledzenie stanu oraz prawdopodobnie wykonywanie wielu wywołań narzędzi. Gdy operacja może być sformułowana dokładnie, należy ją zapisać tylko raz:

node scripts/check-angular-versions.mjs

Następnie ta umiejętność po prostu podaje, kiedy ją uruchomić i co zrobić z wynikiem:

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

To ma liczne zalety. Skrypt można przetestować w formie testów jednostkowych i zawsze zachowuje się tak samo. Wymaga mniej decyzji modelu oraz często mniej wywołań narzędzi. A gdy coś się nie uda, można odtworzyć ten błąd bez konieczności proszenia LLM o powtórzenie jego rozumowania.

To wcale nie oznacza zastępowania agentów skryptami. Oznacza wybór odpowiedniej abstrakcji. Używaj modelu do podejmowania decyzji, na przykład do określenia, które projekty mogą zostać dotknięte zmianą architektury. Używaj kodu do realizacji dokładnych algorytmów, na przykład do wylistowania projektów, które importują dany pakiet. Agent koordynuje oba te elementy, a taka kombinacja jest lepsza niż zapisanie całego procesu w języku angielskim.

Narzędzia i umiejętności rozwiązują różne problemy

Narzędzie dostarcza agentowi akcję, natomiast umiejętność uczy, kiedy i jak tę akcję używać. Narzędzie w linii poleceń może umożliwić obliczenie projektów, które zostały dotknięte:

tr project affected --base main

Narzędzie zapewnia taką możliwość. Umiejętność dopasowywania dostarcza wiedzy organizacji:

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

CLI nie ma pojęcia, dlaczego pięć dotkniętych aplikacji powinno wydawać się podejrzane, a specjalista nie musi znać mechanizmów przeszukiwania zależności. To jest jasna granica. Ta sama zasada obowiązuje, gdy funkcjonalność jest dostarczana przez polecenie w shellu, API internetowe, serwer MCP lub jakąkolwiek inną interfejs – nie ukrywaj zasad w narzędziach niskiego poziomu, chyba że faktycznie tam należą, i nie pisz algorytmów deterministycznych w formie tekstu opisowego, chyba że jest to konieczne.

Więcej umiejętności nie oznacza automatycznie lepszych rezultatów

Kuszącym podejściem w rozwoju agentów jest gromadzenie umiejętności o atrakcyjnym wyglądzie, ich instalowanie we wszystkich i zakładanie, że agent staje się bardziej zdolny. Dowody wskazują jednak na konieczność znacznie większej selektywności.

SkillsBench obejmuje 86 zadań z 11 dziedzin. Zgodnie z pierwszą wersją publikacji, umiejętności dobrane starannie podniosły średni procent zdawalności o 16,2 punktu procentowego, przy dużych różnicach pomiędzy poszczególnymi dziedzinami. Inżynieria oprogramowania poprawiła się zaledwie o 4,5 punktu, a u 16 z 84 zadań wyniki się pogorszyły po dodaniu umiejętności. Umiejętności samodzielnie stworzone przez same modele nie przyniosły żadnej średniej poprawy.

SWE-Skills-Bench przeanalizował 49 publicznych umiejętności stosowanych w rzeczywistych zadaniach z inżynierii oprogramowania. U 39 z nich nie zaobserwowano poprawy w procentie zdawalności, a średnia poprawa wyniosła zaledwie 1,2 punktu. Kilka wysoce specjalistycznych umiejętności, łącznie siedem, poprawiło wyniki o aż 30 punktów. Kolejne trzy negatywnie wpłynęły na wyniki, obniżając je o maksymalnie 10 punktów, ponieważ ich wskazówki odnosiły się do innej wersji niż ta użyta w projekcie.

To pasuje do tego, co przewiduje architektura. Umiejętność ogólna konkuruje z tym, co model już wie, natomiast umiejętność bardzo specyficzna może dostarczyć dokładnie tego brakującego faktu:

When our generated API clients change, regenerate schemas before running typecheck.

To ma wartość. To ma znacznie mniej:

Always think carefully before modifying APIs.

Zasada ogólna: nie twórz umiejętności tylko dlatego, że istnieje zadanie. Twórz ją wtedy, gdy istnieją procedury, których agent ciągle nie potrafi zastosować.

Umiejętności wymagają testów

To może być największa zmiana koncepcyjna. Ponieważ modyfikacja pliku SKILL.md wpływa na zachowanie agenta, konsekwencje przypominają zmiany w kodzie:

• Usunięcie jednej instrukcji może sprawić, że agent pominie konieczną weryfikację.
• Rozszerzenie opisu może skutkować aktywacją umiejętności podczas wykonywania niepowiązanych z nią zadań.
• Dodanie obszernego dokumentu referencyjnego może prowadzić do zwiększonego zużycia tokenów bez lepszych rezultatów.
• Zmiana procedury może spowodować spadek wskaźników skuteczności.

Dlatego należy to przetestować. W przypadku umiejętności zajmującej się migracjami w Angularze, zbiór do oceny może zawierać zadanie takie jak:

Upgrade application A from Angular 20 to Angular 21.

z takimi oczekiwaniami:

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Drugi zadanie:

Upgrade a shared library consumed by applications A and B.

z własnymi oczekiwaniami:

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

A trzecie:

Modify a React application in the same monorepo.

którego oczekiwany wynik to brak aktywacji:

Expected:
- Angular migration skill is NOT activated

Ten ostatni przypadek ma takie samo znaczenie jak każdy udany test, więc sprawdź obie strony: umiejętność powinna się tu aktywować, a nie tam. Narzędzie o nazwie SkillGrade opiera się na tej koncepcji. Określ zadania, uruchamiaj agenta wielokrotnie, a następnie oceniaj każdy test za pomocą dokładnych sprawdzeń, rubryki opracowanej przy użyciu LLM na podstawie nagranej sesji lub obu tych metod jednocześnie. Możesz stosować tę zasadę nawet bez niego. Chodzi o to, by traktować umiejętność jako coś, co może ulec regresji. Zmień umiejętność, nie będąc w stanie stwierdzić, czy nowa wersja jest lepsza od starej, i edytujesz wtedy logikę produkcyjną bez żadnych testów.

Zaczynaj od niepowodzeń, a nie od rynku umiejętności

Najprostszym sposobem na stworzenie bezużytecznych umiejętności jest zadanie sobie pytania, jakie umiejętności powinien mieć agent programistyczny. Otrzymasz listę tematów takich jak testowanie, debugowanie, przegląd kodu, dokumentacja, architektura, workflow w Git, dostępność, bezpieczeństwo oraz dwadzieścia innych zagadnień, które model już doskonale rozumie.

Lepszym punktem wyjścia jest własna historia agenta. Szukajmy powtarzających się niepowodzeń. Być może agent:

• wykonywa cały zestaw testów w ogromnym monorepo zamiast skupić się na dotkniętym projekcie
• ciągle narusza granice zależności w repozytorium
• wybiera technicznie poprawną ścieżkę migracji, ale pomija wewnętrzny krok związany z kompatybilnością
• modyfikuje pliki wygenerowane, zamiast schematów, które je tworzą
• spędza pięć minut na ponownym odkrywaniu tej samej procedury debugowania za każdym razem, gdy jeden z usług zawodzi

To są kandydaci na umiejętności. Cykl życia wygląda następująco: obserwacja powtarzającego się niepowodzenia, zidentyfikowanie brakującej wiedzy proceduralnej, napisanie najmniejszej przydatnej umiejętności, przeniesienie deterministycznych kroków do skryptów, stworzenie reprezentatywnych zadań oceniających, pomiary, a następnie zachowanie, udoskonalenie lub usunięcie tej umiejętności. Udoskonalanie prowadzi z powrotem do jej przepisania.

Uważaj na ostatnią opcję, ponieważ usunięcie jest dopuszczalne. Umiejętność, która nie poprawia zachowania, nie jest bezpieczna – dodaje kontekst, obciążenie konserwacyjne oraz kolejną instrukcję, która może później wejść w konflikt z czymś innym.

Prawdziwą abstrakcją jest kontrolowany kontekst

Ludzie często opisują umiejętności jako sposób na rozszerzanie agentów. To prawda, ale to ukrywa ciekawszy problem inżynieryjny. Dostarczanie informacji agentowi jest łatwe; trudniejsze jest decydowanie, które informacje staną się istotne podczas danej eksploatacji.

Dobrze zaprojektowane środowisko agenta przypomina raczej system oprogramowania składający się z warstw, niż jeden ogromny prompt. Zawsze obecne są ogólne informacje modelu oraz krótkie instrukcje globalne. Dopiero gdy zadanie ich wymaga, wykorzystywane są umiejętności specyficzne dla danego zadania, warunkowo ładowane odniesienia, narzędzia deterministyczne oraz kontekst repozytorium w czasie wykonywania. Każda warstwa ma swoje zadanie. Gdy te obowiązki się zacierają, kontekst staje się nadmiernie rozbudowany, co utrudnia zrozumienie zachowania agenta. Jeśli je oddzielić, umiejętności stają się przyjemnie monotonne, co jest dobrym rozwiązaniem.

Dobra umiejętność to nie efektowny prompt – to zwięzła porcja wiedzy proceduralnej, która zostaje wykorzystana we właściwej sytuacji, korzysta z narzędzi deterministycznych tam, gdzie to możliwe, i sprawdza się pod kątem błędów, których ma zapobiegać.

Literatura pokrewna

• Pięć warstw agent harness, wraz z kodem, który nie działa bez nich — Praktyczny przegląd pięciu miejsc, w których agent harness egzekwuje zasady w kodzie, od granic wykonywania po łańcuchy kontekstowe, oraz tego, co badania mogą, a czego nie mogą udowodnić.
• Używanie Codex w VS Code: zakres działania, punkty odzyskiwania oraz rozwiązania najczęstszych problemów — Praktyczny przewodnik po rozszerzeniu Codex dla VS Code: instalacja, logowanie, pierwsze zadanie agenta, użycie chmury w porównaniu z interfejsem wiersza poleceń, wspólna konfiguracja oraz rozwiązania problemów z WSL, zatwierdzenia i autoryzacją zdalną.