Claude Skills spiegati: i tre livelli della divulgazione progressiva

Un Claude Skill è, fisicamente, una cartella. Non un servizio ospitato, non un binario, non un blocco di testo da incollare all'inizio di una conversazione — una directory che contiene un file SKILL.md e tutto ciò che serve al compito. Quasi tutto ciò che c'è di interessante nei Skills deriva da quella singola decisione, perché una cartella è qualcosa che un agente può aprire in modo selettivo. Un prompt non può essere aperto in modo selettivo. O è nella conversazione oppure no.

La documentazione di Anthropic descrive la disposizione come organizzata alla stregua di una guida di onboarding che creeresti per un nuovo membro del team, e l’analogia regge più di quanto sembri a prima vista. Nessuno legge una guida di onboarding dall’inizio alla fine prima di iniziare a lavorare. Si legge la pagina che corrisponde alla domanda che si ha davanti, e si confida che il resto sia ancora lì quando serve. Una skill si basa sulla stessa scommessa: che la maggior parte di una procedura possa rimanere su disco per la maggior parte del tempo.

Prima il filesystem, poi la capacità

Claude opera in una macchina virtuale con accesso al filesystem. Questa è la precondizione perché una skill sia una directory anziché una voce di configurazione, poiché consente all'agente di elencare una cartella, leggere un file e seguire un riferimento a un altro file usando le stesse operazioni che userebbe una persona. Al suo interno, una skill raccoglie istruzioni, metadati e risorse opzionali come script e template.

Il risultato è una capacità più ampia di qualsiasi singolo file nella cartella. Le istruzioni indicano come svolgere l'attività. Uno script incluso può eseguirne una parte senza essere descritto in prosa. Un documento di riferimento può contenere materiale che viene consultato anziché ricordato. Ciò che rende quelle tre cose un sistema invece di un mucchio è l'ordine in cui diventano visibili, che è la parte che Anthropic chiama progressive disclosure: caricare le informazioni per fasi man mano che servono anziché consumare il contesto in anticipo.

Livello 1: i due campi che vengono sempre caricati

Ogni skill inizia con un frontmatter YAML che contiene un nome e una descrizione. Claude carica questi metadati all'avvio e li include nel prompt di sistema. È l'unica parte della skill presente prima che qualcuno chieda qualcosa e, finché una skill non viene attivata, solo il suo nome e la sua descrizione occupano il contesto.

La descrizione svolge tre funzioni contemporaneamente, e distinguerle spiega perché così tante skill vengano ignorate in silenzio. È un'etichetta, che dice come si chiama la cosa. È una voce di indice, il testo con cui viene confrontata una richiesta quando Claude decide se la skill è pertinente. Ed è una dichiarazione di ambito, ed è per questo che le linee guida di Anthropic dicono che deve specificare sia cosa fa la skill sia quando usarla. Una descrizione che riesce a coprire solo la prima non dà nulla al meccanismo di confronto su cui trovare una corrispondenza.

Prendi due versioni della stessa competenza. Una è descritta come compilazione e convalida di moduli PDF, da usare quando una richiesta implica compilare o controllare un modulo PDF. L'altra è descritta come un aiuto con i documenti. La prima nomina un'azione e una situazione; la seconda non nomina nessuna delle due. Una competenza la cui descrizione non nomina nessuna delle due resterà sul disco senza essere letta mentre l'agente svolge il compito per la via più lunga — non perché la competenza abbia fallito, ma perché non è mai stata trovata.

Livello 2: il corpo, da leggere quando la descrizione corrisponde

Quando una richiesta corrisponde alla descrizione, si apre il secondo livello: il corpo di SKILL.md. Questa è la procedura — flussi di lavoro, buone pratiche, indicazioni — ed è scritta per un agente che ha già deciso che questa competenza è lo strumento giusto per il compito. È il luogo in cui un team annota i passaggi che altrimenti ripeterebbe in ogni conversazione, ed è il luogo in cui si trovano i riferimenti a materiale più approfondito.

L'ordine conta qui tanto quanto conta al livello 1. Il corpo non viene caricato all'avvio, e non viene caricato per sicurezza. Arriva dopo che è stata presa una decisione, il che significa che la decisione deve essere possibile già solo dal livello 1. Una skill con una descrizione vaga non ha modo di recuperare al livello 2, perché il livello 2 non viene mai letto.

