Agent Skills i SKILL.md: divulgació progressiva, mesurada

El Capítol 14 va establir la regla per a la segona meitat d’aquest curs — connexions, reintents i cancel·lació són TypeScript — i va declarar cinc excepcions. Aquesta n’és una, i el motiu no és una preferència.

Un skill és un fitxer Markdown. No un fitxer que configura un programa, no un fitxer que un programa compila: un document que el model llegeix, de la mateixa manera que llegeix el missatge que has escrit. Donar a aquest capítol un llenguatge de programació voldria dir no haver entès el format, i aquest malentès és el més habitual sobre els skills. Tot el que ve a continuació és Markdown i YAML, més un petit script de shell que existeix precisament per mostrar on pertany el codi dins d’un skill i on no.

Aquí tens una instrucció real: com una empresa escriu les seves notes de versió. És un procediment, no una preferència: té un conjunt ordenat de passos, una taxonomia, una veu, una plantilla i un script que recull la matèria primera.

Posa-ho tot al system prompt, com fan la majoria d’equips, i l’aritmètica del Capítol 16 s’imposa. Un system prompt és un prefix, i un prefix es paga en cada crida. Mesurat amb o200k_base sobre la carpeta escrita per a aquest capítol:

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

Vint-i-quatre vegades més barat quan s’utilitza, trenta-set vegades més barat quan no s’utilitza. Les tarifes són les del Capítol 16: $2.00 per milió de tokens d’entrada.

Ara l’objecció honesta, perquè un capítol que se la saltés seria publicitat. El prompt caching gairebé tanca la bretxa de diners. Un system prompt és estable i va al principi, cosa que el converteix en el millor candidat possible per a la cache; a $0.20 per milió d’entrada en cache, els mateixos 68.640 tokens costen $0.0168 en lloc de $0.1373. Encara és tres vegades el skill, però ja no és un altre ordre de magnitud.

Els diners mai no van ser l’argument més fort. Aquest ho és:

El caching abarateix un prefix permanent. No el fa més petit.

Al torn 40, la versió amb system prompt encara té 1.716 tokens de política de notes de versió dins la finestra durant una conversa sobre una altra cosa completament diferent, competint pel que el Capítol 24 va anomenar el pressupost d’attention del model. La versió amb skill en té 46. Fes cache de la cosa equivocada i hauràs comprat un descompte sobre una distracció.

Escrit com a fórmula, amb $n$ torns, $L_1$ les metadades, $L_2$ el cos, $L_3$ el paquet sencer i $R$ el conjunt de fitxers empaquetats que realment es llegeixen:

Tot aquest capítol és la diferència entre multiplicar el segon terme per $n$ i multiplicar-lo per u o per zero.

Un skill és un directori. L’especificació és prou curta per exposar-la sencera:

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 ha de començar amb YAML frontmatter, i exactament dos camps són obligatoris: name i description.¹ Quatre més són opcionals i no se’n defineix cap altre:

Aquí tens el skill de notes de versió, complet, amb el cos per sota de trenta línies:

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

Llegeix què és aquest cos. No és la política: és una taula de continguts amb un ordre d’operacions. La política viu en tres fitxers que anomena i no inclou. I el primer pas passa feina a un script, perquè el codi d’un script no entra mai a la context window: només ho fa la seva sortida.²

El model de càrrega té un nom i tres etapes. L’especificació les declara amb un pressupost de token adjunt:¹

1. Metadades, uns 100 tokens: name i description, carregats a l’inici per a cada skill instal·lat.
2. Instruccions, recomanades per sota de 5.000 tokens: el cos de SKILL.md, carregat quan s’activa el skill.
3. Recursos, segons calgui: fitxers inclosos, carregats només quan alguna cosa els requereix.

La documentació de referència posa una quarta columna a la mateixa taula — quan es carrega, cost en tokens, contingut — i la fila que importa és la tercera: cap fins que s’hi accedeix.³ La frase que resumeix tot el capítol també hi és:

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

La taula mesurada al principi d’aquest capítol és aquesta afirmació comprovada contra cinc skills que ningú va escriure per a aquest article. Dues files mereixen llegir-se l’una contra l’altra.

next-best-practices té un cos de 966 tokens que enllaça a dinou fitxers amb 19.374 tokens. Demana-li que arregli un error d’hidratació i l’agent llegeix el cos més hydration-error.md: 1.409 tokens de 20.340, un factor de catorze, i els altres divuit fitxers no s’obren mai.

