Agent Skills e SKILL.md: divulgación progresiva, medida

O Capítulo 14 estableceu a regra para a segunda metade deste curso — conexións, reintentos e cancelación son TypeScript — e declarou cinco excepcións. Esta é unha delas, e a razón non é unha preferencia.

Unha skill é un ficheiro Markdown. Non un ficheiro que configura un programa, nin un ficheiro que un programa compila: un documento que o modelo le, igual que le a mensaxe que escribiches. Poñerlle unha linguaxe de programación a este capítulo significaría non ter entendido o formato, e ese malentendido é o máis común sobre as skills. Todo o que vén despois é Markdown e YAML, máis un pequeno script de shell que existe precisamente para amosar onde debe estar o código dentro dunha skill e onde non.

Esta é unha instrución real: como unha empresa escribe as súas notas de versión. É un procedemento, non unha preferencia: ten un conxunto ordenado de pasos, unha taxonomía, unha voz, un modelo e un script que recolle a materia prima.

Mete todo iso no system prompt, como fan a maioría dos equipos, e a aritmética do Capítulo 16 toma o control. Un system prompt é un prefixo, e un prefixo págase en cada chamada. Medido con o200k_base sobre o cartafol escrito para este capítulo:

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

Vinte e catro veces máis barato cando se usa, trinta e sete veces máis barato cando non se usa. As tarifas son as do Capítulo 16: $2.00 por millón de input tokens.

Agora a obxección honesta, porque un capítulo que a saltase sería publicidade. O prompt caching pecha case toda a fenda de diñeiro. Un system prompt é estable e vai ao comezo, o que o converte no mellor candidato posible para cache; a $0.20 por millón de input en cache, os mesmos 68.640 tokens custan $0.0168 no canto de $0.1373. Aínda tres veces máis que a skill, pero xa non unha orde de magnitude distinta.

O diñeiro nunca foi o argumento máis forte. É este:

O caching abarata un prefixo permanente. Non o fai máis pequeno.

No turno 40, a versión con system prompt segue tendo 1.716 tokens de política de notas de versión dentro da xanela durante unha conversa sobre algo completamente distinto, competindo polo que o Capítulo 24 chamou o orzamento de attention do modelo. A versión con skill ten 46. Fai cache do que non toca e acabas de mercar un desconto nunha distracción.

Escrito como fórmula, con $n$ turnos, $L_1$ os metadatos, $L_2$ o corpo, $L_3$ o paquete completo e $R$ o conxunto de ficheiros empaquetados que realmente se len:

Todo este capítulo é a diferenza entre multiplicar o segundo termo por $n$ e multiplicalo por un ou por cero.

Unha skill é un directorio. A especificación é o bastante curta como para expoñela enteira:

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 debe comezar con YAML frontmatter, e requírense exactamente dous campos: name e description.¹ Catro máis son opcionais e non se define ningún outro:

Esta é a skill de notas de versión, completa, co corpo por debaixo de trinta liñas:

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

Le o que é ese corpo. Non é a política: é unha táboa de contidos cunha orde de operacións. A política vive en tres ficheiros que o corpo nomea e non inclúe. E o primeiro paso pásalle traballo a un script, porque o código dun script nunca entra na context window: só entra a súa saída.²

O modelo de carga ten nome e tres fases. A especificación descríbeas cun orzamento de token asociado:¹

1. Metadatos, arredor de 100 tokens: name e description, cargados no inicio para cada skill instalada.
2. Instrucións, recomendadas por debaixo de 5.000 tokens: o corpo de SKILL.md, cargado cando se activa a skill.
3. Recursos, segundo sexan necesarios: ficheiros empaquetados, cargados só cando algo os require.

A documentación de referencia pon unha cuarta columna na mesma táboa — cando se carga, custo en token, contido — e a fila que importa é a terceira: nada ata que se accede.³ A frase que resume todo o capítulo tamén está aí:

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

A táboa medida ao comezo deste capítulo é esa afirmación comprobada contra cinco skills que ninguén escribiu para este artigo. Hai dúas filas que paga a pena ler unha fronte á outra.

next-best-practices ten un corpo de 966 tokens que enlaza con dezanove ficheiros que conteñen 19.374 tokens. Pídelle que arranxe un erro de hidratación e o agent le o corpo máis hydration-error.md: 1.409 tokens de 20.340, un factor de catorce, e os outros dezaoito ficheiros nunca se abren.

