Agent Skills i SKILL.md: zmierzona progresywna prezentacja

Rozdział 14 ustalił regułę dla drugiej połowy tego kursu — połączenia, ponowienia i anulowanie są w TypeScript — oraz ogłosił pięć wyjątków. To jedno z nich, a powodem nie jest preferencja.

Skill to plik Markdown. Nie plik konfigurujący program, nie plik kompilowany przez program: dokument, który model czyta, tak samo jak czyta wiadomość, którą wpisałeś. Przypisanie temu rozdziałowi języka programowania oznaczałoby niezrozumienie formatu, a to nieporozumienie jest najczęstsze w rozmowach o skill. Wszystko poniżej to Markdown i YAML, plus jeden mały skrypt powłoki, który istnieje właśnie po to, by pokazać, gdzie kod należy, a gdzie nie należy w skill.

Oto prawdziwa instrukcja: jak pewna firma pisze swoje informacje o wydaniu. To procedura, nie preferencja — ma uporządkowany zestaw kroków, taksonomię, głos, szablon i skrypt, który zbiera materiał źródłowy.

Włóż to wszystko do system prompt, jak robi większość zespołów, a arytmetyka z rozdziału 16 przejmuje stery. System prompt jest prefiksem, a za prefiks płaci się przy każdym wywołaniu. Pomiar z użyciem o200k_base na folderze napisanym do tego rozdziału:

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

Dwadzieścia cztery razy taniej, gdy jest użyty, trzydzieści siedem razy taniej, gdy nie jest. Stawki są z rozdziału 16: $2,00 za milion token wejściowych.

Teraz uczciwy kontrargument, bo rozdział, który by go pominął, byłby reklamą. Prompt caching w dużej mierze zamyka lukę kosztową. System prompt jest stabilny i znajduje się na początku, co czyni go najlepszym możliwym kandydatem do cache; przy $0,20 za milion cached input te same 68 640 token kosztuje $0,0168 zamiast $0,1373. Nadal trzy razy więcej niż skill, ale już nie o rząd wielkości.

Pieniądze nigdy nie były najmocniejszym argumentem. Tym jest to:

Caching sprawia, że stały prefiks jest tańszy. Nie sprawia, że jest mniejszy.

W turze 40 wersja z system-prompt nadal ma 1 716 token polityki informacji o wydaniu siedzących w oknie podczas rozmowy o czymś zupełnie innym, konkurujących o to, co rozdział 24 nazwał budżetem attention modelu. Wersja skill ma 46. Zrób cache złej rzeczy, a kupiłeś zniżkę na rozproszenie.

Jako formuła, z $n$ turami, $L_1$ metadanymi, $L_2$ treścią, $L_3$ całym pakietem i $R$ zbiorem faktycznie przeczytanych plików z pakietu:

Cały ten rozdział to różnica między mnożeniem drugiego składnika przez $n$ a mnożeniem go przez jeden albo przez zero.

Skill to katalog. Specyfikacja jest na tyle krótka, że można ją przytoczyć w całości:

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md musi zaczynać się od YAML frontmatter i wymagane są dokładnie dwa pola: name oraz description.¹ Cztery kolejne są opcjonalne i nie zdefiniowano żadnych innych:

Oto kompletny skill do informacji o wydaniu, z treścią poniżej trzydziestu linii:

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

Zwróć uwagę, czym jest ta treść. To nie polityka — to spis treści z kolejnością działań. Polityka żyje w trzech plikach, które wskazuje, ale których nie zawiera. A krok pierwszy przekazuje pracę skryptowi, bo kod skryptu nigdy nie wchodzi do context window: wchodzi tylko jego wynik.²

Model ładowania ma nazwę i trzy etapy. Specyfikacja opisuje je z przypisanym budżetem token:¹

