Computer

Creare una skill per Claude: come si scrive

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 Picco
scritta 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 quasi tutte le 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.

Cosa entra in memoria, e quandoLa descrizionesempre, fin dall’avvioquanto una frase o dueLe istruzioni (SKILL.md)solo quando la skill si attivapoche pagine di testoGli allegatisolo se servono davveronessun costo finché non si apronoSolo la descrizione è sempre presente: è con quella che Claude decidese la skill serve. Se è vaga, il resto non si apre mai.
Le istruzioni e gli allegati non costano niente finché non servono. La descrizione invece è sempre lì, ed è l’unica cosa su cui Claude può decidere.
  1. Il primo strato è sempre presente: nome e descrizione di ogni skill installata. Costa pochissimo, quindi se ne possono tenere installate tante senza rallentare niente.
  2. 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.
  3. 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.
  4. 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.

  1. Dove si mette la cartella: 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.
  2. Il file comincia con due righe fra tre trattini, e sono le uniche obbligatorie: name e description.
  3. Il nome può essere lungo al massimo 64 caratteri e può contenere solo lettere minuscole, numeri e trattini. Niente spazi, niente accenti, niente maiuscole.
  4. Attenzione a una regola documentata di cui l'errore non parla, e che fa perdere un pomeriggio: il nome non può contenere le parole «claude» e «anthropic». Sta scritta in chiaro nella documentazione, ma chi chiama la sua skill claude-fatture riceve un errore che non dice il perché — e nessuno va a rileggere la documentazione per un nome. Basta chiamarla fatture.
  5. La descrizione può arrivare a 1.024 caratteri. Non è un titolo: è il campo più importante del file, e la sezione qui sotto spiega perché.
  6. 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.
  7. 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 quasi tutti ne scrivono una sola.

DescrizioneCosa 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
  1. Prima cosa: cosa fa la skill. In modo concreto, non astratto: «genera fatture in XML» e non «gestisce la fatturazione».
  2. 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.
  3. 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».
  4. 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.
  5. 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, in ordine di quanto sono frequenti.

  1. 1. La descrizione dice cosa fa ma non quando serve. È il numero uno e produce una skill perfetta che non parte mai.
  2. 2. 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.
  3. 3. 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)...».
  4. 4. Nessun esempio. Un esempio concreto di ingresso e di risultato vale più di dieci righe di spiegazione, perché toglie l'ambiguità.
  5. 5. Il nome con dentro «claude». Vietato, e l'errore non lo spiega.
  6. 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 presa in giro — 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. Il file comincia con due righe obbligatorie — name e description — e sotto ci vanno le istruzioni scritte in italiano normale.

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, non scatta niente: 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. Può arrivare a 1.024 caratteri: usali.

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 una tabella — non può contenere le parole «claude» e «anthropic». Chiamarla claude-fatture dà un errore che non spiega il motivo.

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 20 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 21 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, letto il 21 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

Continua da qui