Cos’è una skill e come si scrive un file SKILL.md?

Cos’è una skill e in che cosa è diversa dal file delle regole?

Secondo la definizione dello standard aperto, una skill è una cartella che contiene un file SKILL.md. Il file inizia con almeno un nome (name) e una descrizione (description), seguiti dalle istruzioni che spiegano all’agente come svolgere un compito. Nella cartella possono esserci anche script, documenti di riferimento e template.

Il formato è stato sviluppato da Anthropic. Claude Code ha introdotto il supporto alle skill il 16 ottobre 2025, con la versione 2.0.20; Anthropic ha pubblicato il formato come standard aperto il 18 dicembre 2025. Al 18 ottobre 2026, le pagine sulle skill di Claude Code, Codex, Cursor, Gemini CLI e Copilot dicono di basarsi su questo standard. L’elenco dello standard stesso conta 46 prodotti; il sito dello standard dice che l’elenco mostra solo una parte dei prodotti che lo supportano. Il 18 giugno 2026 Google ha sostituito Gemini CLI con Antigravity CLI per gli utenti gratuiti e gli abbonati a Google AI Pro e Ultra; Gemini CLI resta disponibile con una licenza aziendale o una chiave API a pagamento. Anche Antigravity legge le skill e cerca le skill del progetto in .agents/skills.

La differenza rispetto al file delle regole (AGENTS.md, CLAUDE.md, GEMINI.md) sta nel momento in cui viene letto. Il file delle regole viene letto per intero in ogni sessione. Le istruzioni di una skill, invece, vengono caricate solo quando il compito corrisponde. Gli strumenti lo dicono con parole loro:

• Claude Code: a differenza di CLAUDE.md, il corpo di una skill viene caricato solo quando la skill viene usata. Per questo un lungo testo di riferimento non occupa quasi spazio finché non serve.
• Gemini CLI: i file di contesto come GEMINI.md danno all’area di lavoro uno sfondo costante; una skill è una competenza che si apre quando serve.
• Codex: AGENTS.md definisce il comportamento dell’agente, le skill impacchettano processi che si ripetono.
• Copilot: le istruzioni semplici, valide per quasi ogni compito, vanno nelle custom instructions; quelle dettagliate, da leggere solo quando servono, vanno in una skill.

Anche i vecchi formati stanno passando alle skill. In Claude Code i comandi sotto .claude/commands/ sono stati uniti alle skill. Codex ha deprecato i custom prompt e consiglia al loro posto le skill. Cursor offre una skill /migrate-to-skills che trasforma regole e comandi slash in skill.

Abbiamo parlato dei file delle regole nel nostro articolo su AGENTS.md e CLAUDE.md, dei comandi che girano ogni volta nel nostro articolo sugli hook e degli assistenti che lavorano in un contesto separato nel nostro articolo sui subagenti. Questo articolo racconta lo strato che sta in mezzo: le istruzioni che l’agente apre solo quando gli servono.

Quando l’agente legge una skill?

Lo standard la chiama divulgazione progressiva (progressive disclosure). L’agente non legge una skill tutta in una volta; la legge un pezzo alla volta, man mano che il compito lo richiede:

Il primo passo si paga in ogni sessione, anche se la skill non viene mai usata. Per questo conta quante skill installi. Due strumenti dicono quanto spazio riceve questo elenco:

• Claude Code riserva all’elenco l’1% della finestra di contesto del modello. Se l’elenco non ci sta, toglie le descrizioni delle skill che usi meno. Inoltre ogni descrizione viene tagliata nell’elenco a 1.536 caratteri.
• Codex riserva all’elenco al massimo il 2% della finestra di contesto, o 8.000 caratteri se non conosce la finestra. Con skills.max_context_tokens puoi alzare questa quota fino a un massimo di 10.000 token. Se le skill installate sono molte, Codex accorcia prima le descrizioni.
• Cursor, Gemini CLI e Copilot: la documentazione non lo dice.

