Agent Skills y SKILL.md: progressive disclosure, medido

El Capítulo 14 fijó la regla para la segunda mitad de este curso —conexiones, reintentos y cancelación son TypeScript— y declaró cinco excepciones. Esta es una de ellas, y la razón no es una preferencia.

Un skill es un archivo Markdown. No un archivo que configura un programa, no un archivo que un programa compila: un documento que el modelo lee, del mismo modo que lee el mensaje que has escrito. Darle a este capítulo un lenguaje de programación significaría no haber entendido el formato, y ese malentendido es el más común sobre los skills. Todo lo que sigue es Markdown y YAML, más un pequeño script de shell que existe precisamente para mostrar dónde pertenece el código dentro de un skill y dónde no.

Aquí tienes una instrucción real: cómo escribe una empresa sus notas de lanzamiento. Es un procedimiento, no una preferencia: tiene un conjunto ordenado de pasos, una taxonomía, una voz, una plantilla y un script que recoge el material bruto.

Ponlo todo en el system prompt, como hace la mayoría de equipos, y la aritmética del Capítulo 16 toma el control. Un system prompt es un prefijo, y un prefijo se paga en cada llamada. Medido con o200k_base sobre la carpeta escrita 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

Veinticuatro veces más barato cuando se usa, treinta y siete veces más barato cuando no se usa. Las tarifas son las del Capítulo 16: $2,00 por millón de input tokens.

Ahora la objeción honesta, porque un capítulo que se la saltara sería publicidad. El prompt caching cierra casi toda la brecha económica. Un system prompt es estable y va al principio, lo que lo convierte en el mejor candidato de caché posible; a $0,20 por millón de input en caché, los mismos 68.640 tokens cuestan $0,0168 en vez de $0,1373. Sigue siendo tres veces el skill, pero ya no está en otro orden de magnitud.

El dinero nunca fue el argumento más fuerte. Este lo es:

El caching abarata un prefijo permanente. No lo hace más pequeño.

En el turno 40, la versión con system prompt sigue teniendo 1.716 tokens de política de notas de lanzamiento dentro de la ventana durante una conversación sobre cualquier otra cosa, compitiendo por lo que el Capítulo 24 llamó el presupuesto de attention del modelo. La versión con skill tiene 46. Cachea lo equivocado y habrás comprado un descuento sobre una distracción.

Escrito como fórmula, con $n$ turnos, $L_1$ los metadatos, $L_2$ el cuerpo, $L_3$ el paquete completo y $R$ el conjunto de archivos empaquetados que realmente se leen:

Todo este capítulo es la diferencia entre multiplicar el segundo término por $n$ y multiplicarlo por uno o por cero.

Un skill es un directorio. La especificación es lo bastante breve como para enunciarla completa:

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 empezar con frontmatter YAML, y solo se requieren exactamente dos campos: name y description.¹ Otros cuatro son opcionales y no se define ningún otro:

Aquí está el skill de notas de lanzamiento, completo, con su cuerpo por debajo de treinta líneas:

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

Lee qué es ese cuerpo. No es la política: es un índice con un orden de operaciones. La política vive en tres archivos que nombra y no incluye. Y el primer paso entrega trabajo a un script, porque el código de un script nunca entra en la context window: solo lo hace su salida.²

El modelo de carga tiene un nombre y tres etapas. La especificación las enuncia con un presupuesto de tokens asociado:¹

1. Metadatos, unos 100 tokens: name y description, cargados al inicio para cada skill instalado.
2. Instrucciones, recomendado por debajo de 5.000 tokens: el cuerpo de SKILL.md, cargado cuando se activa el skill.
3. Recursos, según se necesiten: archivos incluidos, cargados solo cuando algo los requiere.

La documentación de referencia añade una cuarta columna a la misma tabla —cuándo se carga, coste en tokens, contenido—, y la fila que importa es la tercera: ninguno hasta que se accede.³ La frase que resume todo el capítulo también está ahí:

Los archivos no consumen contexto hasta que se accede a ellos, así que los Skills pueden incluir documentación de API exhaustiva, grandes datasets o ejemplos extensos. No hay penalización de contexto por el contenido incluido que no se usa.³

La tabla medida al principio de este capítulo es esa afirmación comprobada contra cinco skills que nadie escribió para este artículo. Dos filas merecen leerse una frente a la otra.

