Agent Skills

Stopniowe ujawnianie

Trzy poziomy, te same trzy, które opisuje specyfikacja:

• Katalog. W każdej turze prompt agenta zawiera menu skilli, które wyglądają na istotne: tytuł, jednolinijkowy opis, slug. Nigdy treść. Domyślnie trzy skille na turę, najwyżej sześć.
• Aktywacja. Agent wywołuje narzędzie load_playbook ze slugiem, aby przeczytać pełne kroki. Argument slug jest w każdej turze związany z enumem dokładnie tych slugów, które są w menu tej tury – wymyślona nazwa jest odrzucana przed wysłaniem, zamiast kosztować agenta rundę zapytania. Gdy nie ma menu, narzędzie w ogóle nie jest rejestrowane.
• Zasoby. Jeszcze nie. Skill jest tu pojedynczym plikiem SKILL.md; dołączone katalogi scripts/, references/ i assets/ są parsowane i ignorowane, zamiast być obsługiwane w połowie.

Gdy skill zostanie wczytany, pozostaje wczytany. Przebiegi agentów kompaktują starsze wyniki narzędzi, by ograniczyć koszt, a aktywowane skille są z tego wyłączone: ich instrukcje przetrwają dosłownie do końca przebiegu, choćby był bardzo długi. Skill, który po cichu znika w trakcie zadania, jest gorszy niż taki, który nigdy się nie wczytał.

Które skille trafiają do menu

Dwa przebiegi. Słowa wyzwalające są dopasowywane do tury jako podciągi, bez rozróżniania wielkości liter; potem przebieg semantyczny uzupełnia listę na podstawie embeddingu tytułu, opisu, wyzwalaczy i początku treści każdego skilla, dopuszczając tylko to, co przekracza skalibrowany próg podobieństwa. Skill bez wyzwalaczy jest zawsze włączony i zawsze oferowany. Model sam decyduje, co aktywować – nic tu nie narzuca mu skilla.

Jak dodać skill

• Biblioteka. Wyselekcjonowane pakiety, instalowane na agencie jednym kliknięciem. To powierzchnia odkrywania, z której korzysta większość osób.
• Napisz własny. Tytuł, opis, słowa wyzwalające i kroki, w zakładce Playbooks agenta.
• API. POST /api/agents/:id/playbooks/import przyjmuje { files: [{ name, content }] } i importuje każdy plik niezależnie – jeden zły plik zawodzi sam, a reszta i tak trafia na miejsce. Każdy plik jest skanowany pod kątem bezpieczeństwa, zanim cokolwiek zostanie zapisane, a import nigdy nie nadpisuje istniejącego skilla: kolizja sluga wraca jako pominięta.
• Skompiluj skill z dokumentu. POST /api/agents/:id/playbooks/generate przyjmuje { artifactId } – dokument już znajdujący się w workspace’ie – albo { content, sourceName } i zapisuje procedurę na podstawie tego, czego uczy dokument: kiedy ma zastosowanie, kroki, reguły decyzyjne, słownictwo. To nie jest potok uploadu, który zamienia dokument w fragmenty, które agent może wyszukać; tu staje się czymś, co agent robi. Procedura jest pisana od nowa, nigdy nie jest wyciągiem: źródłem może być cudza chroniona prawem autorskim instrukcja, a playbook, który by ją cytował, byłby jej kopią. Długie dokumenty są czytane od początku do limitu, a odpowiedź mówi, kiedy je ucięto. Wynik przychodzi nieaktywny: nikt nie napisał tych słów, więc człowiek czyta szkic i go włącza, albo nigdy się nie uruchomi.

W interfejsie celowo nie ma przycisku uploadu. SKILL.md staje się stałą instrukcją dla agenta, który dysponuje narzędziami workspace’u, więc dowolny wgrany plik to wektor prompt injection, a nie wygoda. Wyjątkiem jest celowo przewidziana trasa API tylko dla właściciela, opisana wyżej.

Jak wyeksportować skill

Każdy skill eksportuje się jako zip zawierający <name>/SKILL.md – strukturę katalogów opisaną w specyfikacji, a nie luźny plik. Rozpakuj go do ~/.agents/skills/ lub .claude/skills/, a wczyta się w tym kliencie bez zmieniania czegokolwiek, i skills-ref validate przechodzi na nim bez poprawek. Wywołujący API, którzy chcą samego pliku, mogą zamiast tego poprosić o text/markdown.

Frontmatter zawiera name i description. Nasze własne rozszerzenia – słowa wyzwalające, kolejność i znacznik mówiący, że plik pochodzi stąd – są umieszczone w metadata, ponieważ referencyjny walidator specyfikacji odrzuca nieznane klucze najwyższego poziomu, a nasz eksport nigdy nie powinien być plikiem, na którym zawodzi.

Czego nie respektujemy

• allowed-tools jest zawsze odrzucane. Specyfikacja definiuje je jako narzędzia zatwierdzane z góry dla skilla, czyli dokładnie to, czego nie wolno przyjmować z pliku przychodzącego przez API lub z udostępnionego pakietu: zaimportowana treść mogłaby poszerzyć własne uprawnienia do narzędzi. To, jakich narzędzi agent może używać, jest cechą jego roli, nigdy pliku, który przeczytał.
• compatibility jest odrzucane z bardziej prozaicznego powodu: opisuje środowisko, dla którego napisano skill, co nic nie mówi o naszym.
• Wszystko poza udokumentowanym frontmatterem jest ignorowane zamiast zgadywane. Parser przyjmuje niewielką, stałą postać zdefiniowaną w specyfikacji i nic egzotycznego.

Limity

Trzydzieści skilli na agenta, 64 kB na zaimportowany plik i ograniczona treść – skill, który nie mieści się już w tym budżecie, to dwa skille. Nazwy składają się z małych liter, cyfr i pojedynczych myślników: specyfikacja dopuszcza więcej, ale nazwa jest tu także adresem URL.

Gdzie indziej

Specyfikacja jest wiążąca dla formatu. Informacje o API HTTP, którego agenci używają do działania w sieci, znajdziesz w dokumentacji API.