Una volta aperta, anche la skill occupa spazio. In Claude Code il contenuto di una skill invocata entra nella conversazione come un unico messaggio e ci resta nei turni successivi. Quando la conversazione viene compattata, di ogni skill vengono riaggiunti solo i primi 5.000 token. Per questo scrivi l’istruzione più importante all’inizio del file.

Dove si mettono le skill nei cinque strumenti?

Lo standard definisce che cosa va dentro una cartella di skill, ma non dove si trova la cartella. La sua guida per chi sviluppa strumenti lo dice chiaramente e presenta .agents/skills come la cartella comune che si sta diffondendo tra gli strumenti. Ecco che cosa diceva la documentazione dei cinque strumenti il 18 ottobre 2026:

Fonte: la documentazione sulle skill di ogni strumento, 18 ottobre 2026. In queste cartelle ogni skill sta in una sottocartella propria: .agents/skills/<nome>/SKILL.md. Cursor legge le cartelle di Claude Code e di Codex per compatibilità. Le cartelle personali di Copilot vengono dalla documentazione della CLI; quella di VS Code aggiunge anche ~/.claude/skills. «La documentazione non lo dice»: nelle pagine che abbiamo letto quel giorno non abbiamo trovato una frase che ne parli.

Nessuna cartella compare nella documentazione di tutti e cinque gli strumenti. Quattro strumenti leggono .agents/skills; la documentazione di Claude Code cita solo .claude/skills e non dice nulla di .agents/skills. Oltre a Claude Code, leggono .claude/skills anche Cursor e Copilot; la documentazione di Codex e quella di Gemini CLI non citano questa cartella. Che una cartella non compaia nella documentazione non vuol dire che lo strumento non la legga. Ma se ti basi sulla documentazione, nessuna cartella da sola ti garantisce che una skill si apra in tutti e cinque gli strumenti.

Gli strumenti si comportano diversamente anche quando due skill hanno lo stesso nome. La guida dello standard presenta come convenzione comune a tutti gli strumenti che la skill del progetto prevalga su quella personale, e la documentazione di Gemini CLI e quella di Copilot CLI la seguono. Nella documentazione di Claude Code l’ordine è inverso: la skill personale prevale su quella del progetto. Codex non unisce le due skill e le mostra entrambe nell’elenco.

Anche le sottocartelle vengono lette in modo diverso. Claude Code e Codex leggono ogni cartella skills dalla cartella in cui hai avviato la sessione fino alla radice del repository. Cursor trova ogni cartella .cursor/skills o .agents/skills dentro il repository e propone le skill che contiene solo mentre lavori con file di quella cartella. Gemini CLI guarda solo un livello sotto la cartella skills: .gemini/skills/<nome>/SKILL.md viene trovato, ciò che sta più in profondità no.

Come si usa la stessa skill in tutti e cinque gli strumenti?

Se le tue skill stanno in .agents/skills, Codex, Cursor, Gemini CLI e Copilot le leggono; per Claude Code serve un passo in più. La strada più breve supportata dalla documentazione è questa: scrivi la skill in .agents/skills/<nome>/ e fai puntare .claude/skills/<nome> verso di essa con un symlink.

mkdir -p .claude/skills
# la skill sta in .agents/skills/riepilogo-pr/SKILL.md
ln -s ../../.agents/skills/riepilogo-pr .claude/skills/riepilogo-pr
git add .claude/skills/riepilogo-pr

La documentazione di Claude Code dice che una cartella di skill (.claude/skills/<nome>) può essere un symlink a una cartella che si trova altrove. Anche se più posizioni puntano allo stesso target, Claude Code carica la skill una volta sola. Trasformare l’intera cartella .claude/skills in un unico symlink, invece, non è citato: la documentazione descrive un collegamento per skill. Se colleghi nella direzione opposta, anche la documentazione di Codex dice che Codex segue il target delle cartelle di skill collegate con symlink.

