Agent Skills és SKILL.md: progresszív feltárás, mérve

A 14. fejezet felállította a kurzus második felének szabályát — a kapcsolatok, újrapróbálkozások és megszakítás TypeScriptben készülnek —, és megnevezett öt kivételt. Ez az egyik, és az ok nem ízlés kérdése.

A skill egy Markdown fájl. Nem olyan fájl, amely egy programot konfigurál, nem olyan fájl, amelyet egy program lefordít: hanem egy dokumentum, amelyet a modell olvas, ugyanúgy, ahogyan az általad beírt üzenetet olvassa. Ha programozási nyelvet adnánk ehhez a fejezethez, az azt jelentené, hogy nem értettük meg a formátumot, és pontosan ez a félreértés a leggyakoribb a skillekkel kapcsolatban. Lent minden Markdown és YAML, plusz egy kicsi shell script, amely éppen azért létezik, hogy megmutassa, hol van és hol nincs helye kódnak egy skillen belül.

Íme egy valódi utasítás: hogyan írja egy cég a release note-jait. Ez eljárás, nem preferencia — rendezett lépéssora, taxonómiája, hangja, template-je és egy scriptje van, amely összegyűjti a nyersanyagot.

Tedd mindezt a system promptba, ahogy a legtöbb csapat teszi, és átveszi az irányítást a 16. fejezet számtana. A system prompt prefix, a prefixért pedig minden hívásnál fizetsz. A fejezethez írt mappán o200k_base segítségével mérve:

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

Huszonnégyszer olcsóbb, amikor használják, harminchétszer olcsóbb, amikor nem. Az árak a 16. fejezet árai: $2.00 egymillió input tokenenként.

Most jön az őszinte ellenvetés, mert egy fejezet, amely ezt kihagyná, reklám lenne. A prompt caching nagyrészt bezárja a pénzbeli rést. A system prompt stabil és elöl ül, ami a lehető legjobb cache-jelöltté teszi; cached inputnál egymilliónként $0.20 mellett ugyanaz a 68 640 token $0.1373 helyett $0.0168-ba kerül. Még mindig háromszorosa a skillnek, de már nem más nagyságrend.

Soha nem a pénz volt a legerősebb érv. Hanem ez:

A caching olcsóbbá teszi az állandó prefixet. Kisebbé nem.

A 40. körben a system-promptos verzióban még mindig 1 716 tokennyi release-note szabályzat ül a windowban egy teljesen másról szóló beszélgetés közben, versengve azért, amit a 24. fejezet a modell attention-költségvetésének nevezett. A skilles verzióban 46. Ha rossz dolgot cache-elsz, kedvezményt vettél egy figyelemelterelésre.

Képletként írva, ahol $n$ a körök száma, $L_1$ a metadata, $L_2$ a törzs, $L_3$ a teljes csomag, $R$ pedig a ténylegesen olvasott csomagolt fájlok halmaza:

Az egész fejezet annak a különbségéről szól, hogy a második tagot $n$-nel szorozzuk-e, vagy eggyel, illetve nullával.

A skill egy könyvtár. A specifikáció elég rövid ahhoz, hogy teljes egészében kimondjuk:

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

A SKILL.md YAML frontmatterrel kell kezdődjön, és pontosan két mező kötelező: name és description.¹ További négy opcionális, és más mező nincs definiálva:

Íme a release-notes skill, teljes egészében, harminc sornál rövidebb törzzsel:

---
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.

Olvasd el, mi ez a törzs. Nem maga a szabályzat — hanem tartalomjegyzék műveleti sorrenddel. A szabályzat három olyan fájlban él, amelyet megnevez, de nem tartalmaz. Az első lépés pedig scriptnek adja át a munkát, mert egy script kódja soha nem kerül be a context windowba: csak a kimenete.²

A betöltési modellnek neve és három szakasza van. A specifikáció token-költségvetéssel együtt írja le őket:¹

1. Metadata, nagyjából 100 token: name és description, induláskor betöltve minden telepített skillhez.
2. Utasítások, ajánlottan 5 000 token alatt: a SKILL.md törzse, betöltve, amikor a skill aktiválódik.
3. Erőforrások, szükség szerint: csomagolt fájlok, csak akkor betöltve, amikor valami igényli őket.

