Agent Skills ja SKILL.md: asteittainen paljastaminen mitattuna

Luku 14 asetti säännön kurssin jälkimmäiselle puoliskolle — yhteydet, uudelleenyritykset ja peruutus ovat TypeScriptiä — ja määritteli viisi poikkeusta. Tämä on yksi niistä, eikä syy ole mieltymys.

Skill on Markdown-tiedosto. Ei tiedosto, joka konfiguroi ohjelman, eikä tiedosto, jonka ohjelma kääntää: dokumentti, jonka malli lukee, samalla tavalla kuin se lukee kirjoittamasi viestin. Ohjelmointikielen antaminen tälle luvulle tarkoittaisi, ettei formaattia ole ymmärretty, ja juuri se väärinkäsitys on yleisin skill-kansioista. Kaikki alla on Markdownia ja YAMLia sekä yksi pieni shell-skripti, jonka tarkoitus on nimenomaan näyttää, minne koodi kuuluu skillin sisällä ja minne ei.

Tässä on todellinen ohje: miten yksi yritys kirjoittaa julkaisutiedotteensa. Se on menettely, ei mieltymys — siinä on järjestetty askeljoukko, taksonomia, ääni, malli ja skripti, joka kerää raaka-aineen.

Laita se kaikki system promptiin, kuten useimmat tiimit tekevät, ja luvun 16 aritmetiikka ottaa vallan. System prompt on etuliite, ja etuliitteestä maksetaan jokaisessa kutsussa. Mitattuna o200k_base-työkalulla tätä lukua varten kirjoitetusta kansiosta:

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

Kaksikymmentäneljä kertaa halvempi, kun sitä käytetään, kolmekymmentäseitsemän kertaa halvempi, kun sitä ei käytetä. Hinnat ovat luvusta 16: $2,00 miljoonalta input-tokenilta.

Nyt rehellinen vastaväite, koska luku, joka ohittaisi sen, olisi mainontaa. Prompt caching sulkee rahallisen kuilun enimmäkseen. System prompt on vakaa ja se on ensimmäisenä, mikä tekee siitä parhaan mahdollisen cache-ehdokkaan; hinnalla $0,20 miljoonalta cachetulta input-tokenilta samat 68 640 tokenia maksavat $0,0168 eivätkä $0,1373. Yhä kolme kertaa skillin verran, mutta ei enää eri suuruusluokkaa.

Raha ei koskaan ollut vahvin argumentti. Tämä on:

Caching tekee pysyvästä etuliitteestä halvemman. Se ei tee siitä pienempää.

Vuorolla 40 system-prompt-versiossa on yhä 1 716 tokenia julkaisutiedotepolitiikkaa ikkunassa keskustelussa, joka koskee aivan muuta, kilpailemassa siitä, mitä luku 24 kutsui mallin attention-budjetiksi. Skill-versiossa niitä on 46. Cachea väärä asia, ja olet ostanut alennuksen häiriötekijästä.

Kaavana kirjoitettuna, kun $n$ on vuorojen määrä, $L_1$ metadata, $L_2$ body, $L_3$ koko nippu ja $R$ tosiasiassa luettujen niputettujen tiedostojen joukko:

Koko tämä luku on ero sen välillä, kerrotaanko toinen termi luvulla $n$ vai luvulla yksi tai nolla.

Skill on hakemisto. Spesifikaatio on tarpeeksi lyhyt esitettäväksi kokonaan:

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 täytyy alkaa YAML-frontmatterilla, ja täsmälleen kaksi kenttää vaaditaan: name ja description.¹ Neljä muuta ovat valinnaisia, eikä muita ole määritelty:

Tässä on julkaisutiedote-skill kokonaisuudessaan, alle kolmenkymmenen rivin bodylla:

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

Lue, mitä tuo body on. Se ei ole politiikka — se on sisällysluettelo ja toimintajärjestys. Politiikka elää kolmessa tiedostossa, jotka se nimeää mutta joita se ei sisällytä. Ja ensimmäinen askel antaa työn skriptille, koska skriptin koodi ei koskaan päädy context window -ikkunaan: vain sen output päätyy.²

Latausmallilla on nimi ja kolme vaihetta. Spesifikaatio esittää ne token-budjetin kanssa:¹

