Agent Skills e SKILL.md: disclosure progressiva, misurata

Il Capitolo 14 ha fissato la regola per la seconda metà di questo corso — connessioni, retry e cancellazione sono TypeScript — e ha dichiarato cinque eccezioni. Questa è una di quelle, e il motivo non è una preferenza.

Una skill è un file Markdown. Non un file che configura un programma, non un file che un programma compila: un documento che il modello legge, nello stesso modo in cui legge il messaggio che hai scritto. Dare a questo capitolo un linguaggio di programmazione significherebbe non aver capito il formato, e questo fraintendimento è il più comune sulle skill. Tutto qui sotto è Markdown e YAML, più un piccolo script shell che esiste proprio per mostrare dove il codice deve e non deve stare dentro una skill.

Ecco un’istruzione reale: come un’azienda scrive le sue note di rilascio. È una procedura, non una preferenza — ha una sequenza ordinata di passaggi, una tassonomia, una voce, un template e uno script che raccoglie il materiale grezzo.

Metti tutto nel system prompt, come fanno quasi tutti i team, e l’aritmetica del Capitolo 16 prende il controllo. Un system prompt è un prefisso, e un prefisso si paga a ogni chiamata. Misurato con o200k_base sulla cartella scritta per questo capitolo:

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

Ventiquattro volte più economico quando viene usata, trentasette volte più economico quando non viene usata. Le tariffe sono quelle del Capitolo 16: $2,00 per milione di token in input.

Ora l’obiezione onesta, perché un capitolo che la saltasse sarebbe pubblicità. Il prompt caching chiude quasi del tutto il divario economico. Un system prompt è stabile e sta all’inizio, il che lo rende il miglior candidato possibile per la cache; a $0,20 per milione per input in cache, gli stessi 68.640 token costano $0,0168 invece di $0,1373. Ancora tre volte la skill, ma non più un ordine di grandezza diverso.

Il denaro non è mai stato l’argomento più forte. Questo lo è:

Il caching rende più economico un prefisso permanente. Non lo rende più piccolo.

Al turno 40 la versione con system prompt ha ancora 1.716 token di policy sulle note di rilascio dentro la finestra durante una conversazione su tutt’altro, in competizione per ciò che il Capitolo 24 ha chiamato il budget di attention del modello. La versione con skill ne ha 46. Metti in cache la cosa sbagliata e hai comprato uno sconto su una distrazione.

Scritta come formula, con $n$ turni, $L_1$ i metadati, $L_2$ il corpo, $L_3$ l’intero bundle e $R$ l’insieme dei file inclusi effettivamente letti:

Tutto questo capitolo è la differenza tra moltiplicare il secondo termine per $n$ e moltiplicarlo per uno o per zero.

Una skill è una directory. La specifica è abbastanza breve da poterla enunciare per intero:

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 deve iniziare con YAML frontmatter, e sono richiesti esattamente due campi: name e description.¹ Altri quattro sono opzionali e non ne sono definiti altri:

Ecco la skill per le note di rilascio, completa, con il corpo sotto le trenta righe:

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

Leggi che cosa è quel corpo. Non è la policy — è un indice con un ordine operativo. La policy vive in tre file che il corpo nomina e non include. E il primo passaggio affida il lavoro a uno script, perché il codice di uno script non entra mai nella context window: entra solo il suo output.²

Il modello di caricamento ha un nome e tre fasi. La specifica le enuncia con un budget di token associato:¹

1. Metadati, circa 100 token: name e description, caricati all’avvio per ogni skill installata.
2. Istruzioni, raccomandate sotto i 5.000 token: il corpo di SKILL.md, caricato quando la skill viene attivata.
3. Risorse, secondo necessità: file inclusi, caricati solo quando qualcosa li richiede.

La documentazione di riferimento aggiunge una quarta colonna alla stessa tabella — quando viene caricato, costo in token, contenuto — e la riga che conta è la terza: nessuno finché non viene aperto.³ Anche la frase che riassume l’intero capitolo è lì:

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 tabella misurata all’inizio di questo capitolo è quella affermazione verificata su cinque skill che nessuno ha scritto per questo articolo. Due righe meritano di essere lette una contro l’altra.

next-best-practices ha un corpo da 966 token che rimanda a diciannove file contenenti 19.374 token. Chiedigli di correggere un errore di hydration e l’agent legge il corpo più hydration-error.md: 1.409 token su 20.340, un fattore quattordici, e gli altri diciotto file non vengono mai aperti.

