Skills e AGENTS.md: la differenza è il caricamento a richiesta
Le skills non sono istruzioni speciali: sono markdown caricato in contesto solo quando serve. Ecco il meccanismo, e quando un AGENTS.md basta ancora.
Perché agenti come Claude Code e Codex abbiano il concetto di "skills" invece di un semplice AGENTS.md ben organizzato? Quale è la differenza rispetto a un file markdown che "punta a cartelle di .md e dice all'agente quando leggerle"?
La risposta è una sola, ed è un meccanismo di caricamento: le skills sono istruzioni markdown presentate al modello come un menu di titoli e descrizioni, e lette integralmente solo quando servono. È lazy loading di contesto, non una nuova categoria di istruzioni.
La differenza non è nel contenuto, è nel momento in cui quel contenuto entra nel modello.
La confusione è legittima, perché a prima vista il formato è identico: una cartella, un file markdown, istruzioni in prosa. Per capirla serve guardare come l'agente scopre le istruzioni, e cosa paga per averle sempre a disposizione.
Cos'è una skill, davvero
Una skill è una cartella che contiene un file SKILL.md: istruzioni in markdown, precedute da un frontmatter YAML con due campi obbligatori, name e description. Nella documentazione per sviluppatori il meccanismo è descritto in tre livelli di caricamento, che corrispondono a tre momenti diversi della vita di una conversazione.
Il frontmatter è il cartellino in vetrina
Al momento dell'avvio, l'agente pre-carica nel system prompt solo il name e la description di ogni skill installata. La documentazione lo chiama progressive disclosure: il primo livello dà al modello abbastanza informazioni per sapere quando usare una skill, senza occupare il contesto con il corpo delle istruzioni. La description è ciò che il modello confronta con la richiesta dell'utente per decidere se attivare la skill, quindi deve dire sia cosa fa sia quando usarla. Il costo è dichiarato: circa 100 token per skill installata, per tutta la durata della conversazione.
I tre livelli di caricamento
Il corpo di SKILL.md è il secondo livello: entra in contesto solo quando il modello decide che la skill è rilevante, leggendola dal filesystem con un comando shell. Il terzo livello riguarda i file aggiuntivi dentro la cartella: documentazione di riferimento, esempi, script. I file vengono letti solo se richiamati, e gli script eseguibili entrano in gioco in modo ancora più radicale: l'agente li lancia e riceve in contesto solo l'output, non il codice. Ogni livello ha il suo costo dichiarato nella documentazione:
- Livello 1, metadata:
nameedescription, sempre in contesto, circa 100 token per skill - Livello 2, istruzioni: il corpo di
SKILL.md, caricato alla chiamata, sotto i 5mila token - Livello 3, risorse: file e script aggiuntivi, letti su richiesta, zero token finché non servono
Un'architettura che consente di impacchettare nei file della skill un volume di materiale effettivamente senza limite, perché finché non viene letto non costa nulla.
L'analogia usata da Anthropic è quella del manuale ben strutturato: indice, poi capitoli, poi appendici. Oppure, per chi ha assunto qualcuno di recente, quella della guida di onboarding per un nuovo arrivato: non gli consegni tutta la storia dell'azienda al primo giorno, gli dai le istruzioni quando servono.
Il conto in token
Un AGENTS.md non ha livelli: gli agenti che supportano lo standard lo leggono integralmente all'avvio, e i file nidificati (uno per sottoprogetto nei monorepo) funzionano per prossimità, con il file più vicino al file modificato che ha la precedenza. Il repository di OpenAI, per fare un esempio citato nella spec, ne conta 88. Ogni file viene "semplicemente parsato" e il suo contenuto occupa contesto per tutta la sessione, serva o no.
Il punto è quanto pesa. Ho preso un AGENTS.md realistico per un progetto medio, 59 righe con comandi di setup, convenzioni di stile, istruzioni di test e deployment, e l'ho tokenizzato con cl100k_base: 562 token. Un costo irrisorio rispetto ai contesti da centinaia di migliaia di token dei modelli attuali, ma che si paga a ogni singola conversazione, anche quando il task non tocca affatto quelle istruzioni.
La stessa quantità di istruzioni trasformata in una skill costa 100 token di metadata sempre, più 562 di corpo solo quando viene chiamata. Il risparmio esiste, ed è esattamente ciò che le skills vendono: se hai venti skill installate e in una sessione ne usi due, paghi il metadata di tutte e il corpo di due. È economia di contesto, ed è il motivo architetturale per cui il formato esiste.
Quando la skill paga, e quando no
La soglia è il volume e la frammentazione. Le skills pagano quando il corpo di istruzioni cresce oltre ciò che sta comodamente in contesto, quando i domini sono mutualmente esclusivi (le istruzioni per i PDF non servono mentre lavori sugli Excel) e quando le conoscenze sono condivise tra progetti o condivisibili pubblicamente: da dicembre 2025 Agent Skills è uno standard aperto, pensato per la portabilità tra piattaforme. Pagano anche quando servono script deterministici da eseguire senza far entrare il codice nel modello.
Non pagano quando le istruzioni sono poche, compatte e rilevanti quasi sempre. In quel caso un AGENTS.md da 500-600 token è più economico della skill equivalente: la skill replica quel costo quasi per intero quando viene chiamata, e ci aggiunge un passaggio di scoperta, la decisione del modello di attivarla in base alla descrizione. Un passaggio che può sbagliare, e che quando sbaglia degrada l'aderenza alle istruzioni.
Per un team con una base di codice stabile e un solo agente, migrare le istruzioni da AGENTS.md a skills è un costo senza guadagno: il caso in cui la skill paga davvero è un altro.
La regola pratica è quindi una sola: le skills non sostituiscono l'AGENTS.md, lo integrano quando il sapere dell'organizzazione supera quello che un file in cima al repository può contenere senza soffocare la conversazione. Se il tuo AGENTS.md sta in 60 righe, non hai un problema di contesto: hai già la soluzione giusta.
Further Reading