next-best-practices tiene un cuerpo de 966 tokens que enlaza a diecinueve archivos con 19.374 tokens. Pídele que arregle un error de hydration y el agent lee el cuerpo más hydration-error.md: 1.409 tokens de 20.340, un factor de catorce, y los otros dieciocho archivos nunca se abren.

next-cache-components tiene un cuerpo de 2.334 tokens y ningún archivo incluido. Es un skill válido y bien escrito, y no tiene nivel 3 que revelar. Ese es el límite honesto de la técnica: la progressive disclosure solo ahorra si hay algo que diferir. Un skill cuyo conocimiento no se descompone paga todo su cuerpo al activarse, y la única palanca que queda es no activarlo.

El nivel 1 es una decisión de routing tomada a partir de una frase. Nada más de un skill influye en si alguna vez se abre: ni la calidad del cuerpo, ni los ejemplos, ni los scripts. Así que la descripción no es documentación. Es la superficie de consulta, y puede estar mal.

La especificación lo dice en forma de un buen ejemplo y uno malo, y el malo son cuatro palabras: description: Helps with PDFs.¹ Merece la pena medirlo en vez de aceptarlo.

Seis skills, cada uno con una descripción plausible que dice qué hace y cuándo usarlo. Veinticuatro solicitudes, cuatro por skill, formuladas como las formularía una persona y sin nombrar nunca el skill. El modelo ve las seis líneas en su system prompt y debe responder con un nombre o con NONE. Greedy decoding, así que reproduce. Después, las mismas veinticuatro solicitudes con los mismos seis skills, y las descripciones recortadas hasta su asunto desnudo.

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

Lee primero los intervalos, como insistió el Capítulo 4 y volverá a insistir el Capítulo 29: se solapan, y veinticuatro casos no pueden ordenar dos sistemas solo por sus agregados. La comparación pareada es lo que lo resuelve, y es el instrumento del Capítulo 15: de los diez casos en los que las dos ramas discreparon, nueve fueron para las descripciones ricas y uno para las pobres. Eso queda establecido en el umbral habitual.

Ahora lee la última línea, que es el hallazgo real. Con descripciones pobres, el modelo respondió NONE en nueve de veinticuatro solicitudes. No el skill equivocado: ningún skill. Aquí tienes cuatro de ellas, literalmente:

"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 instalado un skill sql-review perfecto, con cuerpo, ejemplos y checklist, y nunca se abrió, tres veces seguidas, ante las tres preguntas para las que fue escrito. Los niveles 2 y 3 son irrelevantes para un skill al que el nivel 1 nunca llega.

El coste de arreglarlo: 214 tokens, la diferencia entre 295 y 81, repartida entre seis skills. Es el hallazgo del Capítulo 18 llegando desde el otro lado. Allí, cambiar solo la descripción de una herramienta llevó el formateo de fechas de 2 aciertos de 24 a 24 de 24. Aquí, cambiar solo la descripción de un skill lleva la activación de 10 de 24 a 18. En ambos casos, el arreglo más barato del sistema es una frase, y en ambos casos la frase tiene que nombrar el disparador y no solo el tema: no qué es la cosa, sino qué habrá dicho justo el usuario cuando aplica.

Una salvedad que este capítulo debe a sus propios estándares. Este es un modelo de medio millardo de parámetros, y un modelo de frontera hace routing mucho mejor que el 75 %. Lee el mecanismo, no la magnitud: la señal de routing tiene una sola frase sea cual sea el modelo que la lea, y ningún modelo puede seleccionar según información que no pusiste en esa frase.

El segundo fallo es lo opuesto al primero. El skill se encuentra, los niveles están correctamente separados, y el agent lo lee entero de todos modos.

vercel-react-best-practices es un skill genuinamente bien construido. Su cuerpo de 1.670 tokens es una tabla de prioridades de ocho categorías y una referencia rápida que nombra 70 archivos de reglas, una línea cada uno. Las reglas están en disco junto a él: 70 archivos, el más pequeño de 132 tokens, mediana de 319, el mayor de 1.052. Hazle una pregunta sobre barrel imports y el coste honesto es el cuerpo más un archivo: menos de 2.400 tokens frente a un paquete de 53.670.

Entonces la última línea del cuerpo dice esto:

## Full Compiled Document

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

AGENTS.md son 26.362 tokens. Es la concatenación de los 70 archivos de reglas: su suma es 25.784, y la diferencia son los encabezados entre ellos. Así que el skill le ofrece al agent elegir entre leer una regla mediana de 319 tokens y leer el mismo contenido, todo él, a ochenta y tres veces el precio, y le ofrece esa elección en una frase sin coste asociado y sin condición sobre cuándo tomarla.

