Creare una skill per Claude: come si scrive
Questa guida è per Claude Code. Una skill è una cartella con dentro un file. La parte che decide se funziona o no non sono le istruzioni: è la descrizione, perché è l'unica cosa che Claude ha sempre davanti — tutto il resto lo apre solo se quella combacia. Una descrizione vaga produce una skill scritta benissimo che non si attiva mai.
Fabrizio Piccoscritta il 20 settembre 2026 · si legge in 12 minuti
Scrivere una skill è facile: una cartella, un file, due righe di intestazione. Farla partire quando serve è la parte difficile, ed è quella su cui si arenano molte skill fatte in casa. Il motivo è nel modo in cui Claude le tiene in memoria.
Come Claude tiene le skill in memoria
Va capito prima di scrivere una riga, perché spiega tutto il resto. Le skill non vengono caricate tutte insieme: entrano a strati.
- Il primo strato è sempre presente: nome e descrizione di ogni skill installata. Costa poco, ma non è gratis: ogni skill in elenco occupa un po' di contesto a ogni turno, quindi conviene tenere installate solo quelle che usi.
- Il secondo strato si apre solo quando serve: quando quello che chiedi combacia con la descrizione di una skill, Claude va a leggere il file delle istruzioni. Prima di quel momento, quel file per Claude non esiste.
- Il terzo strato sono gli allegati — altri documenti, tabelle di riferimento, programmi — che si aprono uno per uno solo se le istruzioni li richiamano. Un programma allegato, in più, viene eseguito senza che il suo contenuto occupi memoria: entra solo il risultato.
- La conseguenza pratica è tutta qui: puoi allegare quanto vuoi senza costi, ma se la descrizione non combacia, niente di tutto quel materiale viene mai aperto. È il motivo per cui la descrizione conta più di tutto il resto messo insieme.
Il file, campo per campo
Una skill è una cartella con dentro un file che si chiama SKILL.md. Tutto il resto è facoltativo.
- Dove si mette la cartella (in Claude Code): in
~/.claude/skills/per averla in tutti i progetti, oppure in.claude/skills/dentro un progetto per averla solo lì. Il nome della cartella è il nome della skill. - Il file comincia con un'intestazione fra due righe di tre trattini, con i campi
nameedescription. In Claude Code il nome, se manca, è quello della cartella, e la descrizione è consigliata; sulle API e su claude.ai sono obbligatori tutti e due. Scrivili sempre entrambi. - Il nome può essere lungo al massimo 64 caratteri e può contenere solo lettere minuscole, numeri e trattini. Niente spazi, niente accenti, niente maiuscole.
- Una regola documentata da tenere a mente: la documentazione di Anthropic vieta di usare nel nome le parole «claude» e «anthropic». Nessuno la rilegge per un nome, quindi il modo più sicuro è evitarle: invece di
claude-fatture, chiamalafatture. - La descrizione ha un limite (1.024 caratteri nella specifica, 200 su claude.ai; in Claude Code viene tagliata intorno ai 1.500 insieme al resto). Non è un titolo: è il campo più importante del file, e la sezione qui sotto spiega perché. Metti per prima la cosa più importante.
- Sotto le due righe va il testo libero: le istruzioni vere e proprie, scritte come le scriveresti a una persona nuova. Passaggi, esempi, cose da non fare.
- Tieni quel testo corto — la documentazione dice sotto le 500 righe — e sposta il materiale lungo in file separati accanto, richiamandoli dal testo. Così si aprono solo quando servono davvero.
La descrizione: dove si vince o si perde
Se leggi una cosa sola di questa guida, leggi questa. La descrizione deve dire due cose, e spesso se ne scrive una sola.
| Descrizione | Cosa succede |
|---|---|
| «Aiuta con le fatture» | non si attiva quasi mai: non dice quando |
| «Crea e controlla fatture elettroniche in XML. Da usare quando si parla di fatture, fatturazione elettronica, SDI o partita IVA.» | si attiva al momento giusto |
| «Utilità per documenti» | troppo generica: si attiva a sproposito |
| «Gestisce il progetto» | non dice né cosa fa né quando serve |
- Prima cosa: cosa fa la skill. In modo concreto, non astratto: «genera fatture in XML» e non «gestisce la fatturazione».
- Seconda cosa, ed è quella che manca sempre: QUANDO va usata. Claude confronta quello che gli chiedi con questa frase: se lì non ci sono le parole che una persona userebbe per chiedere quella cosa, non scatta niente.
- Il trucco pratico: scrivi nella descrizione le parole vere che useresti tu per chiedere quel lavoro, comprese le sigle e i modi informali. Se dici «fammi la fattura elettronica», nella descrizione ci devono stare «fattura elettronica».
- Come si collauda in due minuti: apri una conversazione nuova e chiedi la cosa nel modo in cui la chiederesti normalmente, senza nominare la skill. Se non si attiva, il problema è la descrizione — non le istruzioni, che non sono nemmeno state lette.
- Il difetto opposto esiste ed è fastidioso: una descrizione troppo vaga («documenti», «file», «progetto») fa scattare la skill quando non c'entra niente. Va stretta, non allargata: meglio due skill precise che una che prova a fare tutto.
Gli errori che la rendono inutile
Cinque errori comuni, più una regola di sicurezza.
- La descrizione dice cosa fa ma non quando serve. È l'errore più comune e produce una skill perfetta che non parte mai.
- Istruzioni lunghissime dentro SKILL.md. Tutto quel testo entra in memoria ogni volta che la skill si attiva. Il materiale di consultazione va in file accanto, richiamati per nome.
- Istruzioni scritte come una descrizione invece che come una procedura. «Questa skill gestisce le fatture» non serve a niente: serve «per fare una fattura: 1) chiedi il codice cliente, 2) controlla che la partita IVA sia valida, 3)...».
- Nessun esempio. Un esempio concreto di ingresso e di risultato vale più di dieci righe di spiegazione, perché toglie l'ambiguità.
- Il nome con dentro «claude». La documentazione lo vieta: evitalo.
- E una regola di sicurezza che vale per le skill scaricate, non per le tue: una skill è codice e istruzioni che Claude eseguirà. Anthropic dice di usarne solo da fonti fidate, e di leggere tutti i file prima di installarne una scaricata da internet — comprese le cose che vanno a prendersi roba da internet, che possono cambiare dopo che l'hai controllata. È lo stesso ragionamento che si fa prima di installare un programma.
Domande frequenti
Come si crea una skill per Claude?
Si fa una cartella dentro ~/.claude/skills/ (o .claude/skills/ per un solo progetto) e dentro ci si mette un file SKILL.md (è la procedura di Claude Code: su claude.ai una skill si carica invece come file compresso dalle impostazioni). Il file comincia con un'intestazione con name e description, e sotto ci vanno le istruzioni scritte in italiano normale. Per avviarla a mano si scrive /nome-della-skill.
Perché la mia skill non si attiva mai?
Quasi sempre per colpa della descrizione. Di una skill Claude tiene sempre in memoria solo quella, e apre le istruzioni solo se la descrizione combacia con quello che stai chiedendo. Se dice cosa fa la skill ma non quando va usata, di solito non scatta: il file è perfetto e non viene mai letto.
Come si scrive una buona descrizione per una skill?
Deve dire due cose: cosa fa la skill, in concreto, e quando va usata. Nella seconda parte vanno messe le parole vere che useresti tu per chiedere quel lavoro, sigle e modi informali compresi. Non serve riempire lo spazio: metti per prima la cosa più importante, perché con molte skill in Claude Code la descrizione viene tagliata oltre i 1.500 caratteri circa.
Ci sono limiti sul nome di una skill?
Sì, tre: massimo 64 caratteri, solo lettere minuscole, numeri e trattini, e — questa sta nella documentazione ufficiale, ma in fondo a un elenco — non può contenere le parole «claude» e «anthropic». Meglio fatture che claude-fatture.
Quanto deve essere lungo il file SKILL.md?
Corto: la documentazione dice sotto le 500 righe. Quel testo entra in memoria per intero ogni volta che la skill si attiva. Il materiale lungo — tabelle di riferimento, documentazione, esempi estesi — va in file separati accanto, richiamati dal testo: quelli non costano niente finché non servono.
Le skill scaricate da internet sono sicure?
Vanno trattate come un programma che stai per installare. Anthropic dice di usare solo skill di fonti fidate e di leggere tutti i file prima: una skill può far eseguire comandi e leggere file. Attenzione particolare a quelle che vanno a prendersi contenuti da internet, perché quel contenuto può cambiare dopo che l'hai controllato.
Da dove vengono questi dati
Dati controllati il 25 settembre 2026.
- Anthropic — Agent Skills, documentazione ufficiale i tre livelli di caricamento (i metadati sempre in memoria, il file SKILL.md all'attivazione, gli allegati solo se richiamati) e i vincoli: nome massimo 64 caratteri, solo minuscole numeri e trattini, vietate le parole «anthropic» e «claude»; descrizione massimo 1.024 caratteri, letto il 25 settembre 2026
- Anthropic — Come si scrive una skill, buone pratiche la descrizione deve dire cosa fa la skill E quando usarla, scritta in terza persona e con le parole che userebbe chi chiede; il limite di 500 righe per SKILL.md, letto il 21 settembre 2026
- Anthropic — Usare le skill in Claude Code le cartelle ~/.claude/skills/ (personali) e .claude/skills/ (di progetto), e il fatto che Claude Code veda le modifiche alle skill senza riavvio; per Claude Code, il nome facoltativo (di default quello della cartella), la descrizione consigliata e il tetto di circa 1.500 caratteri per descrizione e when_to_use insieme, letto il 25 settembre 2026
- Anthropic — Creare skill personalizzate (assistenza Claude) su claude.ai la skill si carica come file compresso dalle impostazioni e la descrizione ha un limite di 200 caratteri, letto il 25 settembre 2026
Questa guida l’ho scritta con l’aiuto dell’intelligenza artificiale e l’ho verificata sulle fonti qui sopra prima di pubblicarla. Come lavoro