1. Metadane, około 100 token: name i description, ładowane przy starcie dla każdego zainstalowanego skill.
2. Instrukcje, zalecane poniżej 5 000 token: treść SKILL.md, ładowana, gdy skill zostanie aktywowany.
3. Zasoby, według potrzeb: dołączone pliki, ładowane tylko wtedy, gdy coś ich wymaga.

Dokumentacja referencyjna dodaje do tej samej tabeli czwartą kolumnę — kiedy ładowane, koszt token, zawartość — i najważniejszy jest trzeci wiersz: brak, dopóki nie zostanie użyte.³ Jest tam też zdanie podsumowujące cały rozdział:

Pliki nie zużywają context, dopóki nie zostaną użyte, więc Skills mogą zawierać rozbudowaną dokumentację API, duże zbiory danych albo obszerne przykłady. Nie ma kary w context za dołączoną zawartość, która nie jest używana.³

Tabela zmierzona na początku tego rozdziału to sprawdzenie tej tezy na pięciu skill, których nikt nie pisał na potrzeby tego artykułu. Dwa wiersze warto czytać razem.

next-best-practices ma treść o długości 966 token, która linkuje do dziewiętnastu plików zawierających 19 374 token. Poproś go o naprawienie błędu hydration, a agent czyta treść plus hydration-error.md: 1 409 token z 20 340, czynnik czternaście, a pozostałe osiemnaście plików nigdy nie zostaje otwartych.

next-cache-components ma treść o długości 2 334 token i nie ma żadnych dołączonych plików. To poprawny skill i dobrze napisany, ale nie ma poziomu 3 do odsłonięcia. To uczciwa granica techniki: progresywna prezentacja oszczędza tylko wtedy, gdy jest coś do odroczenia. Skill, którego wiedza się nie rozkłada, płaci za całą treść przy aktywacji, a jedyną pozostałą dźwignią jest nieaktywowanie go.

Poziom 1 to decyzja routing podejmowana na podstawie jednego zdania. Nic innego w skill nie wpływa na to, czy kiedykolwiek zostanie otwarty — ani jakość treści, ani przykłady, ani skrypty. Opis nie jest więc dokumentacją. Jest powierzchnią zapytania i może być błędny.

Specyfikacja mówi to w formie dobrego i złego przykładu, a zły przykład ma cztery słowa: description: Helps with PDFs.¹ Warto to zmierzyć, zamiast po prostu przyjąć.

Sześć skill, każdy z wiarygodnym opisem, który mówi, co robi i kiedy go używać. Dwadzieścia cztery żądania, po cztery na skill, sformułowane tak, jak sformułowałby je człowiek, i nigdy nienazywające skill. Model widzi sześć linii w swoim system prompt i ma odpowiedzieć jedną nazwą albo NONE. Greedy decoding, więc wynik jest odtwarzalny. Potem te same dwadzieścia cztery żądania z tymi samymi sześcioma skill, ale z opisami skróconymi do gołego tematu.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

Najpierw czytaj przedziały, jak nalegał rozdział 4 i jak znów będzie nalegał rozdział 29: nakładają się, a dwadzieścia cztery przypadki nie pozwalają uszeregować dwóch systemów wyłącznie po agregatach. Rozstrzyga porównanie sparowane, a to instrument z rozdziału 15: spośród dziesięciu przypadków, w których dwa ramiona się nie zgadzały, dziewięć przypadło bogatym opisom, a jeden cienkim. To jest ustalone na zwykłym progu.

Teraz przeczytaj ostatnią linię, która jest właściwym wynikiem. Przy cienkich opisach model odpowiedział NONE na dziewięć z dwudziestu czterech żądań. Nie zły skill: żaden skill. Oto cztery z nich, dosłownie:

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

Zainstalowany był idealny skill sql-review, z treścią, przykładami i checklistą, a mimo to nigdy nie został otwarty, trzy razy z rzędu, przy trzech pytaniach, do których został napisany. Poziomy 2 i 3 są nieistotne dla skill, do którego poziom 1 nigdy nie dociera.