1. Metadata, noin 100 tokenia: name ja description, ladattu käynnistyksessä jokaiselle asennetulle skillille.
2. Ohjeet, suositus alle 5 000 tokenia: SKILL.md-body, ladattu kun skill aktivoidaan.
3. Resurssit, tarpeen mukaan: niputetut tiedostot, ladattu vain kun jokin vaatii niitä.

Referenssidokumentaatio lisää samaan taulukkoon neljännen sarakkeen — milloin ladataan, token-hinta, sisältö — ja tärkeä rivi on kolmas: ei mitään ennen käyttöä.³ Siellä on myös lause, joka tiivistää koko luvun:

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

Tämän luvun alussa oleva mitattu taulukko on tuo väite tarkistettuna viidellä skillillä, joita kukaan ei kirjoittanut tätä artikkelia varten. Kahta riviä kannattaa lukea rinnakkain.

next-best-practices sisältää 966-tokenin bodyn, joka linkittää 19 tiedostoon, joissa on 19 374 tokenia. Pyydä sitä korjaamaan hydration error, ja agent lukee bodyn sekä hydration-error.md: 1 409 tokenia 20 340:stä, neljäntoista kertoimen, eikä muita kahdeksaatoista tiedostoa koskaan avata.

next-cache-components sisältää 2 334-tokenin bodyn eikä lainkaan niputettuja tiedostoja. Se on validi skill ja hyvin kirjoitettu sellainen, eikä sillä ole tasoa 3 paljastettavaksi. Se on tekniikan rehellinen raja: progressive disclosure säästää vain, jos jotain voidaan siirtää myöhemmäksi. Skill, jonka tieto ei hajoa osiin, maksaa koko bodynsä aktivoinnissa, ja jäljellä oleva ainoa vipu on olla aktivoimatta sitä.

Taso 1 on yhdestä lauseesta tehty routing-päätös. Mikään muu skillissä ei vaikuta siihen, avataanko sitä koskaan — ei bodyn laatu, eivät esimerkit, eivät skriptit. Kuvaus ei siis ole dokumentaatiota. Se on query surface, ja se voi olla väärä.

Spesifikaatio sanoo tämän hyvän ja huonon esimerkin muodossa, ja huono esimerkki on neljä sanaa: description: Helps with PDFs.¹ Se kannattaa mitata eikä vain hyväksyä.

Kuusi skill-kansiota, jokaisella uskottava kuvaus, joka sanoo mitä se tekee ja milloin sitä käytetään. Kaksikymmentäneljä pyyntöä, neljä per skill, muotoiltuna kuten ihminen ne muotoilisi ja ilman skillin nimeämistä. Malli näkee kuusi riviä system promptissaan ja sen täytyy vastata yhdellä nimellä tai NONE. Greedy decoding, jotta se toistuu. Sitten samat 24 pyyntöä samoilla kuudella skillillä, mutta kuvaukset leikattuna pelkkään aiheeseen.

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

Lue ensin intervallit, kuten luku 4 vaati ja luku 29 vaatii uudelleen: ne menevät päällekkäin, eivätkä 24 tapausta voi järjestää kahta järjestelmää pelkkien aggregaattien perusteella. Parittainen vertailu ratkaisee asian, ja se on luvun 15 instrumentti: niistä kymmenestä tapauksesta, joissa kaksi haaraa olivat eri mieltä, yhdeksän meni rikkaille kuvauksille ja yksi ohuille. Se on todettu tavallisella kynnyksellä.

Lue nyt viimeinen rivi, joka on varsinainen löydös. Ohuilla kuvauksilla malli vastasi NONE yhdeksään kahdestakymmenestäneljästä pyynnöstä. Ei väärä skill: ei mitään skill-kansiota. Tässä niistä neljä sanatarkasti:

"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

Täydellinen sql-review-skill oli asennettuna, bodylla, esimerkeillä ja checklistillä, eikä sitä avattu koskaan, kolme kertaa peräkkäin, niihin kolmeen kysymykseen, joita varten se oli kirjoitettu. Tasot 2 ja 3 ovat merkityksettömiä skillille, johon taso 1 ei koskaan yllä.