A referenciadokumentáció ugyanerre a táblára egy negyedik oszlopot is tesz — mikor töltődik be, tokenköltség, tartalom —, és a fontos sor a harmadik: semmi, amíg nincs elérve.³ A mondat, amely az egész fejezetet összefoglalja, szintén ott van:

A fájlok addig nem fogyasztanak contextet, amíg hozzájuk nem férnek, így a skillek átfogó API-dokumentációt, nagy adathalmazokat vagy kiterjedt példákat is tartalmazhatnak. Nincs context-büntetés olyan csomagolt tartalomért, amelyet nem használnak.³

A fejezet elején lévő mért táblázat ennek az állításnak az ellenőrzése öt olyan skillen, amelyet senki nem ehhez a cikkhez írt. Két sort érdemes egymás ellenében olvasni.

A next-best-practices törzse 966 token, és tizenkilenc, összesen 19 374 tokent tartalmazó fájlra linkel. Kérd meg, hogy javítson egy hydration errort, és az agent a törzset plusz a hydration-error.md fájlt olvassa el: 1 409 token a 20 340-ből, tizennégyszeres szorzó, a másik tizennyolc fájlt pedig soha nem nyitja meg.

A next-cache-components törzse 2 334 token, és egyáltalán nincsenek csomagolt fájljai. Érvényes skill, ráadásul jól megírt, de nincs 3. szintje, amit feltárhatna. Ez a technika őszinte korlátja: a progresszív feltárás csak akkor megtakarítás, ha van mit elhalasztani. Egy skill, amelynek tudása nem bontható fel, aktiváláskor a teljes törzsét kifizeti, és az egyetlen megmaradó kar az, hogy ne aktiválódjon.

Az 1. szint egy útválasztási döntés egyetlen mondatból. Semmi más nem befolyásolja egy skillről, hogy valaha megnyitják-e — sem a törzs minősége, sem a példák, sem a scriptek. Ezért a leírás nem dokumentáció. Ez a query surface, és lehet hibás.

A specifikáció ezt egy jó és egy rossz példa formájában mondja ki, a rossz pedig négy szó: description: Helps with PDFs.¹ Ezt érdemes mérni, nem csak elfogadni.

Hat skill, mindegyikhez egy hihető leírás, amely megmondja, mit csinál és mikor kell használni. Huszonnégy kérés, skillenként négy, úgy megfogalmazva, ahogy egy ember fogalmazná, és soha nem nevezve meg a skillt. A modell látja a hat sort a system promptjában, és egy névvel vagy NONE-vel kell válaszolnia. Greedy decoding, hogy reprodukálható legyen. Aztán ugyanaz a huszonnégy kérés ugyanazzal a hat skillel, de a leírások a puszta tárgyukra visszavágva.

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

Először az intervallumokat olvasd, ahogy a 4. fejezet ragaszkodott hozzá, és ahogy a 29. fejezet is ragaszkodni fog: átfednek, és huszonnégy eset önmagában, összesített értékek alapján nem tud két rendszert rangsorolni. A párosított összehasonlítás dönti el, és ez a 15. fejezet eszköze: abból a tíz esetből, ahol a két ág eltért, kilenc a gazdag leírásokhoz ment, egy a vékonyakhoz. Ez a szokásos küszöbön megáll.

Most olvasd az utolsó sort, ami a tényleges eredmény. Vékony leírásokkal a modell a huszonnégy kérésből kilencnél NONE-szel válaszolt. Nem rossz skill: nincs skill. Íme négy közülük szó szerint:

"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

Telepítve volt egy tökéletes sql-review skill, törzzsel, példákkal és checklisttel, és soha nem nyílt meg, egymás után háromszor, annál a három kérdésnél, amelyre írták. A 2. és 3. szint irreleváns egy olyan skill számára, amelyet az 1. szint soha nem ér el.

