Agent Skills și SKILL.md: divulgare progresivă, măsurată

Capitolul 14 a stabilit regula pentru a doua jumătate a acestui curs — conexiunile, retry-urile și anularea sunt TypeScript — și a declarat cinci excepții. Aceasta este una dintre ele, iar motivul nu este o preferință.

Un skill este un fișier Markdown. Nu un fișier care configurează un program, nu un fișier pe care îl compilează un program: un document pe care modelul îl citește, la fel cum citește mesajul pe care l-ai tastat. A da acestui capitol un limbaj de programare ar însemna să nu fi înțeles formatul, iar această neînțelegere este cea mai comună despre skills. Tot ce urmează este Markdown și YAML, plus un mic script shell care există tocmai ca să arate unde își are locul codul într-un skill și unde nu.

Iată o instrucțiune reală: cum își scrie o companie notele de lansare. Este o procedură, nu o preferință — are un set ordonat de pași, o taxonomie, o voce, un șablon și un script care colectează materia primă.

Pune totul în system prompt, așa cum fac majoritatea echipelor, și aritmetica din Capitolul 16 preia controlul. Un system prompt este un prefix, iar un prefix este plătit la fiecare call. Măsurat cu o200k_base peste folderul scris pentru acest capitol:

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

De douăzeci și patru de ori mai ieftin când este folosit, de treizeci și șapte de ori mai ieftin când nu este. Tarifele sunt cele din Capitolul 16: $2.00 per milion de token de input.

Acum obiecția onestă, pentru că un capitol care ar sări peste ea ar fi reclamă. Prompt caching închide în mare parte diferența de bani. Un system prompt este stabil și stă primul, ceea ce îl face cel mai bun candidat pentru cache; la $0.20 per milion pentru input în cache, aceiași 68.640 token costă $0.0168 în loc de $0.1373. Încă de trei ori mai mult decât skill-ul, dar nu mai este un ordin de mărime diferit.

Banii nu au fost niciodată cel mai puternic argument. Acesta este:

Caching face mai ieftin un prefix permanent. Nu îl face mai mic.

La tura 40, versiunea cu system prompt încă are 1.716 token de politică pentru note de lansare în window în timpul unei conversații despre cu totul altceva, concurând pentru ceea ce Capitolul 24 a numit bugetul de attention al modelului. Versiunea cu skill are 46. Pune în cache lucrul greșit și ai cumpărat o reducere pentru o distragere.

Scris ca formulă, cu $n$ ture, $L_1$ metadata, $L_2$ corpul, $L_3$ întregul pachet și $R$ setul de fișiere incluse citite efectiv:

Întregul capitol este diferența dintre a înmulți al doilea termen cu $n$ și a-l înmulți cu unu sau cu zero.

Un skill este un director. Specificația este suficient de scurtă încât să fie redată complet:

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 trebuie să înceapă cu YAML frontmatter, iar exact două câmpuri sunt obligatorii: name și description.¹ Alte patru sunt opționale și nu sunt definite altele:

Iată skill-ul pentru release notes, complet, cu corpul sub treizeci de 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.

Citește ce este acel corp. Nu este politica — este un cuprins cu o ordine a operațiilor. Politica trăiește în trei fișiere pe care le numește și nu le include. Iar pasul unu predă munca unui script, pentru că codul unui script nu intră niciodată în context window: doar output-ul lui intră.²

Modelul de încărcare are un nume și trei etape. Specificația le enunță cu un buget de token atașat:¹

1. Metadata, aproximativ 100 token: name și description, încărcate la pornire pentru fiecare skill instalat.
2. Instrucțiuni, recomandate sub 5.000 token: corpul SKILL.md, încărcat când skill-ul este activat.
3. Resurse, după nevoie: fișiere incluse, încărcate doar când ceva le cere.

Documentația de referință pune o a patra coloană în același tabel — când este încărcat, cost în token, conținut — iar rândul care contează este al treilea: nimic până la accesare.³ Propoziția care rezumă întregul capitol este și ea acolo:

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

Tabelul măsurat de la începutul acestui capitol este acea afirmație verificată pe cinci skills pe care nimeni nu le-a scris pentru acest articol. Două rânduri merită citite unul lângă altul.

next-best-practices are un corp de 966 token care trimite la nouăsprezece fișiere ce conțin 19.374 token. Cere-i să repare o eroare de hydration și agent citește corpul plus hydration-error.md: 1.409 token din 20.340, un factor de paisprezece, iar celelalte optsprezece fișiere nu sunt deschise niciodată.