Korjauksen hinta: 214 tokenia, ero 295:n ja 81:n välillä, jaettuna kuudelle skillille. Tämä on luvun 18 löydös toisesta suunnasta. Siellä pelkän toolin kuvauksen muuttaminen vei päivämäärämuotoilun tuloksesta 2 oikein 24:stä tulokseen 24 oikein 24:stä. Tässä pelkän skillin kuvauksen muuttaminen vie aktivoinnin 10:stä 24:stä 18:aan. Molemmissa tapauksissa järjestelmän halvin korjaus on lause, ja molemmissa tapauksissa lauseen täytyy nimetä trigger eikä vain aihe: ei mikä asia on, vaan mitä käyttäjä on juuri sanonut, kun se soveltuu.

Yksi varaus, jonka tämä luku on velkaa omille standardeilleen. Tämä on puolen miljardin parametrin malli, ja frontier model routtaa paljon paremmin kuin 75 %. Lue mekanismi, älä suuruusluokkaa: routing-signaali on yhden lauseen mittainen riippumatta siitä, mikä malli sitä lukee, eikä mikään malli voi valita tiedon perusteella, jota et laittanut siihen lauseeseen.

Toinen epäonnistuminen on ensimmäisen vastakohta. Skill löytyy, tasot on jaettu oikein, ja agent lukee silti kaiken.

vercel-react-best-practices on aidosti hyvin rakennettu skill. Sen 1 670-tokenin body on prioriteettitaulukko kahdeksasta kategoriasta ja pikaviite, joka nimeää 70 sääntötiedostoa, yhden rivin kutakin kohti. Säännöt ovat levyllä sen vieressä: 70 tiedostoa, pienin 132 tokenia, mediaani 319, suurin 1 052. Kysy yksi kysymys barrel importeista, ja rehellinen hinta on body plus yksi tiedosto — alle 2 400 tokenia 53 670:n nipusta.

Sitten bodyn viimeinen rivi sanoo tämän:

## Full Compiled Document

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

AGENTS.md on 26 362 tokenia. Se on 70 sääntötiedostoa ketjutettuna yhteen: niiden summa on 25 784, ja erotus on niiden väliset otsikot. Skill siis tarjoaa agentille valinnan yhden mediaanisäännön lukemisen hintaan 319 tokenia ja saman sisällön, kokonaan, lukemisen välillä kahdeksankymmentäkolminkertaiseen hintaan — ja tarjoaa valinnan lauseessa, jossa ei ole hintaa eikä ehtoa sille, milloin se kannattaa tehdä.

Se ei ole bugi eikä tiedosto ole väärin; koottu dokumentti on aidosti hyödyllinen ihmiselle ja agentille, jota on pyydetty auditoimaan kokonainen codebase. Se on tason 3 tiedosto tason 2 kutsulla, ja oppi yleistyy tämän yhden skillin ohi: jokaisen polun ulos tiedostosta SKILL.md pitäisi sanoa, mitä se maksaa ja milloin se on hintansa arvoinen, koska mallilla ei ole tapaa tietää, että tiedostonimi on kahdeksankymmentäkolme kertaa kalliimpi kuin sen yläpuolella oleva tiedostonimi.

Samassa kansiossa on pienempi oppi vanhenemisesta. Body sanoo ”70 sääntöä 8 kategoriassa” ja listaa 70; rules/-hakemisto sisältää 72 tiedostoa, joista kaksi ovat scaffoldingia (_template.md ja _sections.md); ja sidecar metadata.json sanoo ”40+ rules”. Kolme laskuria samasta joukosta yhdessä kansiossa, yksi oikein, yksi aritmeettinen ja yksi jäänyt aiemmasta versiosta. Skill on dokumentti, ja dokumentit lahoavat täsmälleen kuten koodikommentti, joka on ajelehtinut erilleen vieressään olevasta koodista — sillä erolla, että tätä lukee kone, joka ei kohota kulmakarvaa.

Avoin spesifikaatio määrittelee kuusi frontmatter-kenttää. Referenssitoteutus, Claude Code, hyväksyy kaksikymmentä.² Viisi ryhmää kannattaa tuntea nimeltä, koska niissä formaatti lakkaa olemasta pelkkä dokumentti:

Argumentit (arguments, argument-hint) antavat ihmisen välittää arvoja, jotka korvataan bodyyn, mikä tekee skillistä käyttökelpoisen slash-komentona. Rajaus (paths) rajoittaa aktivoinnin tiedostoihin, jotka vastaavat globia. Ja dynamic context injection on se, joka muuttaa ajattelumallia: muotoa !`git diff HEAD` oleva rivi ajetaan ennen kuin body lähetetään, ja sen output korvataan tekstiin. Dokumentti on template, ja osa siitä lasketaan lukuhetkellä.