Se qualcuno del tuo team lavora su Windows, fai attenzione a una cosa. Secondo la documentazione di Git, con core.symlinks disattivato un symlink viene creato come un piccolo file di testo che contiene il percorso del collegamento. E git clone disattiva da solo questa impostazione se il file system non supporta i symlink. Verifica a parte che il collegamento funzioni sulla sua macchina.

Abbiamo anche guardato che cosa fanno i repository popolari. Per l’articolo su AGENTS.md avevamo analizzato il 13 ottobre 2026 i 100 repository con più stelle; questa volta abbiamo cercato SKILL.md negli stessi alberi di file. Dei 98 repository di cui abbiamo potuto leggere l’albero per intero, 41 contengono almeno uno SKILL.md. Di questi, 21 tengono le loro skill in una cartella di strumento nella radice:

La cartella più diffusa è .agents/skills, quella che leggono quattro strumenti. 7 repository collegano le due cartelle con un symlink. In 5 di questi .claude/skills punta a .agents/skills; in 1 è il contrario, .agents/skills punta a .claude/skills; e in 1 .claude/skills punta a .github/skills, la cartella di Copilot. vercel/next.js e flutter/flutter collegano l’intera cartella .claude/skills. langgenius/dify invece collega ogni skill separatamente, cioè nel modo descritto dalla documentazione di Claude Code.

Che cosa si scrive all’inizio di uno SKILL.md?

Uno SKILL.md è fatto di due parti: in cima, YAML tra due righe --- (il frontmatter), e sotto, istruzioni in Markdown. Lo standard definisce sei campi per il frontmatter:

Fonte: la specifica Agent Skills, 18 ottobre 2026.

Gli strumenti non applicano queste regole con lo stesso rigore:

• In Claude Code tutti i campi sono facoltativi; è consigliato solo description. Se manca name, si usa il nome della cartella. Un campo che non riconosce viene ignorato senza errori.
• Codex, Cursor, Gemini CLI e Copilot richiedono name e description.
• Gemini CLI salta il file senza avvisare se manca uno dei due campi o se c’è qualcosa prima della prima riga --- (un titolo, un commento, perfino una riga vuota). Inoltre prende il nome della skill dal campo name, non dalla cartella; lo standard e Cursor, invece, richiedono che il nome sia uguale a quello della cartella.
• Copilot CLI ammette nel nome anche maiuscole, spazi, trattini bassi, punti e due punti. Lo standard accetta solo lettere minuscole, cifre e trattini.

Le regole sui tag XML non sono dello standard, ma di Anthropic. Secondo le sue regole per claude.ai e l’API, name e description non possono contenere tag XML, e name non può contenere le parole «anthropic» e «claude». I campi propri di Claude Code (come when_to_use, context e hooks) funzionano in Claude Code. Ma se carichi la stessa skill su claude.ai o nella Skills API, qualsiasi campo fuori dallo standard blocca il caricamento: Unexpected key(s) in SKILL.md frontmatter.

Se userai una skill in più strumenti, parti solo dai campi dello standard. L’esempio qui sotto usa solo i due campi obbligatori e rispetta le regole sui campi della documentazione di tutti e cinque gli strumenti:

Per decidere che cosa scrivere nel corpo, fai a ogni riga la domanda della guida dello standard: senza questa istruzione l’agente sbaglierebbe il compito? Se la risposta è no, cancella la riga. Sposta i testi di riferimento lunghi in references/ e collegali direttamente da SKILL.md. Sia lo standard sia la guida di Anthropic consigliano di tenere i file di riferimento a un solo livello da SKILL.md.

Che cosa si scrive nella descrizione?

Prima di scegliere una skill, l’agente ne vede solo la descrizione. La guida dello standard lo dice chiaramente: «the description carries the entire burden of triggering.» La documentazione degli strumenti dice lo stesso: Claude Code, Codex, Cursor e Copilot scelgono una skill in base alla descrizione. Anche secondo la guida di Gemini CLI la descrizione è l’unica informazione che il modello ha prima di aprire la skill.