next-cache-components are un corp de 2.334 token și niciun fișier inclus deloc. Este un skill valid și bine scris, iar el nu are nivelul 3 de divulgat. Aceasta este limita onestă a tehnicii: divulgarea progresivă economisește doar dacă există ceva de amânat. Un skill a cărui cunoaștere nu se descompune își plătește întregul corp la activare, iar singura pârghie rămasă este să nu îl activezi.

Nivelul 1 este o decizie de rutare luată dintr-o singură propoziție. Nimic altceva despre un skill nu influențează dacă va fi vreodată deschis — nici calitatea corpului, nici exemplele, nici scripturile. Deci descrierea nu este documentație. Este suprafața de interogare, și poate fi greșită.

Specificația spune asta sub forma unui exemplu bun și a unuia prost, iar cel prost are patru cuvinte: description: Helps with PDFs.¹ Merită măsurat, nu doar acceptat.

Șase skills, fiecare cu o descriere plauzibilă care spune ce face și când se folosește. Douăzeci și patru de cereri, patru per skill, formulate așa cum le-ar formula o persoană și fără a numi vreodată skill-ul. Modelul vede cele șase linii în system prompt și trebuie să răspundă cu un nume sau cu NONE. Greedy decoding, deci reproduce. Apoi aceleași douăzeci și patru de cereri cu aceleași șase skills, iar descrierile tăiate până la subiectul lor nud.

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

Citește mai întâi intervalele, așa cum a insistat Capitolul 4 și cum va insista din nou Capitolul 29: ele se suprapun, iar douăzeci și patru de cazuri nu pot ierarhiza două sisteme doar pe agregatele lor. Comparația pereche este cea care decide, iar instrumentul este cel din Capitolul 15: dintre cele zece cazuri în care cele două brațe au fost în dezacord, nouă au mers la descrierile bogate și unul la cele subțiri. Asta este stabilit la pragul obișnuit.

Acum citește ultima linie, care este constatarea propriu-zisă. Cu descrieri subțiri, modelul a răspuns NONE la nouă din douăzeci și patru de cereri. Nu skill-ul greșit: niciun skill. Iată patru dintre ele, verbatim:

"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

Un skill sql-review perfect era instalat, cu corp și exemple și checklist, și nu a fost deschis niciodată, de trei ori la rând, la cele trei întrebări pentru care fusese scris. Nivelurile 2 și 3 sunt irelevante pentru un skill la care nivelul 1 nu ajunge niciodată.

Costul remedierii: 214 token, diferența dintre 295 și 81, împărțită peste șase skills. Este constatarea din Capitolul 18 venind din cealaltă parte. Acolo, schimbarea doar a descrierii unui tool a dus formatarea datelor de la 2 corecte din 24 la 24 din 24. Aici, schimbarea doar a descrierii unui skill duce activarea de la 10 din 24 la 18. În ambele cazuri, cea mai ieftină remediere din sistem este o propoziție, iar în ambele cazuri propoziția trebuie să numească trigger-ul, nu doar subiectul: nu ce este lucrul, ci ce tocmai va fi spus utilizatorul când se aplică.

O rezervă pe care acest capitol o datorează propriilor standarde. Acesta este un model de o jumătate de miliard de parametri, iar un model de frontieră rutează mult mai bine decât 75 %. Citește mecanismul, nu magnitudinea: semnalul de rutare are o singură propoziție indiferent ce model îl citește, iar niciun model nu poate selecta pe baza informației pe care nu ai pus-o în acea propoziție.

Al doilea eșec este opusul primului. Skill-ul este găsit, nivelurile sunt împărțite corect, iar agent citește totul oricum.

vercel-react-best-practices este un skill cu adevărat bine construit. Corpul lui de 1.670 token este un tabel de priorități cu opt categorii și o referință rapidă care numește 70 de fișiere de reguli, câte o linie fiecare. Regulile sunt pe disc lângă el: 70 de fișiere, cel mai mic 132 token, mediana 319, cel mai mare 1.052. Pune-i o întrebare despre barrel imports și costul onest este corpul plus un fișier — sub 2.400 token față de un pachet de 53.670.

Apoi ultima linie a corpului spune asta:

## Full Compiled Document

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

AGENTS.md are 26.362 token. Este concatenarea celor 70 de fișiere de reguli: suma lor este 25.784, iar diferența sunt heading-urile dintre ele. Deci skill-ul îi oferă agent-ului o alegere între a citi o regulă mediană la 319 token și a citi același conținut, tot, la un preț de optzeci și trei de ori mai mare — și oferă acea alegere într-o propoziție fără cost atașat și fără condiție despre când merită luată.