Nyt ansa, ja se sanotaan samassa dokumentaatiossa: Claude Coden ulkopuolella — web-tuotteessa, Skills API:n kautta, paketoinnissa — vain kuusi määriteltyä kenttää sallitaan, ja mikä tahansa muu kenttä on kova virhe uploadissa.² Skill, joka toimii täydellisesti yhdessä tuotteessa, ei siis asennu toiseen saman toimittajan tuotteeseen, ja se epäonnistuu frontmatterissa eikä missään sellaisessa, minkä voisit testata lukemalla proosan. Jos haluat skillin olevan portable, kuusi kenttää on koko budjetti. Jos et halua, sano se kentässä compatibility, joka on olemassa juuri tätä varten.

Neljä asiaa sekoitetaan jatkuvasti toisiinsa, eikä sekaannus ole sanastollista pilkunviilausta: väärä valinta maksaa rahaa jokaisella vuorolla tai vie sinulta takuun, jonka luulit sinulla olevan.

Kaksi lihavoitua riviä ovat koko ero. Skill luetaan; tool kutsutaan. Skill on proosaa, joka saapuu context window -ikkunaan ja kilpailee attentionista kaiken muun siellä olevan kanssa; malli voi noudattaa sitä, lukea sen väärin tai ohittaa sen, eikä mikään järjestelmässä huomaa. Tool on kutsu, joka poistuu kokonaan mallin käsistä: koodisi vastaanottaa argumentit, validoi ne, tarkistaa oikeudet ja päättää. Luku 18 muotoili sen niin, että malli ehdottaa ja koodisi määrää, ja juuri tätä jakoa skillillä ei ole.

Siis kuusi todellista tapausta ratkaistuna:

Historia on lyhyt, poikkeuksellisen hyvin päivätty, ja se on osa, jota lähes kukaan ei kerro.

Agent Skills julkaistiin 16. lokakuuta 2025 yhden toimittajan ominaisuutena, määriteltynä tuossa ilmoituksessa ”järjestetyiksi kansioiksi ohjeita, skriptejä ja resursseja, joita agentit voivat löytää ja ladata dynaamisesti suoriutuakseen paremmin tietyistä tehtävistä”, kolmen tason kanssa kuvattuna säilyttämisen arvoisella analogialla: ”kuin hyvin järjestetty käsikirja, joka alkaa sisällysluettelolla, jatkuu tarkkoihin lukuihin ja päättyy yksityiskohtaiseen liitteeseen”.⁴

18. joulukuuta 2025 sama sivu päivitettiin ilmoittamaan formaatti avoimena standardina, omalla spesifikaatiolla osoitteessa agentskills.io, kontribuutioille avoimella hallinnolla ja referenssivalidaattorilla.³ Luettuna 7. syyskuuta 2026 standardin client showcase listaa neljäkymmentäkuusi tuotetta — editoreita, terminaaleja, pilvialustoja ja mobiiliruntimeja, mukaan lukien Anthropicilta, OpenAI:lta, Googlelta ja Mistralilta tulevat first-party coding agents — joista jokainen linkittää omaan setup-dokumentaatioonsa.¹

Yhtyminen MCP:n kanssa tehdään avoimesti, numeroilla jotka voi tarkistaa:

Kiinnostava osa on sulkeminen, ei ehdotukset. SEP-2076 pyysi neljättä primitiveä tools, resources ja prompts rinnalle. Siitä muodostunut työryhmä päätti, että vastaus oli ei: skills kulkevat jo olemassa olevan resources-primitiven päällä opt-in extensionina.⁵ Luku 26 mittasi saman vaiston protokollan omassa changelogissa, jossa sampling, roots ja logging poistettiin käytöstä eikä pidetty mukana. Standardointielin, joka poistaa itse kirjoittamansa ehdotuksen, käyttäytyy hyvin, ja syy kertoa tämä tarina numeroiden kanssa on se, että muualla lukemasi tiivistelmät kuvaavat skills yhä MCP-primitiveinä.

Nyt osaat kirjoittaa tiedoston SKILL.md, jakaa sen kolmeen tasoon, jotka maksavat itse itsensä, lukea jonkun toisen skillin frontmatterin ja tietää, mitkä kentät eivät selviä uploadista muualle, sekä vastata kysymykseen, jonka ympärille koko luku rakennettiin — system prompt, skill, tool vai server — syyllä eikä tottumuksella.