A javítás költsége: 214 token, a 295 és 81 különbsége, hat skillre szétterítve. Ez a 18. fejezet megállapítása a másik oldalról érkezve. Ott pusztán egy tool leírásának megváltoztatása a dátumformázást 24-ből 2 helyesről 24-ből 24-re vitte. Itt pusztán egy skill leírásának megváltoztatása az aktiválást 24-ből 10-ről 18-ra viszi. Mindkét esetben a rendszer legolcsóbb javítása egy mondat, és mindkét esetben a mondatnak a triggert kell megneveznie, nem pusztán a tárgyat: nem azt, hogy mi a dolog, hanem azt, hogy mit mondott éppen a user, amikor alkalmazni kell.

Egy kitétel, amellyel ez a fejezet tartozik a saját mércéinek. Ez egy félmilliárd paraméteres modell, egy frontier modell pedig sokkal jobban route-ol, mint 75 %. A mechanizmust olvasd, ne a nagyságrendet: az útválasztási jel egy mondat hosszú, bármilyen modell olvassa is, és egyetlen modell sem tud olyan információ alapján választani, amelyet nem tettél bele abba a mondatba.

A második hiba az első ellentéte. A skill megtalálódik, a szintek helyesen vannak szétválasztva, az agent mégis elolvassa az egészet.

A vercel-react-best-practices valóban jól felépített skill. 1 670 tokenes törzse nyolc kategória prioritási táblája és egy gyors referencia, amely 70 szabályfájlt nevez meg, mindegyiket egy sorban. A szabályok mellette vannak a lemezen: 70 fájl, a legkisebb 132 token, a medián 319, a legnagyobb 1 052. Tegyél fel egy kérdést a barrel importokról, és az őszinte költség a törzs plusz egy fájl — 2 400 token alatt egy 53 670 tokenes csomaggal szemben.

Aztán a törzs utolsó sora ezt mondja:

## Full Compiled Document

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

A AGENTS.md 26 362 token. Ez a 70 szabályfájl összefűzve: az összegük 25 784, a különbséget a köztük lévő címsorok adják. Vagyis a skill választást kínál az agentnek aközött, hogy elolvas egy medián szabályt 319 tokenért, vagy ugyanazt a tartalmat, az egészet, nyolcvanháromszoros áron — és ezt a választást olyan mondatban kínálja, amelyhez nincs költség társítva, és nincs feltétele annak, mikor érdemes élni vele.

Ez nem bug, és a fájl nem hibás; egy összeállított dokumentum valóban hasznos egy embernek, és olyan agentnek is, amelyet egy teljes codebase auditálására kértek. Ez egy 3. szintű fájl 2. szintű meghívóval, és a tanulság túlmutat ezen az egy skillen: minden SKILL.md-ből kifelé vezető útvonalnak meg kell mondania, mibe kerül és mikor éri meg, mert a modellnek nincs módja tudni, hogy egy fájlnév nyolcvanháromszor drágább, mint a fölötte lévő fájlnév.

Ugyanez a mappa egy kisebb tanulságot is hordoz az elavulásról. A törzs azt mondja: „70 szabály 8 kategóriában”, és 70-et listáz; a rules/ könyvtárban 72 fájl van, amelyek közül kettő scaffolding (_template.md és _sections.md); a sidecar metadata.json pedig azt mondja: „40+ szabály”. Ugyanannak a halmaznak három darabszáma egy mappában: az egyik helyes, az egyik számtani, az egyik egy korábbi verzióból maradt ott. A skill dokumentum, a dokumentumok pedig pontosan úgy rohadnak, mint egy kódkomment, amely elcsúszott a mellette lévő kódtól — azzal a különbséggel, hogy ezt egy olyan gép olvassa, amely nem vonja fel a szemöldökét.

A nyílt specifikáció hat frontmatter mezőt definiál. A referencia-implementáció, a Claude Code, húszat fogad el.² Öt csoportot érdemes név szerint ismerni, mert ezeknél szűnik meg a formátum pusztán dokumentumnak lenni:

Az argumentumok (arguments, argument-hint) lehetővé teszik, hogy egy ember értékeket adjon át, amelyek behelyettesülnek a törzsbe; ettől használható a skill slash commandként. A scoping (paths) a globnak megfelelő fájlokra korlátozza az aktiválást. A dinamikus context injection pedig az, amely megváltoztatja a mentális modellt: egy !`git diff HEAD` alakú sor azelőtt fut le, hogy a törzset elküldenék, és a kimenete behelyettesül a szövegbe. A dokumentum template, és egy része olvasáskor számítódik ki.