next-cache-components té un cos de 2.334 tokens i cap fitxer inclòs. És un skill vàlid i ben escrit, i no té cap nivell 3 per divulgar. Aquest és el límit honest de la tècnica: la divulgació progressiva només estalvia si hi ha alguna cosa a diferir. Un skill el coneixement del qual no es descompon paga tot el seu cos en activar-se, i l’única palanca que queda és no activar-lo.

El nivell 1 és una decisió d’encaminament presa a partir d’una sola frase. Res més d’un skill influeix en si s’obrirà mai: ni la qualitat del cos, ni els exemples, ni els scripts. Per tant, la descripció no és documentació. És la superfície de consulta, i pot estar malament.

L’especificació ho diu en forma d’un bon exemple i d’un de dolent, i el dolent té quatre paraules: description: Helps with PDFs.¹ Val la pena mesurar-ho en lloc d’acceptar-ho.

Sis skills, cadascun amb una descripció plausible que diu què fa i quan s’ha d’utilitzar. Vint-i-quatre sol·licituds, quatre per skill, formulades com ho faria una persona i sense anomenar mai el skill. El model veu les sis línies al seu system prompt i ha de respondre amb un nom o amb NONE. Greedy decoding, així que reprodueix. Després, les mateixes vint-i-quatre sol·licituds amb els mateixos sis skills, i les descripcions retallades fins al tema nu.

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

Llegeix primer els intervals, com va insistir el Capítol 4 i com tornarà a insistir el Capítol 29: se solapen, i vint-i-quatre casos no poden ordenar dos sistemes només pels seus agregats. La comparació aparellada és el que ho resol, i és l’instrument del Capítol 15: dels deu casos en què els dos braços discreparen, nou van anar a les descripcions riques i un a les primes. Això queda establert al llindar habitual.

Ara llegeix l’última línia, que és la troballa real. Amb descripcions primes, el model va respondre NONE en nou de vint-i-quatre sol·licituds. No el skill equivocat: cap skill. Aquí en tens quatre, literalment:

"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

Hi havia instal·lat un skill sql-review perfecte, amb un cos, exemples i una checklist, i no es va obrir mai, tres vegades seguides, en les tres preguntes per a les quals havia estat escrit. Els nivells 2 i 3 són irrellevants per a un skill que el nivell 1 no arriba mai a tocar.

El cost d’arreglar-ho: 214 tokens, la diferència entre 295 i 81, repartits entre sis skills. És la troballa del Capítol 18 arribant des de l’altre costat. Allà, canviar només la descripció d’una eina va portar el formatatge de dates de 2 encerts de 24 a 24 de 24. Aquí, canviar només la descripció d’un skill porta l’activació de 10 de 24 a 18. En tots dos casos, la solució més barata del sistema és una frase, i en tots dos casos la frase ha de nomenar el trigger i no només el tema: no què és la cosa, sinó què acaba de dir l’usuari quan s’aplica.

Un advertiment que aquest capítol deu als seus propis estàndards. Aquest és un model de mig bilió de paràmetres, i un model de frontera encamina molt millor que un 75 %. Llegeix el mecanisme, no la magnitud: el senyal d’encaminament té una sola frase de llarg independentment del model que el llegeixi, i cap model pot seleccionar segons informació que no hagis posat en aquesta frase.

El segon error és l’oposat del primer. El skill es troba, els nivells estan ben separats, i l’agent ho llegeix tot igualment.

vercel-react-best-practices és un skill genuïnament ben construït. El seu cos de 1.670 tokens és una taula de prioritats de vuit categories i una referència ràpida que anomena 70 fitxers de regles, una línia cadascun. Les regles són al disc al costat: 70 fitxers, el més petit de 132 tokens, mediana 319, el més gran 1.052. Fes-li una pregunta sobre barrel imports i el cost honest és el cos més un fitxer: per sota de 2.400 tokens contra un paquet de 53.670.

Llavors l’última línia del cos diu això:

## Full Compiled Document

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

AGENTS.md són 26.362 tokens. Són els 70 fitxers de regles concatenats: la seva suma és 25.784, i la diferència són els encapçalaments entre ells. Així que el skill ofereix a l’agent una tria entre llegir una regla mediana de 319 tokens i llegir el mateix contingut, tot sencer, a vuitanta-tres vegades el preu — i ofereix aquesta tria en una frase sense cap cost adjunt i sense cap condició sobre quan convé prendre-la.