next-cache-components ha un corpo da 2.334 token e nessun file incluso. È una skill valida e ben scritta, e non ha un livello 3 da rivelare. Questo è il limite onesto della tecnica: la disclosure progressiva risparmia solo se c’è qualcosa da rinviare. Una skill la cui conoscenza non si scompone paga tutto il suo corpo all’attivazione, e l’unica leva rimasta è non attivarla.

Il livello 1 è una decisione di routing presa da una frase. Nient’altro di una skill influenza se verrà mai aperta — non la qualità del corpo, non gli esempi, non gli script. Quindi la descrizione non è documentazione. È la superficie di query, e può essere sbagliata.

La specifica lo dice sotto forma di buon esempio e cattivo esempio, e quello cattivo è di quattro parole: description: Helps with PDFs.¹ Vale la pena misurarlo invece di accettarlo.

Sei skill, ciascuna con una descrizione plausibile che dice che cosa fa e quando usarla. Ventiquattro richieste, quattro per skill, formulate come le formulerebbe una persona e senza mai nominare la skill. Il modello vede le sei righe nel suo system prompt e deve rispondere con un nome o con NONE. Greedy decoding, quindi riproducibile. Poi le stesse ventiquattro richieste con le stesse sei skill, e le descrizioni ridotte al loro soggetto nudo.

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

Leggi prima gli intervalli, come ha insistito il Capitolo 4 e come insisterà di nuovo il Capitolo 29: si sovrappongono, e ventiquattro casi non possono ordinare due sistemi solo sui loro aggregati. Il confronto appaiato è ciò che decide, ed è lo strumento del Capitolo 15: dei dieci casi in cui i due rami hanno discordato, nove sono andati alle descrizioni ricche e uno a quelle sottili. Questo è stabilito alla soglia abituale.

Ora leggi l’ultima riga, che è il vero risultato. Con descrizioni sottili il modello ha risposto NONE su nove richieste su ventiquattro. Non la skill sbagliata: nessuna skill. Eccone quattro, parola per parola:

"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

Una skill sql-review perfetta era installata, con corpo, esempi e checklist, e non è mai stata aperta, tre volte di fila, sulle tre domande per cui era stata scritta. I livelli 2 e 3 sono irrilevanti per una skill che il livello 1 non raggiunge mai.

Il costo della correzione: 214 token, la differenza tra 295 e 81, distribuita su sei skill. Che è il risultato del Capitolo 18 che arriva dall’altro lato. Lì, cambiare solo la descrizione di uno strumento ha portato la formattazione delle date da 2 corrette su 24 a 24 su 24. Qui, cambiare solo la descrizione di una skill porta l’attivazione da 10 su 24 a 18. In entrambi i casi la correzione più economica del sistema è una frase, e in entrambi i casi la frase deve nominare il trigger e non solo il soggetto: non che cos’è la cosa, ma che cosa l’utente avrà appena detto quando si applica.

Una cautela che questo capitolo deve ai propri standard. Questo è un modello da mezzo miliardo di parametri, e un modello frontier fa routing molto meglio del 75%. Leggi il meccanismo, non la grandezza: il segnale di routing è lungo una frase qualunque sia il modello che lo legge, e nessun modello può selezionare in base a informazioni che non hai messo in quella frase.

Il secondo fallimento è l’opposto del primo. La skill viene trovata, i livelli sono divisi correttamente, e l’agent legge comunque tutto.

vercel-react-best-practices è una skill costruita davvero bene. Il suo corpo da 1.670 token è una tabella di priorità di otto categorie e un riferimento rapido che nomina 70 file di regole, una riga ciascuno. Le regole sono su disco accanto a esso: 70 file, il più piccolo 132 token, mediana 319, il più grande 1.052. Fai una domanda sugli import barrel e il costo onesto è il corpo più un file — sotto i 2.400 token contro un bundle di 53.670.

Poi l’ultima riga del corpo dice questo:

## Full Compiled Document

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

AGENTS.md è 26.362 token. Sono i 70 file di regole concatenati: la loro somma è 25.784, e la differenza sono i titoli tra loro. Quindi la skill offre all’agent una scelta tra leggere una regola mediana da 319 token e leggere lo stesso contenuto, tutto, a ottantatré volte il prezzo — e offre quella scelta in una frase senza costo associato e senza condizione su quando prenderla.