Most a csapda, és ugyanaz a dokumentáció mondja ki: Claude Code-on kívül — a webes termékben, a Skills API-n keresztül, csomagoláskor — csak a hat specifikált mező megengedett, minden más mező hard error feltöltéskor.² Vagyis egy skill, amely tökéletesen működik az egyik termékben, nem telepíthető ugyanannak a vendornek egy másik termékébe, és már a frontmatternél elbukik, nem olyasminél, amit a próza elolvasásával tesztelni tudnál. Ha hordozható skillt akarsz, a hat mező a teljes költségvetés. Ha nem, mondd ki a compatibility mezőben, amely pontosan ezért létezik.

Négy dolgot állandóan összekevernek egymással, és a zavar nem szókincsbeli szőrszálhasogatás: ha rosszul választasz, minden körben pénzbe kerül, vagy elveszít egy garanciát, amelyről azt hitted, megvan.

A két félkövér sor a teljes különbség. A skillt olvassák; a toolt meghívják. A skill próza, amely megérkezik a context windowba, és minden mással verseng az attentionért; a modell követheti, félreolvashatja vagy figyelmen kívül hagyhatja, és a rendszerben semmi nem veszi észre. A tool olyan hívás, amely teljesen kikerül a modell kezéből: a kódod argumentumokat kap, validálja őket, ellenőrzi az engedélyeket és dönt. A 18. fejezet úgy fogalmazta meg, hogy a modell javasol, a kódod rendelkezik, és pontosan ez a felosztás az, amivel egy skill nem rendelkezik.

Tehát hat valódi eset, feloldva:

A történet rövid, szokatlanul jól dátumozott, és ez az a rész, amelyet szinte senki nem mesél el.

Az Agent Skills 2025. október 16-án jelent meg egy vendor funkciójaként, abban a bejelentésben úgy definiálva, mint „utasítások, scriptek és erőforrások rendezett mappái, amelyeket az agentek dinamikusan felfedezhetnek és betölthetnek, hogy jobban teljesítsenek konkrét feladatokban”, a három szintet pedig egy megőrzésre érdemes analógiával írta le: „mint egy jól szervezett kézikönyv, amely tartalomjegyzékkel kezdődik, aztán konkrét fejezetekkel folytatódik, végül részletes függelékkel zárul”.⁴

2025. december 18-án ugyanaz az oldal frissült, és a formátumot nyílt szabványként jelentette be, saját specifikációval a agentskills.io címen, hozzájárulások előtt nyitott governance-szel és referencia-validatorral.³ 2026. szeptember 7-én olvasva a szabvány client showcase-e negyvenhat terméket listáz — editorokat, terminálokat, cloud platformokat és mobile runtime-okat, köztük az Anthropic, az OpenAI, a Google és a Mistral first-party coding agentjeit —, mindegyik saját setup dokumentációra linkelve.¹

Az MCP-vel való konvergencia nyíltan zajlik, ellenőrizhető számokkal:

Az érdekes rész a lezárás, nem a javaslatok. A SEP-2076 egy negyedik primitive-et kért a tools, resources és prompts mellé. A belőle kialakult munkacsoport úgy döntött, a válasz nem: a skillek a már létező resources primitive-en utaznak, opt-in extensionként.⁵ A 26. fejezet ugyanezt az ösztönt mérte a protokoll saját changelogjában, ahol a samplinget, rootsot és loggingot deprecálták, nem megtartották. Egy szabványügyi testület, amely eltávolít egy saját maga által írt javaslatot, jól viselkedik; azért érdemes ezt a történetet a számokkal együtt elmondani, mert a máshol olvasott összefoglalók még mindig MCP primitive-ként írják le a skilleket.

Most már tudsz SKILL.md-t írni, három olyan szintre bontani, amelyek megtérítik az árukat, elolvasni valaki más skilljének frontmatterét és tudni, mely mezők nem élik túl, ha máshová töltik fel, valamint válaszolni arra a kérdésre, amely köré az egész fejezet épült — system prompt, skill, tool vagy server — okkal, nem megszokásból.