Això no és cap bug i el fitxer no és incorrecte; un document compilat és realment útil per a una persona, i per a un agent a qui s’ha demanat auditar tota una codebase. És un fitxer de nivell 3 amb una invitació de nivell 2, i la lliçó generalitza més enllà d’aquest skill concret: cada camí que surt d’un SKILL.md hauria de dir què costa i quan val la pena, perquè el model no té manera de saber que un nom de fitxer és vuitanta-tres vegades més car que el nom de fitxer que té al damunt.

La mateixa carpeta porta una lliçó més petita sobre obsolescència. El cos diu «70 regles en 8 categories» i en llista 70; el directori rules/ conté 72 fitxers, dels quals dos són bastides (_template.md i _sections.md); i el sidecar metadata.json diu «40+ regles». Tres recomptes del mateix conjunt en una carpeta, un d’ells correcte, un d’ells aritmètic i un d’ells sobrant d’una versió anterior. Un skill és un document, i els documents es podreixen exactament com un comentari de codi que s’ha anat desviant del codi que té al costat, amb la diferència que aquest el llegeix una màquina que no alçarà una cella.

L’especificació oberta defineix sis camps de frontmatter. La implementació de referència, Claude Code, n’accepta vint.² Val la pena conèixer cinc grups pel nom, perquè són on el format deixa de ser només un document:

Arguments (arguments, argument-hint) permeten que una persona passi valors que se substitueixen dins el cos, que és el que fa que un skill sigui usable com a slash command. Abast (paths) limita l’activació a fitxers que coincideixen amb un glob. I injecció dinàmica de context és la que canvia el model mental: una línia de la forma !`git diff HEAD` s’executa abans que s’enviï el cos, i la seva sortida se substitueix al text. El document és una plantilla, i una part es calcula en el moment de la lectura.

Ara la trampa, i està declarada a la mateixa documentació: fora de Claude Code — al producte web, a través de la Skills API, en empaquetatge — només es permeten els sis camps especificats, i qualsevol altre camp és un error dur en pujar-lo.² Així, un skill que funciona perfectament en un producte no s’instal·la en un altre del mateix proveïdor, i falla al frontmatter en lloc de fallar en qualsevol cosa que poguessis provar llegint la prosa. Si vols que un skill sigui portable, els sis camps són tot el pressupost. Si no, digues-ho a compatibility, que existeix exactament per això.

Quatre coses es confonen constantment, i la confusió no és pedanteria de vocabulari: triar malament costa diners a cada torn, o et costa una garantia que pensaves que tenies.

Les dues files en negreta són tota la distinció. Un skill es llegeix; una eina s’invoca. Un skill és prosa que arriba a la context window i competeix per l’attention amb tota la resta que hi ha; el model pot seguir-lo, malinterpretar-lo o ignorar-lo, i res al sistema se n’adona. Una eina és una crida que surt completament de les mans del model: el teu codi rep arguments, els valida, comprova permisos i decideix. El Capítol 18 ho va formular com el model proposant i el teu codi disposant, i aquesta divisió és exactament la que un skill no té.

Així, sis casos reals, resolts:

La història és curta, insòlitament ben datada, i és la part que gairebé ningú explica.

Agent Skills es van publicar el 16 d’octubre de 2025 com una funcionalitat d’un proveïdor, definida en aquell anunci com «carpetes organitzades d’instruccions, scripts i recursos que els agents poden descobrir i carregar dinàmicament per rendir millor en tasques específiques», amb els tres nivells descrits mitjançant una analogia que val la pena conservar: «com un manual ben organitzat que comença amb una taula de continguts, després capítols específics i finalment un apèndix detallat».⁴

El 18 de desembre de 2025 la mateixa pàgina es va actualitzar per anunciar el format com un estàndard obert, amb una especificació pròpia a agentskills.io, governança oberta a contribucions i un validador de referència.³ Llegit el 7 de setembre de 2026, l’aparador de clients de l’estàndard llista quaranta-sis productes — editors, terminals, plataformes cloud i runtimes mòbils, inclosos els agents de codi de primera part d’Anthropic, OpenAI, Google i Mistral — cadascun enllaçant a la seva pròpia documentació de configuració.¹

La convergència amb MCP s’està fent en obert, amb números que pots comprovar:

La part interessant és el tancament, no les propostes. SEP-2076 demanava un quart primitive al costat d’eines, recursos i prompts. El working group que en va sorgir va decidir que la resposta era no: els skills viatgen sobre el primitive de recursos que ja existeix, com una extensió opt-in.⁵ El Capítol 26 va mesurar el mateix instint al changelog del protocol, on sampling, roots i logging es van deprecar en lloc de mantenir-se. Un organisme d’estandardització que elimina una proposta que ell mateix ha redactat es comporta bé, i la raó d’explicar aquesta història amb els números al davant és que els resums que llegiràs en altres llocs encara descriuen els skills com un primitive MCP.

Ara pots escriure un SKILL.md, dividir-lo en tres nivells que es paguen sols, llegir el frontmatter del skill d’algú altre i saber quins camps no sobreviuran si el puges en un altre lloc, i respondre la pregunta al voltant de la qual s’ha construït tot el capítol — system prompt, skill, eina o servidor — amb una raó en lloc d’un hàbit.

El que no pots fer és dir si el teu funciona.

Tota afirmació important d’aquest capítol era una mesura, i la més important era una exactitud: 18 de 24 contra 10 de 24, amb un interval sobre cadascuna i una prova aparellada entre elles, perquè dos agregats que se solapen no decideixen res. Aquell instrument era prestat. La descripció d’un skill és una clau d’encaminament, el seu cos és un procediment que el model pot seguir o no, i totes dues són propietats que només pots descobrir executant la cosa moltes vegades i puntuant què ha tornat: és a dir, un conjunt daurat, un grader que has escrit abans de l’execució i la mètrica que pregunta si ha funcionat cada vegada i no almenys una.

El Capítol 29 és això, i obre amb el número del qual depèn el mètode d’aquest capítol: un agent que té èxit set vegades de cada deu sembla un 70 %, i el seu pass^10 — la probabilitat que tingui èxit en les deu — és zero. També mesura tres graders sobre les mateixes dues-centes transcripcions i obté 0 %, 13 % i 26 % sense regenerar ni un sol token. Abans de confiar en la frase que acabes d’escriure dins un description, necessites l’instrument que et pot dir que és pitjor que la que has substituït.

Tots els recomptes de token d’aquest capítol es van produir localment amb tiktoken 0.14.0 i l’encoding o200k_base, el 7 de setembre de 2026: sobre els cinc skills de tercers llistats al principi d’aquest capítol, i sobre el skill release-notes escrit per a aquest capítol, el text complet del qual es reprodueix parcialment més amunt. El nivell 1 es mesura com la sola línia - name: description que un host renderitza dins el system prompt; el nivell 2 és el cos de SKILL.md després del frontmatter; el nivell 3 és qualsevol altre fitxer de la carpeta. Els costos utilitzen les tarifes mesurades del Capítol 16 per a gpt-5.6-terra, $2.00 per milió de tokens d’entrada i $0.20 per milió de tokens d’entrada en cache, aplicades a aquests recomptes: són aritmètica sobre tokens mesurats, no observacions d’una factura en viu. No s’ha cridat cap API de pagament per escriure aquest capítol.

L’experiment d’activació va executar Qwen/Qwen2.5-0.5B-Instruct en mitja precisió sobre una GPU de consum, greedy decoding, 24 sol·licituds sobre sis skills, dues vegades: una amb descripcions que indiquen què fa el skill i quan s’aplica, i una altra amb les descripcions retallades fins a un tema nu a l’estil del «poor example» de la mateixa especificació. Els intervals són Wilson al 95 %; la comparació aparellada és una prova exacta de signes bilateral sobre els deu casos discordants; l’interval de Wilson és el del Capítol 4 i la prova exacta de signes aparellada és la del Capítol 15, tots dos reutilitzats sense canvis. Llegeix les magnituds com una propietat d’un model molt petit i el mètode com a transferible.

Els cinc skills mesurats aquí són paquets de tercers, no escrits per a aquest capítol: next-best-practices i next-cache-components de vercel-labs/next-skills, i vercel-composition-patterns, vercel-react-best-practices i vercel-react-native-skills de vercel-labs/agent-skills. Els seus recomptes interns — 70 fitxers de regles, AGENTS.md a 26.362 tokens, metadata.json datat el gener de 2026 i afirmant «40+ rules» — es van llegir dels fitxers al disc el 7 de setembre de 2026 i són propietats d’aquella versió publicada, no crítiques als seus autors: cada una és el tipus de deriva que apareix en qualsevol arbre de documentació que s’edita més sovint del que es compta.