Non è un bug e il file non è sbagliato; un documento compilato è davvero utile a una persona, e a un agent a cui è stato chiesto di fare audit di un’intera codebase. È un file di livello 3 con un invito di livello 2, e la lezione si generalizza oltre questa skill: ogni percorso che esce da un SKILL.md dovrebbe dire quanto costa e quando ne vale la pena, perché il modello non ha modo di sapere che un nome file è ottantatré volte più caro del nome file sopra di lui.

La stessa cartella contiene una lezione più piccola sulla staleness. Il corpo dice «70 regole in 8 categorie» e ne elenca 70; la directory rules/ contiene 72 file, due dei quali sono scaffolding (_template.md e _sections.md); e il sidecar metadata.json dice «40+ regole». Tre conteggi dello stesso insieme in una cartella, uno giusto, uno aritmetico e uno rimasto da una versione precedente. Una skill è un documento, e i documenti marciscono esattamente come un commento nel codice che si è allontanato dal codice accanto a sé — con la differenza che questo viene letto da una macchina che non alzerà un sopracciglio.

La specifica aperta definisce sei campi di frontmatter. L’implementazione di riferimento, Claude Code, ne accetta venti.² Cinque gruppi vale la pena conoscerli per nome, perché sono il punto in cui il formato smette di essere solo un documento:

Argomenti (arguments, argument-hint) permettono a una persona di passare valori che vengono sostituiti nel corpo, ed è questo che rende una skill usabile come slash command. Lo scoping (paths) limita l’attivazione ai file che corrispondono a un glob. E la dynamic context injection è quella che cambia il modello mentale: una riga della forma !`git diff HEAD` viene eseguita prima che il corpo sia inviato, e il suo output viene sostituito nel testo. Il documento è un template, e parte di esso viene calcolata al momento della lettura.

Ora la trappola, ed è dichiarata nella stessa documentazione: fuori da Claude Code — nel prodotto web, tramite la Skills API, nel packaging — sono permessi solo i sei campi specificati, e qualunque altro campo è un errore bloccante in upload.² Quindi una skill che funziona perfettamente in un prodotto non si installa in un altro dello stesso vendor, e fallisce nel frontmatter invece che in qualcosa che potresti testare leggendo la prosa. Se vuoi che una skill sia portabile, i sei campi sono tutto il budget. Se non lo vuoi, dillo in compatibility, che esiste esattamente per questo.

Quattro cose vengono confuse continuamente, e la confusione non è pedanteria lessicale: scegliere male costa denaro a ogni turno, oppure ti costa una garanzia che pensavi di avere.

Le due righe in grassetto sono tutta la distinzione. Una skill viene letta; uno strumento viene invocato. Una skill è prosa che arriva nella context window e compete per l’attention con tutto il resto lì dentro; il modello può seguirla, fraintenderla o ignorarla, e nulla nel sistema se ne accorge. Uno strumento è una chiamata che esce del tutto dalle mani del modello: il tuo codice riceve argomenti, li valida, controlla i permessi e decide. Il Capitolo 18 l’ha formulato come il modello che propone e il tuo codice che dispone, e quella divisione è esattamente ciò che una skill non ha.

Quindi sei casi reali, risolti:

La storia è breve, insolitamente ben datata, ed è la parte che quasi nessuno racconta.

Agent Skills è stato pubblicato il 16 ottobre 2025 come funzionalità di un vendor, definito in quell’annuncio come «organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks», con i tre livelli descritti tramite un’analogia che vale la pena conservare: «like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix».⁴

Il 18 dicembre 2025 la stessa pagina è stata aggiornata per annunciare il formato come standard aperto, con una specifica propria su agentskills.io, governance aperta ai contributi e un validatore di riferimento.³ Letto il 7 settembre 2026, lo showcase dei client dello standard elenca quarantasei prodotti — editor, terminali, piattaforme cloud e runtime mobili, inclusi gli agent di coding first-party di Anthropic, OpenAI, Google e Mistral — ciascuno con link alla propria documentazione di setup.¹

La convergenza con MCP viene fatta in pubblico, con numeri che puoi verificare:

La parte interessante è la chiusura, non le proposte. SEP-2076 chiedeva una quarta primitiva accanto a strumenti, risorse e prompt. Il working group nato da quella proposta ha deciso che la risposta era no: le skill viaggiano sulla primitiva resources già esistente, come estensione opt-in.⁵ Il Capitolo 26 ha misurato lo stesso istinto nel changelog del protocollo, dove sampling, roots e logging sono stati deprecati invece che mantenuti. Un ente di standardizzazione che rimuove una proposta che aveva scritto si sta comportando bene, e il motivo per raccontare questa storia con i numeri davanti è che i riassunti che leggerai altrove descrivono ancora le skill come una primitiva MCP.

Ora puoi scrivere un SKILL.md, dividerlo in tre livelli che si ripagano, leggere il frontmatter della skill di qualcun altro e sapere quali campi non sopravviveranno a un upload altrove, e rispondere alla domanda attorno a cui è stato costruito l’intero capitolo — system prompt, skill, strumento o server — con una ragione invece che per abitudine.

Quello che non puoi fare è dire se la tua funziona.

Ogni affermazione importante in questo capitolo era una misura, e quella più importante era un’accuratezza: 18 su 24 contro 10 su 24, con un intervallo su ciascuna e un test appaiato tra loro, perché due aggregati che si sovrappongono non decidono nulla. Quello strumento è stato preso in prestito. La descrizione di una skill è una chiave di routing, il suo corpo è una procedura che il modello può seguire oppure no, ed entrambe sono proprietà che puoi scoprire solo eseguendo la cosa molte volte e valutando ciò che è tornato — cioè un golden set, un grader che hai scritto prima dell’esecuzione, e la metrica che chiede se ha funzionato ogni volta invece che almeno una volta.

Il Capitolo 29 è questo, e si apre con il numero da cui dipende il metodo di questo capitolo: un agent che riesce sette volte su dieci sembra al 70%, e il suo pass^10 — la probabilità che riesca in tutte e dieci — è zero. Misura anche tre grader sugli stessi duecento transcript e ottiene 0%, 13% e 26% senza rigenerare un solo token. Prima di fidarti della frase che hai appena scritto in un description, ti serve lo strumento che possa dirti che è peggiore di quella che hai sostituito.

Ogni conteggio di token in questo capitolo è stato prodotto localmente con tiktoken 0.14.0 e l’encoding o200k_base, il 7 settembre 2026: sulle cinque skill di terze parti elencate all’inizio di questo capitolo, e sulla skill release-notes scritta per questo capitolo, il cui testo completo è riprodotto sopra in parte. Il livello 1 è misurato come la singola riga - name: description che un host renderizza nel system prompt; il livello 2 è il corpo di SKILL.md dopo il frontmatter; il livello 3 è ogni altro file nella cartella. I costi usano le tariffe misurate del Capitolo 16 per gpt-5.6-terra, $2,00 per milione di token in input e $0,20 per milione di token di input in cache, applicate a quei conteggi — sono aritmetica su token misurati, non osservazioni di una fattura live. Nessuna API a pagamento è stata chiamata per scrivere questo capitolo.

L’esperimento di attivazione ha eseguito Qwen/Qwen2.5-0.5B-Instruct in mezza precisione su una GPU consumer, greedy decoding, 24 richieste su sei skill, due volte — una con descrizioni che dichiarano che cosa fa la skill e quando si applica, una con le descrizioni ridotte a un soggetto nudo nello stile del «poor example» della specifica. Gli intervalli sono Wilson al 95%; il confronto appaiato è un exact sign test a due code sui dieci casi discordanti; l’intervallo di Wilson è quello del Capitolo 4 e l’exact paired sign test è quello del Capitolo 15, entrambi riutilizzati senza modifiche. Leggi le grandezze come proprietà di un modello molto piccolo e il metodo come trasferibile.

Le cinque skill misurate qui sono pacchetti di terze parti, non scritti per questo capitolo: next-best-practices e next-cache-components da vercel-labs/next-skills, e vercel-composition-patterns, vercel-react-best-practices e vercel-react-native-skills da vercel-labs/agent-skills. I loro conteggi interni — 70 file di regole, AGENTS.md a 26.362 token, metadata.json datato gennaio 2026 e con l’affermazione «40+ rules» — sono stati letti dai file su disco il 7 settembre 2026 e sono proprietà di quella versione pubblicata, non critiche ai loro autori: ciascuno è il tipo di drift che appare in qualunque albero di documentazione modificato più spesso di quanto venga contato.