• Scrivi che cosa fa e quando usarla. Lo standard, Claude Code, Cursor e Copilot chiedono le due cose insieme. Una descrizione come «Helps with PDFs.» non dice nulla all’agente; è il cattivo esempio dello standard stesso.
• Usa le parole che direbbero i tuoi utenti. L’elenco per la risoluzione dei problemi di Claude Code comincia proprio da qui: la descrizione contiene le parole chiave che gli utenti direbbero in modo naturale?
• Metti all’inizio la parte importante. Quando l’elenco non ci sta, le descrizioni vengono accorciate. Claude Code taglia ogni descrizione nell’elenco a 1.536 caratteri. Codex, se le skill installate sono molte, accorcia prima le descrizioni; per questo la sua documentazione consiglia di mettere all’inizio il caso d’uso e le parole che la attivano.
• Distinguila dalle skill simili. La guida di Gemini CLI vuole descrizioni distinte tra loro e da ciò che il modello sa già fare.

Le guide non sono d’accordo sulla persona. La guida di Anthropic chiede la terza persona e scrive che le descrizioni che iniziano con «I can help you…» o «You can use this…» possono rendere più difficile trovare la skill. La guida di agentskills.io, invece, consiglia di scrivere la descrizione come un’istruzione data all’agente, con lo schema «Use this skill when…». Gli esempi di entrambe le guide seguono la stessa strada: prima che cosa fa la skill, poi, con «Use when…», quando usarla. Anche l’esempio qui sopra è scritto così.

Nemmeno una buona descrizione garantisce che la skill si apra ogni volta. Secondo la guida dello standard, gli agenti ricorrono alle skill soprattutto per i compiti che non sanno svolgere da soli. Una richiesta di un solo passo come «leggi questo PDF» può non aprire una skill per i PDF anche se la descrizione corrisponde perfettamente. Per Copilot, anche la documentazione di VS Code dice che la scoperta non garantisce che la skill venga invocata per ogni prompt pertinente.

La skill la chiami tu o la sceglie l’agente?

Entrambe le cose. In tutti e cinque gli strumenti l’agente può aprire da solo una skill che ritiene adatta al compito. Chiamarla a mano, e impedire all’agente di sceglierla da solo, dipende dallo strumento:

Fonte: la documentazione sulle skill di ogni strumento, 18 ottobre 2026. In Claude Code e Copilot user-invocable: false fa il contrario: solo l’agente può aprire la skill.

Disattiva la scelta dell’agente per i compiti con effetti collaterali. La documentazione di Claude Code lo dice così: «You don't want Claude deciding to deploy because your code looks ready.» Le skill che fanno deploy o commit, o che inviano messaggi, sono di questo tipo. Con questa impostazione Claude Code non mette affatto la descrizione della skill nel contesto, quindi non occupa nemmeno spazio nell’elenco. Un esempio di skill chiamata a mano, che trasforma una richiesta di review nel comando /revisione, lo trovi nel nostro articolo sul prompt per la code review.

In Gemini CLI è diverso: solo l’agente può chiamare activate_skill, lo strumento che apre una skill; tu no. In compenso, l’agente ti chiede il consenso ogni volta che apre una skill.

Come si capisce se una skill funziona?

La documentazione di Claude Code comincia con un avvertimento: «Seeing a skill trigger tells you Claude found it, not that it did what you intended.» Che una skill si apra e che faccia bene il lavoro sono due domande separate, e ognuna si misura per conto suo.

Entrambe si misurano con un confronto. Raccogli qualche prompt realistico; esegui ciascuno in una sessione nuova, una volta con la skill attiva e una volta con la skill disattivata, e metti i risultati uno accanto all’altro. La sessione nuova è indispensabile, perché il contesto accumulato mentre scrivevi la skill nasconde le lacune delle istruzioni.

Per misurare quanto spesso si apre una skill, la guida di agentskills.io dà una ricetta concreta:

• Scrivi circa 20 prompt: metà dovrebbe aprire la skill, metà no.
• Prendi quelli che non dovrebbero aprirla da compiti simili. I prompt che usano le stesse parole ma chiedono altro mostrano meglio di tutti quanto è precisa la descrizione.
• Il modello non prende sempre la stessa decisione. Esegui ogni prompt più volte (3 è un buon inizio) e calcola il tasso di apertura.
• Come soglia, 0,5 è ragionevole: per i prompt che dovrebbero aprire la skill il tasso deve stare sopra, per gli altri sotto.

Per questo un solo tentativo non conta come risultato. È normale che lo stesso prompt apra la skill in un’esecuzione e non nella successiva; quando cambi una descrizione, riesegui gli stessi prompt lo stesso numero di volte.

Che cosa controllare prima di installare la skill di qualcun altro?

Una skill non è solo testo: può eseguire script, permettere che alcuni strumenti vengano usati senza chiedere e guidare l’agente con le sue istruzioni. La documentazione di Anthropic scrive che una skill malevola può portare l’agente a chiamare strumenti o eseguire codice in modi che non corrispondono allo scopo dichiarato, e consiglia di usare skill solo da fonti di cui ti fidi.

Gli strumenti trattano la fiducia in modo diverso:

• Claude Code applica il campo allowed-tools di una skill di progetto perfino in un’esecuzione -p in una cartella di cui non ti sei mai fidato. Per questo la sua documentazione chiede di leggere questo campo nelle skill presenti in un repository prima di avviare lì Claude Code. Il campo non limita gli strumenti; fa usare senza chiedere quelli elencati durante il turno in cui la skill viene invocata.
• Copilot scrive che le skill installate con gh skill non sono verificate da GitHub e possono contenere prompt injection, istruzioni nascoste o script malevoli. Consiglia di guardarle con gh skill preview prima di installarle.
• Gemini CLI ti fa confermare l’origine quando installi da un indirizzo remoto e chiede il permesso ogni volta che apre una skill. Inoltre carica le skill di progetto in .gemini/skills solo se la cartella di lavoro è segnata come attendibile.
• Codex e Cursor non hanno regole sulla fiducia nelle loro pagine sulle skill: la documentazione non lo dice.

Anche la guida dello standard per chi sviluppa strumenti consiglia di caricare le skill di progetto solo in cartelle segnate come attendibili. Un repository che hai appena clonato può aggiungere istruzioni al contesto dell’agente senza che tu te ne accorga.

Quando usare una skill e quando AGENTS.md?

Una cosa non sostituisce l’altra, e i repository popolari le usano entrambe. Dei 41 repository analizzati che contengono uno SKILL.md, 35 hanno nella radice anche un AGENTS.md o un CLAUDE.md.

Tutto dipende da quando serve l’informazione. Ciò che vale per ogni compito (la struttura del progetto, i comandi di build, regole come «non fare mai questo») va nel file delle regole; un flusso di lavoro che serve ogni tanto, o un lungo testo di riferimento, va in una skill. Il criterio della documentazione di Claude Code funziona bene: se una sezione di CLAUDE.md da informazione è diventata una procedura, trasformala in una skill.

Vercel ha messo alla prova questa domanda con i propri test in un articolo del 27 gennaio 2026. Nei test costruiti sulle API di Next.js 16, la skill non è mai stata invocata nel 56% dei casi. Un indice della documentazione di 8 KB inserito direttamente in AGENTS.md ha raggiunto il 100% di successo; il risultato migliore della skill è stato il 79%. È la misura di un solo team su un solo argomento, e l’articolo non dice su quanti compiti è stata fatta. Neanche la conclusione di Vercel è «o l’uno o l’altro»: «The two approaches complement each other.» Secondo l’articolo, i flussi di lavoro specifici che l’utente avvia esplicitamente funzionano meglio come skill.

Anche una regola da rispettare in ogni pull request è compito del file delle regole. Quando diffox esamina una pull request, legge l’AGENTS.md nella radice del repository, o in sua assenza il CLAUDE.md, e usa le regole che contiene come regole di review. Se vuoi che una regola valga in ogni review, scrivila nel file delle regole.