Koszt naprawy: 214 token, różnica między 295 a 81, rozłożona na sześć skill. To wynik z rozdziału 18 nadchodzący z drugiej strony. Tam zmiana wyłącznie opisu narzędzia podniosła formatowanie dat z 2 poprawnych na 24 do 24 na 24. Tutaj zmiana wyłącznie opisu skill podnosi aktywację z 10 na 24 do 18. W obu przypadkach najtańszą poprawką w systemie jest zdanie, i w obu przypadkach zdanie musi nazwać trigger, a nie tylko temat: nie czym dana rzecz jest, ale co użytkownik właśnie powiedział, gdy ma zastosowanie.

Jedno zastrzeżenie, które ten rozdział jest winien własnym standardom. To model o pół miliarda parametrów, a frontier model radzi sobie z routing znacznie lepiej niż 75%. Czytaj mechanizm, nie wielkość efektu: sygnał routing ma długość jednego zdania niezależnie od modelu, który go czyta, a żaden model nie może wybierać na podstawie informacji, której nie umieściłeś w tym zdaniu.

Druga awaria jest przeciwieństwem pierwszej. Skill zostaje znaleziony, poziomy są poprawnie rozdzielone, a agent i tak czyta wszystko.

vercel-react-best-practices to naprawdę dobrze zbudowany skill. Jego treść o długości 1 670 token to tabela priorytetów ośmiu kategorii i szybki skrót wskazujący 70 plików reguł, po jednej linii każdy. Reguły leżą obok na dysku: 70 plików, najmniejszy 132 token, mediana 319, największy 1 052. Zadaj jedno pytanie o barrel imports, a uczciwy koszt to treść plus jeden plik — poniżej 2 400 token wobec pakietu 53 670.

A potem ostatnia linia treści mówi to:

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md ma 26 362 token. To sklejone 70 plików reguł: ich suma to 25 784, a różnica to nagłówki między nimi. Skill daje więc agent wybór między przeczytaniem jednej medianowej reguły za 319 token a przeczytaniem tej samej zawartości, całej, za cenę osiemdziesiąt trzy razy wyższą — i oferuje ten wybór w zdaniu bez przypisanego kosztu i bez warunku, kiedy warto z niego skorzystać.

To nie jest bug i plik nie jest zły; skompilowany dokument jest naprawdę użyteczny dla człowieka oraz dla agent poproszonego o audyt całej bazy kodu. To plik poziomu 3 z zaproszeniem poziomu 2, a lekcja uogólnia się poza ten jeden skill: każda ścieżka wychodząca z SKILL.md powinna mówić, ile kosztuje i kiedy jest tego warta, bo model nie ma jak wiedzieć, że jedna nazwa pliku jest osiemdziesiąt trzy razy droższa od nazwy pliku nad nią.

Ten sam folder niesie mniejszą lekcję o nieświeżości. Treść mówi „70 rules across 8 categories” i wymienia 70; katalog rules/ zawiera 72 pliki, z których dwa są rusztowaniem (_template.md i _sections.md); a boczny metadata.json mówi „40+ rules”. Trzy liczniki tego samego zbioru w jednym folderze: jeden poprawny, jeden arytmetyczny i jeden pozostały po wcześniejszej wersji. Skill jest dokumentem, a dokumenty gniją dokładnie tak jak komentarz w kodzie, który rozjechał się z kodem tuż obok — z tą różnicą, że ten dokument czyta maszyna, która nie uniesie brwi.

Otwarta specyfikacja definiuje sześć pól frontmatter. Implementacja referencyjna, Claude Code, akceptuje dwadzieścia.² Pięć grup warto znać z nazwy, bo to tam format przestaje być tylko dokumentem:

Argumenty (arguments, argument-hint) pozwalają człowiekowi przekazać wartości podstawiane do treści, co sprawia, że skill nadaje się do użycia jako slash command. Zakres (paths) ogranicza aktywację do plików pasujących do glob. A dynamic context injection to element, który zmienia model mentalny: linia w formie !`git diff HEAD` uruchamia się przed wysłaniem treści, a jej wynik zostaje podstawiony do tekstu. Dokument jest szablonem, a część zostaje obliczona w chwili czytania.

Teraz pułapka, i jest podana w tej samej dokumentacji: poza Claude Code — w produkcie webowym, przez Skills API, przy pakowaniu — dozwolone jest tylko sześć pól ze specyfikacji, a każde inne pole jest twardym błędem przy uploadzie.² Skill, który działa idealnie w jednym produkcie, nie instaluje się więc w innym należącym do tego samego dostawcy, i zawodzi na frontmatter, a nie na czymkolwiek, co dałoby się przetestować przez przeczytanie prozy. Jeśli chcesz, by skill był przenośny, te sześć pól to cały budżet. Jeśli nie chcesz, powiedz to w compatibility, które istnieje dokładnie po to.

Cztery rzeczy są ciągle ze sobą mylone, a to zamieszanie nie jest słowną pedanterią: zły wybór kosztuje pieniądze w każdej turze albo odbiera gwarancję, którą myślałeś, że masz.

Dwa pogrubione wiersze są całym rozróżnieniem. Skill jest czytany; narzędzie jest wywoływane. Skill to proza, która trafia do context window i konkuruje o attention ze wszystkim innym, co się tam znajduje; model może ją wykonać, źle odczytać albo zignorować, a system niczego nie zauważy. Narzędzie to wywołanie, które całkowicie wychodzi z rąk modelu: twój kod dostaje argumenty, waliduje je, sprawdza uprawnienia i decyduje. Rozdział 18 ujął to tak, że model proponuje, a twój kod rozporządza — i to rozdzielenie jest dokładnie tym, czego skill nie ma.

A więc sześć prawdziwych przypadków, rozstrzygniętych:

Historia jest krótka, wyjątkowo dobrze datowana i to jej część prawie nikt nie opowiada.

Agent Skills opublikowano 16 października 2025 jako funkcję jednego dostawcy, zdefiniowaną w tamtym ogłoszeniu jako „organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks”, z trzema poziomami opisanymi przez analogię wartą zachowania: „like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix”.⁴

18 grudnia 2025 tę samą stronę zaktualizowano, ogłaszając format jako otwarty standard, z własną specyfikacją pod adresem agentskills.io, governance otwartym na wkład i walidatorem referencyjnym.³ Odczytana 7 września 2026 wizytówka klientów standardu wymienia czterdzieści sześć produktów — edytory, terminale, platformy chmurowe i środowiska uruchomieniowe mobilne, w tym first-party coding agents od Anthropic, OpenAI, Google i Mistral — każdy z linkiem do własnej dokumentacji konfiguracji.¹

Zbieżność z MCP odbywa się jawnie, z liczbami, które możesz sprawdzić:

Ciekawe jest zamknięcie, nie propozycje. SEP-2076 prosił o czwarty primitive obok tools, resources i prompts. Working group, która z niego powstała, zdecydowała, że odpowiedź brzmi nie: skills jadą na primitive resources, który już istnieje, jako rozszerzenie opt-in.⁵ Rozdział 26 zmierzył ten sam instynkt w changelogu samego protokołu, gdzie sampling, roots i logging zdeprecjonowano zamiast zachować. Organ standaryzacyjny, który usuwa własną propozycję, zachowuje się dobrze, a powód, by opowiedzieć tę historię z liczbami na wierzchu, jest taki, że streszczenia, które przeczytasz gdzie indziej, nadal opisują skills jako MCP primitive.

Umiesz już napisać SKILL.md, rozdzielić go na trzy poziomy, które same się opłacają, przeczytać frontmatter cudzego skill i wiedzieć, które pola nie przetrwają uploadu gdzie indziej, oraz odpowiedzieć na pytanie, wokół którego zbudowano cały rozdział — system prompt, skill, narzędzie czy serwer — z uzasadnieniem, a nie z przyzwyczajenia.