Asta nu este un bug și fișierul nu este greșit; un document compilat este cu adevărat util pentru un om și pentru un agent căruia i s-a cerut să auditeze un întreg codebase. Este un fișier de nivel 3 cu o invitație de nivel 2, iar lecția se generalizează dincolo de acest skill: fiecare cale care iese dintr-un SKILL.md ar trebui să spună cât costă și când merită, pentru că modelul nu are cum să știe că un nume de fișier este de optzeci și trei de ori mai scump decât numele de fișier de deasupra lui.

Același folder poartă o lecție mai mică despre învechire. Corpul spune „70 de reguli în 8 categorii” și listează 70; directorul rules/ conține 72 de fișiere, dintre care două sunt schele (_template.md și _sections.md); iar sidecar-ul metadata.json spune „40+ reguli”. Trei numărări ale aceluiași set într-un folder, una corectă, una aritmetică și una rămasă dintr-o versiune anterioară. Un skill este un document, iar documentele putrezesc exact ca un comentariu de cod care a deviat de la codul de lângă el — cu diferența că acesta este citit de o mașină care nu va ridica din sprânceană.

Specificația deschisă definește șase câmpuri frontmatter. Implementarea de referință, Claude Code, acceptă douăzeci.² Cinci grupuri merită cunoscute pe nume, pentru că ele sunt locul unde formatul încetează să mai fie doar un document:

Argumentele (arguments, argument-hint) permit unei persoane să trimită valori care sunt substituite în corp, ceea ce face ca un skill să fie utilizabil ca slash command. Scoping (paths) limitează activarea la fișiere care se potrivesc unui glob. Iar dynamic context injection este cel care schimbă modelul mental: o linie de forma !`git diff HEAD` rulează înainte ca body-ul să fie trimis, iar output-ul ei este substituit în text. Documentul este un șablon, iar o parte din el este calculată la momentul citirii.

Acum capcana, iar ea este enunțată în aceeași documentație: în afara Claude Code — în produsul web, prin Skills API, în packaging — sunt permise doar cele șase câmpuri specificate, iar orice alt câmp este o eroare dură la upload.² Deci un skill care funcționează perfect într-un produs eșuează la instalare într-un altul aparținând aceluiași vendor și eșuează în frontmatter, nu în ceva ce ai putea testa citind proza. Dacă intenționezi ca un skill să fie portabil, cele șase câmpuri sunt întregul buget. Dacă nu, spune asta în compatibility, care există exact pentru acest lucru.

Patru lucruri sunt confundate constant între ele, iar confuzia nu este pedanterie de vocabular: alegerea greșită costă bani la fiecare tură sau te costă o garanție pe care credeai că o ai.

Cele două rânduri cu bold sunt întreaga distincție. Un skill este citit; un tool este invocat. Un skill este proză care ajunge în context window și concurează pentru attention cu tot ce mai este acolo; modelul îl poate urma, îl poate citi greșit sau îl poate ignora, iar nimic din sistem nu observă. Un tool este un call care iese complet din mâinile modelului: codul tău primește argumente, le validează, verifică permisiuni și decide. Capitolul 18 a formulat-o ca modelul propune și codul tău dispune, iar acea împărțire este exact ceea ce un skill nu are.

Deci șase cazuri reale, rezolvate:

Istoria este scurtă, neobișnuit de bine datată, și este partea pe care aproape nimeni nu o spune.

Agent Skills au fost publicate pe 16 octombrie 2025 ca funcționalitate a unui vendor, definite în acel anunț ca „organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks”, cu cele trei niveluri descrise printr-o analogie care merită păstrată: „like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix”.⁴

Pe 18 decembrie 2025, aceeași pagină a fost actualizată pentru a anunța formatul ca standard deschis, cu o specificație proprie la agentskills.io, guvernanță deschisă contribuțiilor și un validator de referință.³ Citit pe 7 septembrie 2026, showcase-ul de clienți al standardului listează patruzeci și șase de produse — editoare, terminale, platforme cloud și runtime-uri mobile, inclusiv agenții de codare first-party de la Anthropic, OpenAI, Google și Mistral — fiecare cu link către propria documentație de configurare.¹

Convergența cu MCP se face la vedere, cu cifre pe care le poți verifica:

Partea interesantă este închiderea, nu propunerile. SEP-2076 cerea o a patra primitivă lângă tools, resources și prompts. Working group-ul format din ea a decis că răspunsul era nu: skills merg pe primitiva resources care există deja, ca extensie opt-in.⁵ Capitolul 26 a măsurat același instinct în propriul changelog al protocolului, unde sampling, roots și logging au fost depreciate în loc să fie păstrate. Un organism de standardizare care elimină o propunere pe care a inițiat-o se comportă bine, iar motivul pentru care spunem această poveste cu cifrele în față este că rezumatele pe care le vei citi în altă parte încă descriu skills ca pe o primitivă MCP.

Acum poți scrie un SKILL.md, îl poți împărți în trei niveluri care își plătesc costul, poți citi frontmatter-ul skill-ului altcuiva și poți ști ce câmpuri nu vor supraviețui când sunt uploadate în altă parte, și poți răspunde la întrebarea în jurul căreia a fost construit întregul capitol — system prompt, skill, tool sau server — cu un motiv, nu din obișnuință.

Ce nu poți face este să spui dacă al tău funcționează.

Fiecare afirmație din acest capitol care a contat a fost o măsurare, iar cea care a contat cel mai mult a fost o acuratețe: 18 din 24 față de 10 din 24, cu un interval pe fiecare și un test pereche între ele, pentru că două agregate care se suprapun nu decid nimic. Instrumentul acela a fost împrumutat. Descrierea unui skill este o cheie de rutare, corpul lui este o procedură pe care modelul poate sau nu să o urmeze, iar ambele sunt proprietăți pe care le poți afla doar rulând lucrul de multe ori și notând ce a revenit — ceea ce înseamnă un set de aur, un evaluator scris înainte de run și metrica ce întreabă dacă a funcționat de fiecare dată, nu măcar o dată.

Capitolul 29 este asta și deschide cu numărul de care depinde metoda acestui capitol: un agent care reușește de șapte ori din zece arată ca 70 %, iar pass^10 al lui — șansa să reușească în toate cele zece — este zero. Măsoară și trei evaluatori pe aceleași două sute de transcripturi și obține 0 %, 13 % și 26 % fără să regenereze niciun token. Înainte să ai încredere în propoziția pe care tocmai ai scris-o într-un description, ai nevoie de instrumentul care îți poate spune că este mai proastă decât cea pe care ai înlocuit-o.

Fiecare număr de token din acest capitol a fost produs local cu tiktoken 0.14.0 și encoding-ul o200k_base, pe 7 septembrie 2026: peste cele cinci skills third-party listate la începutul acestui capitol și peste skill-ul release-notes scris pentru acest capitol, al cărui text complet este reprodus parțial mai sus. Nivelul 1 este măsurat ca linia unică - name: description pe care un host o randă în system prompt; nivelul 2 este corpul SKILL.md după frontmatter; nivelul 3 este orice alt fișier din folder. Costurile folosesc tarifele măsurate în Capitolul 16 pentru gpt-5.6-terra, $2.00 per milion de token de input și $0.20 per milion de token de input în cache, aplicate acelor numărători — sunt aritmetică pe token măsurați, nu observații ale unei facturi live. Nu a fost apelat niciun API plătit pentru a scrie acest capitol.

Experimentul de activare a rulat Qwen/Qwen2.5-0.5B-Instruct în half precision pe un GPU de consum, greedy decoding, 24 de cereri peste șase skills, de două ori — o dată cu descrieri care afirmă ce face skill-ul și când se aplică, o dată cu descrierile tăiate la un subiect nud în stilul propriului „poor example” al specificației. Intervalele sunt Wilson la 95 %; comparația pereche este un test exact al semnului, bilateral, peste cele zece cazuri discordante; intervalul Wilson este cel din Capitolul 4, iar testul exact pereche al semnului este cel din Capitolul 15, ambele reutilizate neschimbat. Citește magnitudinile ca proprietate a unui model foarte mic și metoda ca transferabilă.

Cele cinci skills măsurate aici sunt pachete third-party, nu scrise pentru acest capitol: next-best-practices și next-cache-components din vercel-labs/next-skills, și vercel-composition-patterns, vercel-react-best-practices și vercel-react-native-skills din vercel-labs/agent-skills. Numărătorile lor interne — 70 de fișiere de reguli, AGENTS.md la 26.362 token, metadata.json datat ianuarie 2026 și pretinzând „40+ rules” — au fost citite din fișierele de pe disc pe 7 septembrie 2026 și sunt proprietăți ale acelei versiuni publicate, nu critici la adresa autorilor lor: fiecare dintre ele este tipul de drift care apare în orice arbore de documentație editat mai des decât este numărat.