Azt viszont nem tudod megmondani, hogy a tiéd működik-e.

Ebben a fejezetben minden fontos állítás mérés volt, és a legfontosabb egy pontosság: 24-ből 18 a 24-ből 10 ellen, mindkettőn intervallummal és köztük párosított teszttel, mert két átfedő összesítés semmit nem dönt el. Ezt az eszközt kölcsönvettük. Egy skill leírása routing key, a törzse pedig olyan eljárás, amelyet a modell vagy követ, vagy nem; mindkettő olyan tulajdonság, amelyet csak úgy tudsz megismerni, ha sokszor lefuttatod a dolgot, és pontozod, mi jött vissza — ez pedig golden set, a futás előtt megírt grader, és az a metrika, amely azt kérdezi, hogy minden alkalommal működött-e, nem azt, hogy legalább egyszer.

A 29. fejezet erről szól, és azzal a számmal nyit, amelytől ennek a fejezetnek a módszere függ: egy agent, amely tízből hétszer sikeres, 70 %-osnak tűnik, az pass^10-ja — az esélye, hogy mind a tízszer sikerül — pedig nulla. Ugyanazon a kétszáz transcript-en három gradert is mér, és 0 %-ot, 13 %-ot és 26 %-ot kap anélkül, hogy egyetlen tokent újragenerálna. Mielőtt megbízol abban a mondatban, amelyet épp egy description-ba írtál, szükséged van arra az eszközre, amely meg tudja mondani, hogy rosszabb annál, amelyet lecseréltél.

Ebben a fejezetben minden token-szám helyben készült tiktoken 0.14.0-val és a o200k_base encodinggal, 2026. szeptember 7-én: a fejezet elején felsorolt öt, harmadik féltől származó skillen, valamint a fejezethez írt release-notes skillen, amelynek teljes szövege fent részben reprodukálva van. Az 1. szintet az egyetlen - name: description sorként mértem, amelyet egy host a system promptba renderel; a 2. szint a SKILL.md törzse a frontmatter után; a 3. szint a mappában lévő minden más fájl. A költségek a 16. fejezet gpt-5.6-terra-ra mért árait használják, $2.00 egymillió input tokenenként és $0.20 egymillió cached input tokenenként, ezekre a darabszámokra alkalmazva — mért tokeneken végzett számtanról van szó, nem élő számla megfigyeléséről. A fejezet megírásához nem történt fizetős API-hívás.

Az aktiválási kísérlet Qwen/Qwen2.5-0.5B-Instruct-t futtatott fél precizitással egy consumer GPU-n, greedy decodinggal, 24 kéréssel hat skillen, kétszer — egyszer olyan leírásokkal, amelyek megmondják, mit csinál a skill és mikor alkalmazandó, egyszer pedig a specifikáció saját „rossz példa” stílusában puszta tárgyra vágott leírásokkal. Az intervallumok 95 %-os Wilson-intervallumok; a párosított összehasonlítás kétoldali exact sign test a tíz eltérő eseten; a Wilson-intervallum a 4. fejezeté, az exact paired sign test a 15. fejezeté, mindkettő változtatás nélkül újrahasználva. A nagyságrendeket egy nagyon kicsi modell tulajdonságaként olvasd, a módszert pedig átvihetőként.

Az itt mért öt skill harmadik féltől származó csomag, nem ehhez a fejezethez íródott: next-best-practices és next-cache-components a vercel-labs/next-skills repositoryból, valamint vercel-composition-patterns, vercel-react-best-practices és vercel-react-native-skills a vercel-labs/agent-skills repositoryból. Belső számaikat — 70 szabályfájl, AGENTS.md 26 362 tokennel, metadata.json 2026. januári dátummal és „40+ rules” állítással — a lemezen lévő fájlokból olvastam ki 2026. szeptember 7-én, és ezek az adott publikált verzió tulajdonságai, nem a szerzőik kritikái: mindegyik olyan drift, amely bármely dokumentációfában megjelenik, ha gyakrabban szerkesztik, mint ahányszor megszámolják.