Et kuitenkaan osaa sanoa, toimiiko omasi.

Jokainen tämän luvun olennainen väite oli mittaus, ja tärkein niistä oli tarkkuus: 18 24:stä vastaan 10 24:stä, intervalli kummallakin ja paritettu testi niiden välillä, koska kaksi päällekkäistä aggregaattia ei päätä mitään. Tuo instrumentti lainattiin. Skillin kuvaus on routing key, sen body on menettely, jota malli voi tai ei voi seurata, ja molemmat ominaisuudet selviävät vain ajamalla asia monta kertaa ja pisteyttämällä, mitä tuli takaisin — mikä tarkoittaa golden setiä, graderia jonka kirjoitit ennen ajoa, ja metriikkaa, joka kysyy toimiko se joka kerta eikä ainakin kerran.

Luku 29 on se, ja se alkaa luvulla, josta tämän luvun menetelmä riippuu: agent, joka onnistuu seitsemän kertaa kymmenestä, näyttää 70-prosenttiselta, ja sen pass^10 — todennäköisyys onnistua kaikissa kymmenessä — on nolla. Se myös mittaa kolme graderia samoilla kahdellasadalla transcriptillä ja saa 0 %, 13 % ja 26 % generoimatta yhtään uutta tokenia. Ennen kuin luotat lauseeseen, jonka juuri kirjoitit tiedostoon description, tarvitset instrumentin, joka voi kertoa sen olevan huonompi kuin lause, jonka korvasit.

Jokainen tämän luvun token-määrä tuotettiin paikallisesti versiolla tiktoken 0.14.0 ja o200k_base-encodingilla 7. syyskuuta 2026: tämän luvun alussa listatuista viidestä kolmannen osapuolen skillistä sekä tätä lukua varten kirjoitetusta release-notes-skillistä, jonka koko teksti toistetaan osittain yllä. Taso 1 mitataan yhtenä rivinä - name: description, jonka host renderöi system promptiin; taso 2 on SKILL.md-body frontmatterin jälkeen; taso 3 on jokainen muu tiedosto kansiossa. Kustannuksissa käytetään luvun 16 mitattuja hintoja mallille gpt-5.6-terra, $2,00 miljoonalta input-tokenilta ja $0,20 miljoonalta cachetulta input-tokenilta, sovellettuna näihin lukuihin — ne ovat aritmetiikkaa mitatuilla tokeneilla, eivät havaintoja live-laskusta. Tämän luvun kirjoittamiseen ei kutsuttu maksullista API:a.

Aktivointikoe ajoi Qwen/Qwen2.5-0.5B-Instruct puolikkaalla tarkkuudella yhdellä kuluttaja-GPU:lla, greedy decodingilla, 24 pyyntöä kuuden skillin yli, kahdesti — kerran kuvauksilla, jotka sanovat mitä skill tekee ja milloin se soveltuu, kerran kuvauksilla, jotka leikattiin paljaaseen aiheeseen spesifikaation oman ”huonon esimerkin” tyyliin. Intervallit ovat Wilson 95 %:ssa; parittainen vertailu on kaksisuuntainen exact sign test kymmenen erimielisen tapauksen yli; Wilson-intervalli on luvusta 4 ja exact paired sign test luvusta 15, molemmat uudelleenkäytettynä muuttamatta. Lue suuruudet hyvin pienen mallin ominaisuutena ja menetelmä siirrettävänä.

Tässä mitatut viisi skill-kansiota ovat kolmannen osapuolen paketteja, eivät tätä lukua varten kirjoitettuja: next-best-practices ja next-cache-components kohteesta vercel-labs/next-skills sekä vercel-composition-patterns, vercel-react-best-practices ja vercel-react-native-skills kohteesta vercel-labs/agent-skills. Niiden sisäiset luvut — 70 sääntötiedostoa, AGENTS.md 26 362 tokenia, tammikuulle 2026 päivätty metadata.json, joka väittää ”40+ rules” — luettiin levyllä olevista tiedostoista 7. syyskuuta 2026 ja ovat kyseisen julkaistun version ominaisuuksia, eivät kritiikkiä sen kirjoittajista: jokainen niistä on sellaista driftia, jota ilmestyy mihin tahansa dokumentaatiopuuhun, jota muokataan useammin kuin lasketaan.