next-cache-components ten un corpo de 2.334-token e ningún ficheiro empaquetado. É unha skill válida e ben escrita, e non ten nivel 3 que divulgar. Ese é o límite honesto da técnica: a divulgación progresiva só aforra se hai algo que aprazar. Unha skill cuxo coñecemento non se descompón paga todo o seu corpo ao activarse, e a única panca que queda é non activala.

O nivel 1 é unha decisión de routing tomada a partir dunha frase. Nada máis dunha skill inflúe en se chega a abrirse: nin a calidade do corpo, nin os exemplos, nin os scripts. Así que a descrición non é documentación. É a superficie de consulta, e pode estar mal.

A especificación dio en forma dun bo exemplo e dun malo, e o malo son catro palabras: description: Helps with PDFs.¹ Iso merece medirse, non simplemente aceptarse.

Seis skills, cada unha cunha descrición plausible que di que fai e cando usala. Vinte e catro solicitudes, catro por skill, formuladas como as formularía unha persoa e sen nomear nunca a skill. O modelo ve as seis liñas no seu system prompt e debe responder cun nome ou con NONE. Greedy decoding, para que reproduza. Despois, as mesmas vinte e catro solicitudes coas mesmas seis skills, e as descricións recortadas ao seu asunto máis cru.

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

Le primeiro os intervalos, como insistiu o Capítulo 4 e como volverá insistir o Capítulo 29: solápanse, e vinte e catro casos non poden ordenar dous sistemas só polos seus agregados. A comparación emparellada é a que o resolve, e é o instrumento do Capítulo 15: dos dez casos nos que os dous brazos discreparon, nove foron para as descricións ricas e un para as delgadas. Iso queda establecido no limiar habitual.

Agora le a última liña, que é o achado real. Con descricións delgadas, o modelo respondeu NONE en nove de vinte e catro solicitudes. Non a skill equivocada: ningunha skill. Aquí tes catro delas, palabra por palabra:

"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

Había instalada unha skill sql-review perfecta, con corpo e exemplos e unha checklist, e nunca se abriu, tres veces seguidas, nas tres preguntas para as que fora escrita. Os niveis 2 e 3 son irrelevantes para unha skill á que o nivel 1 nunca chega.

O custo de arranxalo: 214 tokens, a diferenza entre 295 e 81, repartida entre seis skills. É o achado do Capítulo 18 chegando desde o outro lado. Alí, cambiar só a descrición dunha ferramenta levou o formato de datas de 2 correctas de 24 a 24 de 24. Aquí, cambiar só a descrición dunha skill leva a activación de 10 de 24 a 18. Nos dous casos, o arranxo máis barato do sistema é unha frase, e nos dous casos a frase ten que nomear o disparador e non só o asunto: non que é a cousa, senón que acaba de dicir o usuario cando aplica.

Unha advertencia que este capítulo lle debe aos seus propios estándares. Este é un modelo de medio milleiro de millóns de parámetros, e un modelo de fronteira fai routing moito mellor que o 75 %. Le o mecanismo, non a magnitude: o sinal de routing ten unha frase de longo sexa cal sexa o modelo que o lea, e ningún modelo pode seleccionar sobre información que non puxeches nesa frase.

O segundo fallo é o contrario do primeiro. A skill atópase, os niveis están ben divididos, e o agent léao todo igual.

vercel-react-best-practices é unha skill realmente ben construída. O seu corpo de 1.670-token é unha táboa de prioridades de oito categorías e unha referencia rápida que nomea 70 ficheiros de regras, unha liña cada un. As regras están no disco ao seu carón: 70 ficheiros, o menor de 132 tokens, mediana 319, o maior 1.052. Pregúntalle unha cuestión sobre importacións barrel e o custo honesto é o corpo máis un ficheiro: menos de 2.400 tokens fronte a un paquete de 53.670.

Entón a última liña do corpo di isto:

## Full Compiled Document

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

AGENTS.md son 26.362 tokens. Son os 70 ficheiros de regras concatenados: a súa suma é 25.784, e a diferenza son os títulos entre eles. Así que a skill ofrécelle ao agent escoller entre ler unha regra mediana de 319 tokens e ler o mesmo contido, enteiro, a oitenta e tres veces o prezo — e ofrece esa elección nunha frase sen custo asociado e sen condición sobre cando tomala.