Livello 3: file che si aprono perché qualcosa li ha indicati

Il terzo livello è il resto della cartella: file aggiuntivi a cui fa riferimento SKILL.md. L'esempio di Anthropic è un FORMS.md che contiene indicazioni avanzate sulla compilazione di moduli, tenuto fuori dalle istruzioni principali così che queste restino brevi e il dettaglio sia disponibile solo quando un'attività lo richiede. Anche script e modelli appartengono a questo livello.

L'effetto strutturale è che una skill può portare con sé una grande quantità di materiale senza portarla tutta in una volta. Una cartella può contenere un file di istruzioni principale, un riferimento dettagliato, una serie di template e uno script, e un determinato compito potrebbe interessare solo uno di essi. Tutto ciò a cui nulla fa riferimento resta sul disco, e il disco non è la risorsa scarsa in un agente. Il contesto lo è.

È anche il punto in cui il formato innalza il limite contro cui si scontrano i prompt. Un prompt deve essere abbastanza breve da valere la pena di incollarlo. Il materiale allegato a una skill è limitato da ciò che una directory può contenere, perché l'unica parte che raggiunge il modello è quella che l'attività ha effettivamente toccato.

Perché l'ordine è il design, non un dettaglio

Ne derivano tre conseguenze, e insieme costituiscono il motivo per cui vale la pena comprenderlo anziché limitarsi a saperlo.

• Il contesto è un budget, e il contenuto sempre caricato è un costo fisso. Tutto ciò che sta in un prompt di sistema viene pagato a ogni richiesta, comprese le richieste che non hanno nulla a che fare con quella competenza. La divulgazione progressiva trasforma un costo fisso in uno condizionale: una descrizione sempre, le istruzioni quando pertinenti, i riferimenti quando vengono citati.

• La descrizione è un'interfaccia. È l'unica parte di una skill che si ha la certezza venga vista, quindi è lì che chi scrive deve pensare all'attivazione e non solo al contenuto.

• Una skill ha tre velocità di manutenzione.I metadati cambiano quando la skill dovrebbe attivarsi in modo diverso, il corpo cambia quando cambia il flusso di lavoro, e i riferimenti cambiano quando cambia il materiale sottostante. Tenerli separati evita che un aggiornamento dei riferimenti si trasformi in una riscrittura delle istruzioni.

Il costo è l'immagine speculare del beneficio. Ogni confine di livello è un punto in cui il modello deve prendere una decisione in modo corretto. Una descrizione troppo ristretta significa che la skill non si attiva mai e la cartella è un peso morto. Una troppo ampia significa che si attiva su lavori per cui non è stata creata, e le sue istruzioni diventano una tassa sui compiti non correlati. La divulgazione progressiva rende la descrizione portante in un modo in cui un prompt lungo, sempre presente, non lo è mai.

Quello che Anthropic già offre e da dove provengono le tue competenze

Anthropic offre Skills precompilate per PowerPoint, Excel, Word e PDF — presentazioni, fogli di calcolo, documenti e output PDF formattati. Sono disponibili su claude.ai, la Claude API, Claude Platform on AWS e Microsoft Foundry, con l'avvertenza che su Foundry richiedono un deployment Hosted on Anthropic.

Quelle sono il modo più rapido per vedere il meccanismo invece di leggerne la descrizione. L’ordine di caricamento è identico a quello di qualunque cosa tu scriva da te; la differenza tra una skill pre-costruita e una personalizzata sta in chi ha creato la cartella, non in come arriva al modello.

Le competenze personalizzate possono essere create in Claude Code, caricate tramite l'API di Claude o aggiunte nelle impostazioni di claude.ai. I vantaggi dichiarati da Anthropic sono quelli che ci si aspetterebbe da qualsiasi cosa riutilizzabile: specializzare Claude per attività di dominio, creare indicazioni una volta sola invece di ripeterle e comporre più competenze per lavori a più passaggi. L'ultimo di questi deriva in modo più diretto dall'architettura, perché se ogni competenza è una cartella che si apre su richiesta, un insieme di competenze costa molto poco finché il lavoro non ne ha effettivamente bisogno.

Una competenza non è un prompt, né un connettore

Tre cose vengono confuse nella conversazione, e l'ordine di caricamento rende facile mantenere le distinzioni.