Eso no es un bug y el archivo no está mal; un documento compilado es genuinamente útil para una persona, y para un agent al que se le ha pedido auditar una codebase completa. Es un archivo de nivel 3 con una invitación de nivel 2, y la lección se generaliza más allá de este skill: cada ruta que salga de un SKILL.md debería decir qué cuesta y cuándo merece la pena, porque el modelo no tiene forma de saber que un nombre de archivo es ochenta y tres veces más caro que el nombre de archivo que tiene encima.

La misma carpeta contiene una lección menor sobre obsolescencia. El cuerpo dice «70 rules across 8 categories» y enumera 70; el directorio rules/ contiene 72 archivos, de los cuales dos son andamiaje (_template.md y _sections.md); y el sidecar metadata.json dice «40+ rules». Tres recuentos del mismo conjunto en una carpeta, uno correcto, uno aritmético y uno sobrante de una versión anterior. Un skill es un documento, y los documentos se pudren exactamente como un comentario de código que se ha desviado del código que tiene al lado, con la diferencia de que este lo lee una máquina que no levantará una ceja.

La especificación abierta define seis campos de frontmatter. La implementación de referencia, Claude Code, acepta veinte.² Merece la pena conocer cinco grupos por su nombre, porque ahí es donde el formato deja de ser solo un documento:

Argumentos (arguments, argument-hint) permiten que una persona pase valores que se sustituyen en el cuerpo, que es lo que hace que un skill sea usable como slash command. Ámbito (paths) limita la activación a archivos que coinciden con un glob. Y inyección dinámica de contexto es la que cambia el modelo mental: una línea de la forma !`git diff HEAD` se ejecuta antes de enviar el cuerpo, y su salida se sustituye en el texto. El documento es una plantilla, y parte de él se calcula en el momento de lectura.

Ahora la trampa, y está enunciada en la misma documentación: fuera de Claude Code —en el producto web, a través de la Skills API, en el empaquetado— solo se permiten los seis campos especificados, y cualquier otro campo es un error bloqueante al subir.² Así que un skill que funciona perfectamente en un producto falla al instalarse en otro del mismo proveedor, y falla en el frontmatter en vez de en algo que podrías probar leyendo la prosa. Si pretendes que un skill sea portable, los seis campos son todo el presupuesto. Si no, dilo en compatibility, que existe exactamente para eso.

Cuatro cosas se confunden constantemente entre sí, y la confusión no es pedantería terminológica: elegir mal cuesta dinero en cada turno, o te cuesta una garantía que creías tener.

Las dos filas en negrita son toda la distinción. Un skill se lee; una herramienta se invoca. Un skill es prosa que llega a la context window y compite por attention con todo lo demás que hay ahí; el modelo puede seguirlo, malinterpretarlo o ignorarlo, y nada en el sistema se entera. Una herramienta es una llamada que sale por completo de las manos del modelo: tu código recibe argumentos, los valida, comprueba permisos y decide. El Capítulo 18 lo formuló como que el modelo propone y tu código dispone, y esa división es exactamente lo que un skill no tiene.

Así que seis casos reales, resueltos:

La historia es breve, está inusualmente bien fechada y es la parte que casi nadie cuenta.

Agent Skills se publicó el 16 de octubre de 2025 como función de un proveedor, definida en aquel anuncio como «carpetas organizadas de instrucciones, scripts y recursos que los agents pueden descubrir y cargar dinámicamente para rendir mejor en tareas concretas», con los tres niveles descritos mediante una analogía que merece conservarse: «como un manual bien organizado que empieza con un índice, luego capítulos concretos y, por último, un apéndice detallado».⁴

El 18 de diciembre de 2025, la misma página se actualizó para anunciar el formato como un estándar abierto, con una especificación propia en agentskills.io, gobernanza abierta a contribuciones y un validador de referencia.³ Leído el 7 de septiembre de 2026, el escaparate de clientes del estándar enumera cuarenta y seis productos —editores, terminales, plataformas cloud y runtimes móviles, incluidos los coding agents first-party de Anthropic, OpenAI, Google y Mistral—, cada uno enlazando a su propia documentación de configuración.¹

La convergencia con MCP se está haciendo en abierto, con números que puedes comprobar:

Lo interesante es el cierre, no las propuestas. SEP-2076 pedía una cuarta primitiva junto a tools, resources y prompts. El working group que surgió de ella decidió que la respuesta era no: los skills van sobre la primitiva de resources que ya existe, como extensión opt-in.⁵ El Capítulo 26 midió el mismo instinto en el propio changelog del protocolo, donde sampling, roots y logging se deprecaron en vez de conservarse. Un organismo de estandarización que elimina una propuesta que él mismo redactó se está comportando bien, y la razón para contar esta historia con los números delante es que los resúmenes que leerás en otros sitios siguen describiendo los skills como una primitiva MCP.

Ahora puedes escribir un SKILL.md, dividirlo en tres niveles que se pagan solos, leer el frontmatter del skill de otra persona y saber qué campos no sobrevivirán a una subida en otro sitio, y responder a la pregunta alrededor de la cual se construyó todo el capítulo —system prompt, skill, herramienta o servidor— con una razón en vez de con un hábito.

Lo que no puedes hacer es saber si el tuyo funciona.

Toda afirmación importante en este capítulo fue una medición, y la más importante fue una exactitud: 18 de 24 frente a 10 de 24, con un intervalo sobre cada uno y una prueba pareada entre ellos, porque dos agregados que se solapan no deciden nada. Ese instrumento fue prestado. La descripción de un skill es una clave de routing, su cuerpo es un procedimiento que el modelo puede seguir o no, y ambas son propiedades que solo puedes averiguar ejecutando la cosa muchas veces y puntuando lo que vuelve: un conjunto dorado, un grader que escribiste antes de la ejecución y la métrica que pregunta si funcionó cada vez en vez de al menos una vez.

El Capítulo 29 es eso, y abre con el número del que depende el método de este capítulo: un agent que tiene éxito siete veces de cada diez parece un 70 %, y su pass^10 —la probabilidad de que tenga éxito en las diez— es cero. También mide tres graders sobre las mismas doscientas transcripciones y obtiene 0 %, 13 % y 26 % sin regenerar un solo token. Antes de confiar en la frase que acabas de escribir en un description, necesitas el instrumento que pueda decirte que es peor que la que sustituiste.

Todos los recuentos de tokens de este capítulo se produjeron localmente con tiktoken 0.14.0 y la codificación o200k_base, el 7 de septiembre de 2026: sobre los cinco skills de terceros enumerados al principio de este capítulo, y sobre el skill release-notes escrito para este capítulo, cuyo texto completo se reproduce arriba en parte. El nivel 1 se mide como la línea única - name: description que un host renderiza en el system prompt; el nivel 2 es el cuerpo de SKILL.md después del frontmatter; el nivel 3 es cualquier otro archivo de la carpeta. Los costes usan las tarifas medidas del Capítulo 16 para gpt-5.6-terra, $2,00 por millón de input tokens y $0,20 por millón de input tokens en caché, aplicadas a esos recuentos: son aritmética sobre tokens medidos, no observaciones de una factura real. No se llamó a ninguna API de pago para escribir este capítulo.

El experimento de activación ejecutó Qwen/Qwen2.5-0.5B-Instruct en media precisión sobre una GPU de consumo, greedy decoding, 24 solicitudes sobre seis skills, dos veces: una con descripciones que indican qué hace el skill y cuándo aplica, otra con las descripciones recortadas hasta un tema desnudo al estilo del propio «poor example» de la especificación. Los intervalos son Wilson al 95 %; la comparación pareada es una prueba exacta bilateral de signos sobre los diez casos discordantes; el intervalo de Wilson es el del Capítulo 4 y la prueba exacta pareada de signos es la del Capítulo 15, ambos reutilizados sin cambios. Lee las magnitudes como propiedad de un modelo muy pequeño y el método como transferible.

Los cinco skills medidos aquí son paquetes de terceros, no escritos para este capítulo: next-best-practices y next-cache-components de vercel-labs/next-skills, y vercel-composition-patterns, vercel-react-best-practices y vercel-react-native-skills de vercel-labs/agent-skills. Sus recuentos internos —70 archivos de reglas, AGENTS.md con 26.362 tokens, metadata.json fechado en enero de 2026 y afirmando «40+ rules»— se leyeron de los archivos en disco el 7 de septiembre de 2026 y son propiedades de esa versión publicada, no críticas a sus autores: cada una de ellas es el tipo de deriva que aparece en cualquier árbol de documentación que se edita más a menudo de lo que se cuenta.