Iso non é un bug e o ficheiro non está mal; un documento compilado é realmente útil para unha persoa, e para un agent ao que se lle pediu auditar unha base de código enteira. É un ficheiro de nivel 3 cun convite de nivel 2, e a lección xeneralízase máis alá desta skill: cada camiño que sae dun SKILL.md debería dicir que custa e cando paga a pena, porque o modelo non ten maneira de saber que un nome de ficheiro é oitenta e tres veces máis caro que o nome de ficheiro que ten enriba.

O mesmo cartafol contén unha lección menor sobre obsolescencia. O corpo di "70 rules across 8 categories" e lista 70; o directorio rules/ contén 72 ficheiros, dos cales dous son andamiaxe (_template.md e _sections.md); e o sidecar metadata.json di "40+ rules". Tres contas do mesmo conxunto nun cartafol, unha correcta, unha aritmética e unha arrastrada dunha versión anterior. Unha skill é un documento, e os documentos podrecen exactamente igual que un comentario de código que se desfasou do código que ten ao lado, coa diferenza de que este léao unha máquina que non vai erguer unha cella.

A especificación aberta define seis campos de frontmatter. A implementación de referencia, Claude Code, acepta vinte.² Hai cinco grupos que convén coñecer polo nome, porque son onde o formato deixa de ser só un documento:

Argumentos (arguments, argument-hint) permiten que unha persoa pase valores que se substitúen no corpo, que é o que fai que unha skill sexa usable como comando slash. Ámbito (paths) limita a activación a ficheiros que coinciden cun glob. E a inxección dinámica de contexto é a que cambia o modelo mental: unha liña da forma !`git diff HEAD` execútase antes de enviar o corpo, e a súa saída substitúese no texto. O documento é un modelo, e unha parte calcúlase no momento da lectura.

Agora a trampa, e está formulada na mesma documentación: fóra de Claude Code — no produto web, a través da Skills API, no empaquetado — só se permiten os seis campos especificados, e calquera outro campo é un erro duro ao subir.² Así que unha skill que funciona perfectamente nun produto falla ao instalarse noutro do mesmo provedor, e falla no frontmatter e non en algo que poderías comprobar lendo a prosa. Se queres que unha skill sexa portátil, os seis campos son todo o orzamento. Se non, dilo en compatibility, que existe exactamente para iso.

Catro cousas confúndense entre si constantemente, e a confusión non é pedantería de vocabulario: escoller mal custa diñeiro en cada turno, ou cústache unha garantía que pensabas que tiñas.

As dúas filas en negra son toda a distinción. Unha skill lese; unha ferramenta invócase. Unha skill é prosa que chega á context window e compite pola attention con todo o demais que hai nela; o modelo pode seguila, interpretala mal ou ignorala, e nada no sistema se decata. Unha ferramenta é unha chamada que sae completamente das mans do modelo: o teu código recibe argumentos, valídaos, comproba permisos e decide. O Capítulo 18 formulouno como que o modelo propón e o teu código dispón, e esa división é exactamente o que unha skill non ten.

Así que seis casos reais, resoltos:

A historia é curta, extraordinariamente ben datada, e é a parte que case ninguén conta.

Agent Skills publicouse o 16 de outubro de 2025 como funcionalidade dun provedor, definida nese anuncio como "cartafoles organizados de instrucións, scripts e recursos que os agents poden descubrir e cargar dinamicamente para render mellor en tarefas específicas", cos tres niveis descritos mediante unha analoxía que convén conservar: "como un manual ben organizado que comeza cunha táboa de contidos, segue con capítulos específicos e remata cun apéndice detallado".⁴

O 18 de decembro de 2025 a mesma páxina actualizouse para anunciar o formato como estándar aberto, cunha especificación propia en agentskills.io, gobernanza aberta a contribucións e un validador de referencia.³ Lida o 7 de setembro de 2026, a mostra de clientes do estándar lista corenta e seis produtos — editores, terminais, plataformas cloud e runtimes móbiles, incluíndo os coding agents first-party de Anthropic, OpenAI, Google e Mistral — cada un enlazando coa súa propia documentación de configuración.¹

A converxencia con MCP estase facendo en aberto, con números que podes comprobar:

O interesante é o peche, non as propostas. SEP-2076 pedía un cuarto primitivo xunto a ferramentas, recursos e prompts. O working group que xurdiu del decidiu que a resposta era non: as skills viaxan sobre o primitivo de recursos que xa existe, como extensión opt-in.⁵ O Capítulo 26 mediu o mesmo instinto no changelog do propio protocolo, onde sampling, roots e logging se deprecaron no canto de conservarse. Un organismo de estándares que elimina unha proposta que el mesmo redactou está comportándose ben, e a razón para contar esta historia cos números diante é que os resumos que lerás noutros sitios aínda describen as skills como un primitivo de MCP.

Agora podes escribir un SKILL.md, dividilo en tres niveis que se pagan sós, ler o frontmatter da skill doutra persoa e saber que campos non sobrevivirán ao subila a outro sitio, e responder á pregunta arredor da que se construíu todo o capítulo — system prompt, skill, ferramenta ou server — cunha razón e non cun hábito.

O que non podes facer é saber se a túa funciona.

Cada afirmación importante deste capítulo foi unha medición, e a máis importante foi unha precisión: 18 de 24 contra 10 de 24, cun intervalo en cada unha e unha proba emparellada entre elas, porque dous agregados que se solapan non deciden nada. Ese instrumento tomouse prestado. A descrición dunha skill é unha chave de routing, o seu corpo é un procedemento que o modelo pode seguir ou non, e ambas as dúas son propiedades que só podes descubrir executando a cousa moitas veces e puntuando o que volveu: un conxunto dourado, un avaliador que escribiches antes da execución, e a métrica que pregunta se funcionou todas as veces e non polo menos unha vez.

O Capítulo 29 é iso, e abre co número do que depende o método deste capítulo: un agent que ten éxito sete de cada dez veces parece un 70 %, e o seu pass^10 — a probabilidade de ter éxito nas dez — é cero. Tamén mide tres avaliadores sobre as mesmas duascentas transcricións e obtén 0 %, 13 % e 26 % sen rexenerar un só token. Antes de confiar na frase que acabas de escribir nun description, necesitas o instrumento que che diga que é peor ca a que substituíches.

Cada reconto de token deste capítulo produciuse localmente con tiktoken 0.14.0 e a codificación o200k_base, o 7 de setembro de 2026: sobre as cinco skills de terceiros listadas ao comezo deste capítulo, e sobre a skill release-notes escrita para este capítulo, cuxo texto completo se reproduce parcialmente arriba. O nivel 1 mídese como a única liña - name: description que un host renderiza no system prompt; o nivel 2 é o corpo de SKILL.md despois do frontmatter; o nivel 3 son todos os demais ficheiros do cartafol. Os custos usan as tarifas medidas no Capítulo 16 para gpt-5.6-terra, $2.00 por millón de input tokens e $0.20 por millón de input tokens en cache, aplicadas a eses recontos: son aritmética sobre tokens medidos, non observacións dunha factura real. Non se chamou ningunha API de pago para escribir este capítulo.

O experimento de activación executou Qwen/Qwen2.5-0.5B-Instruct en media precisión nunha GPU de consumo, greedy decoding, 24 solicitudes sobre seis skills, dúas veces: unha con descricións que din que fai a skill e cando aplica, outra coas descricións recortadas a un asunto cru ao estilo do "poor example" da propia especificación. Os intervalos son Wilson ao 95 %; a comparación emparellada é unha proba exacta dos signos bilateral sobre os dez casos discordantes; o intervalo de Wilson é o do Capítulo 4 e a proba exacta dos signos emparellada é a do Capítulo 15, ambos reutilizados sen cambios. Le as magnitudes como propiedade dun modelo moi pequeno e o método como transferible.

As cinco skills medidas aquí son paquetes de terceiros, non escritos para este capítulo: next-best-practices e next-cache-components de vercel-labs/next-skills, e vercel-composition-patterns, vercel-react-best-practices e vercel-react-native-skills de vercel-labs/agent-skills. Os seus recontos internos — 70 ficheiros de regras, AGENTS.md con 26.362 tokens, metadata.json datado en xaneiro de 2026 e afirmando "40+ rules" — léronse dos ficheiros no disco o 7 de setembro de 2026 e son propiedades desa versión publicada, non críticas aos seus autores: cada un deles é o tipo de deriva que aparece en calquera árbore de documentación que se edita máis a miúdo do que se conta.