Un prompt è a livello di conversazione. È presente fin dal primo turno, colora tutto in quella conversazione e scompare con la conversazione. Una skill è su richiesta: esiste prima che la conversazione inizi, la maggior parte non entra mai nella conversazione e la parte che arriva lo fa perché una descrizione ha trovato corrispondenza. Questa è la differenza tra dire a un agente come comportarsi e dargli qualcosa che può cogliere.

Un connettore riguarda il raggio d'azione. {{1}}I connettori rappresentano l'accesso alle app{{/1}}, il che significa che determinano ciò che un agente può toccare; una skill determina come l'agente dovrebbe fare qualcosa una volta che può toccarlo. {{2}}Un team può disporre di connettori eccellenti e produrre comunque documenti incoerenti{{/2}}, perché l'accesso non è procedura. Può anche disporre di skill eccellenti e comunque non vedere i dati, perché la procedura non è accesso.

La documentazione di Anthropic tratta le Skills e il Model Context Protocol come livelli diversi, e il meccanismo a tre livelli mostra perché la separazione è netta. L'ordine di caricamento riguarda quando arrivano le informazioni, non da dove provengono.

Dove si inserisce la donazione, in un paragrafo

Il 22 ottobre 2026, Anthropic ha donato lo standard Agent Skills alla Agentic AI Foundation sotto la Linux Foundation — il nome, il logo, l'organizzazione GitHub e il dominio agentskills.io — con ingegneri di Anthropic, Google, OpenAI e altre aziende che lo mantengono a titolo individuale. Niente di tutto ciò altera il meccanismo sopra. Il formato delle cartelle, il frontmatter YAML, l'ordine di caricamento e le skill documentali predefinite sono esattamente come erano il giorno prima. Ciò che è cambiato è chi possiede il nome, il che conta moltissimo per la stabilità a lungo termine di uno standard e per nulla per come si scrive una skill questo pomeriggio.

Leggere una skill prima di installarla

Se i tre livelli sono l’architettura, costituiscono anche una breve checklist di revisione. Leggi prima la descrizione, perché è ciò che stabilisce se qualcos’altro accadrà mai: dovrebbe indicare cosa fa la skill e quando usarla, con parole che una richiesta userebbe verosimilmente. Leggi SKILL.md per secondo, perché è la procedura che l’agente seguirà, e dovrebbe leggersi come istruzioni a un collega competente anziché come un riassunto di ciò che speri accada. Leggi per terzo ciò a cui fa riferimento. Poi leggi gli script.

Quell'ultimo elemento non è paranoia. Il formato consente a una skill di trasportare istruzioni insieme a risorse opzionali, e le risorse possono includere codice eseguibile. Una skill che installi non è quindi solo testo che plasma una conversazione; è una cartella da cui un agente capace aprirà file e su cui agirà. Il modello livello per livello ti dice esattamente dove guardare, il che è più di quanto offrano la maggior parte delle cose installate.

Un confine vale la pena dichiararlo per i lettori che arrivano dalle nostre stesse pagine. OrcaRouter instrada le chiamate ai modelli e non ospitiamo nessuna delle app di Anthropic né le sue superfici delle skill — una skill viene eseguita ovunque si trovi il filesystem dell'agente, e quello non è il nostro livello. Ciò che facciamo si colloca sotto la scelta del modello: più di 200 modelli dietro un'unica chiave compatibile OpenAI, il prezzo di listino del provider passato senza ricarichi e failover automatico tra provider quando uno non è disponibile. Una skill decide come dovrebbe essere svolto un compito. Un router decide quale modello lo svolge, e nessuno dei due livelli dovrebbe avere bisogno di sapere molto dell'altro.

La divulgazione progressiva è onesta riguardo al vincolo che risolve. Il contesto è finito, le procedure sono lunghe e la maggior parte di una data procedura è irrilevante per il compito che si ha davanti. Un nome, un corpo e un insieme di file non sono un progetto complicato; sono il più piccolo che consente a un agente di portare con sé una grande quantità di conoscenza tenendo solo la parte di cui ha bisogno.

Ecco perché la riga più importante in una skill ben costruita è anche la più breve. Tutto il resto nella cartella è una biblioteca. La descrizione è il catalogo a schede, e quando il catalogo è sbagliato, è come se la biblioteca non esistesse.