Nie umiesz natomiast stwierdzić, czy twój działa.

Każde istotne twierdzenie w tym rozdziale było pomiarem, a najważniejsze było accuracy: 18 z 24 wobec 10 z 24, z przedziałem dla każdego i testem sparowanym między nimi, bo dwa nakładające się agregaty niczego nie rozstrzygają. Ten instrument został pożyczony. Opis skill jest kluczem routing, jego treść jest procedurą, którą model może, ale nie musi wykonać, i obie te właściwości da się poznać tylko przez wielokrotne uruchomienie rzeczy i ocenienie tego, co wróciło — czyli golden set, grader napisany przed uruchomieniem oraz metrykę, która pyta, czy zadziałało za każdym razem, a nie przynajmniej raz.

Rozdział 29 jest właśnie o tym i zaczyna się od liczby, na której opiera się metoda z tego rozdziału: agent, który odnosi sukces siedem razy na dziesięć, wygląda jak 70%, a jego pass^10 — szansa, że odniesie sukces we wszystkich dziesięciu — wynosi zero. Mierzy też trzy graders na tych samych dwustu transkryptach i dostaje 0%, 13% oraz 26% bez regenerowania ani jednego token. Zanim zaufasz zdaniu, które właśnie wpisałeś do description, potrzebujesz instrumentu, który powie ci, że jest gorsze od tego, które zastąpiłeś.

Każde zliczenie token w tym rozdziale zostało wykonane lokalnie za pomocą tiktoken 0.14.0 i kodowania o200k_base, 7 września 2026: na pięciu skill firm trzecich wymienionych na początku tego rozdziału oraz na skill release-notes napisanym do tego rozdziału, którego pełny tekst częściowo odtworzono powyżej. Poziom 1 mierzony jest jako pojedyncza linia - name: description, którą host renderuje do system prompt; poziom 2 to treść SKILL.md po frontmatter; poziom 3 to każdy inny plik w folderze. Koszty używają stawek zmierzonych w rozdziale 16 dla gpt-5.6-terra, $2,00 za milion token wejściowych i $0,20 za milion cached input tokens, zastosowanych do tych liczników — to arytmetyka na zmierzonych token, a nie obserwacje z prawdziwego rachunku. Do napisania tego rozdziału nie wywołano żadnego płatnego API.

Eksperyment aktywacji uruchomił Qwen/Qwen2.5-0.5B-Instruct w half precision na jednej konsumenckiej karcie GPU, greedy decoding, 24 żądania na sześć skill, dwa razy — raz z opisami, które mówią, co skill robi i kiedy ma zastosowanie, raz z opisami skróconymi do gołego tematu w stylu „poor example” z samej specyfikacji. Przedziały to Wilson przy 95%; porównanie sparowane to dwustronny exact sign test na dziesięciu przypadkach niezgodnych; przedział Wilsona pochodzi z rozdziału 4, a exact paired sign test z rozdziału 15, oba użyte bez zmian. Wielkości efektu czytaj jako właściwość bardzo małego modelu, a metodę jako przenośną.

Pięć skill zmierzonych tutaj to pakiety firm trzecich, nie napisane na potrzeby tego rozdziału: next-best-practices i next-cache-components z vercel-labs/next-skills oraz vercel-composition-patterns, vercel-react-best-practices i vercel-react-native-skills z vercel-labs/agent-skills. Ich wewnętrzne liczniki — 70 plików reguł, AGENTS.md przy 26 362 token, metadata.json datowany na styczeń 2026 i twierdzący „40+ rules” — odczytano z plików na dysku 7 września 2026 i są właściwościami tej opublikowanej wersji, nie krytyką autorów: każdy z nich to rodzaj dryfu, który pojawia się w każdym drzewie dokumentacji edytowanym częściej, niż jest liczone.