Hai usato Claude per una settimana e continui a digitare sempre le stesse cose. Ogni volta che fai un commit di codice, incolli le stesse tre regole sul formato del commit. Ogni volta che scrivi un documento, rispieghi il tuo stile. Claude lo fa bene, poi se ne dimentica appena la chat finisce, e domani riscrivi tutto da capo.
Una skill risolve tutto questo. È una piccola cartella che scrivi una volta sola e insegna a Claude un flusso di lavoro in modo permanente, così lo applica a ogni sessione senza che tu glielo chieda.
Ecco come funziona, in sintesi: una skill è una cartella con un file all'interno. Claude tiene sempre visibile un riepilogo di una riga, e carica le istruzioni complete solo quando la tua richiesta corrisponde. Questo è tutto il meccanismo.
In questa guida costruiamo una skill reale partendo da zero: commit-messages, che scrive commit git nel tuo formato esatto. Se hai Claude installato e nient'altro, puoi seguire ogni passaggio.
Cosa otterrai alla fine
Alla base, una skill è una cartella con un file obbligatorio, SKILL.md. Tre cartelle opzionali si aggiungono man mano che la skill cresce:
1your-skill-name/2├── SKILL.md # Obbligatorio - il file principale della skill3├── scripts/ # Opzionale - codice eseguibile4├── references/ # Opzionale - documentazione5└── assets/ # Opzionale - template, ecc.
SKILL.md stesso ha due parti: un'intestazione breve che dice a Claude quando usare la skill, e istruzioni sottostanti che dicono a Claude cosa fare. Il motivo di questa suddivisione è importante. Claude legge costantemente l'intestazione, quindi sa sempre che la skill esiste, ma carica le istruzioni solo quando la tua richiesta corrisponde. Tieni a mente questa distinzione, perché quasi tutto il resto di questa guida ne deriva.
Creala
Le skill vivono in una cartella chiamata .claude/skills nella tua home directory, che sia Claude Code che l'app desktop leggono. È nascosta e probabilmente non esiste ancora, quindi il modo più veloce per crearla, insieme alla cartella della tua skill, è un singolo comando.
Su Mac, apri Terminale ed esegui:
1mkdir -p ~/.claude/skills/your-skill-name
Su Windows, apri PowerShell ed esegui:
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"
Il nome della cartella non è solo estetico. Claude lo usa come identificatore della skill, e una regola di formattazione fa inciampare le persone più di ogni altra:
- Usa kebab-case: notion-project-setup ✔
- Niente spazi: Notion Project Setup ✖
- Niente underscore: notion_project_setup ✖
- Niente maiuscole: NotionProjectSetup ✖
All'interno di quella cartella, crea un file chiamato esattamente SKILL.md e aprilo con un qualsiasi editor di testo. Da qui in poi, tutto va inserito in quel file.
Progettala prima di scriverla
Le skill che funzionano iniziano con due decisioni, prese prima di scrivere una riga del file. Entrambe sembrano evitabili, ma nessuna lo è.
Primo, decidi esattamente quando la skill dovrebbe attivarsi. Scrivi due o tre situazioni reali con le parole che un utente digiterebbe effettivamente:
- "fai il commit di queste modifiche"
- "scrivi un messaggio di commit per questo diff"
- "staging e commit"
Non è un lavoro inutile. Queste frasi diventano la materia prima per la tua descrizione e per i tuoi test successivi, e una skill progettata senza di esse tende a essere vaga proprio nel modo che le impedisce di attivarsi.
Secondo, decidi come capirai che funziona. Il criterio più importante di tutti è se la skill si carica da sola, senza che tu la nomini. Se devi invocarla manualmente ogni volta, la skill tecnicamente viene eseguita ma ha fallito nel suo compito reale. Vale la pena osservare anche questo: se completa l'attività senza che tu la corregga a metà, e se ti dà lo stesso tipo di risultato in sessioni diverse.
La descrizione è ciò che la fa funzionare o la distrugge
Di tutto ciò che c'è nel file, la descrizione nell'intestazione fa il lavoro più pesante, perché è l'unica parte che Claude legge quando decide se caricare o meno la skill. Le tue istruzioni potrebbero essere impeccabili, ma non avrebbe importanza, perché Claude non le raggiunge mai se la descrizione non corrisponde. È qui che la maggior parte delle skill che "non funzionano" fallisce.
Una buona descrizione risponde a due domande in una frase: cosa fa la skill e quando Claude dovrebbe usarla. La seconda metà è quella che le persone tralasciano.
Ecco la differenza:
1# debole - dice cos'è, non dà a Claude nulla con cui confrontare una richiesta2description: Aiuta con i commit git.34# forte - indica i momenti in cui dovrebbe attivarsi5description: Scrive messaggi di commit git nel formato Conventional Commits. Usala quando l'utente chiede di fare commit, scrivere un messaggio di commit o fare staging e commit dei file.
La versione debole dice a Claude che la skill esiste ma non la collega mai a nulla che potresti dire. La versione forte indica le frasi reali, così quando digiterai "fai il commit di queste modifiche", Claude avrà qualcosa con cui confrontarsi. Cita le parole che un utente userebbe davvero, mantieni il tutto sotto i 1024 caratteri e non inserire < o > al suo interno.
Quando una skill non si attiva, la soluzione è quasi sempre qui. Aggiungi le formulazioni che usi effettivamente. Se dici "salva il mio lavoro" ma la descrizione menziona solo "commit", Claude non ha modo di collegare le due cose. E se invece accade il contrario e la skill si attiva quando non dovrebbe, restringi la descrizione o aggiungi un trigger negativo:
1description: Scrive messaggi di commit git nel formato Conventional Commits. Usala quando si fanno commit. Non usarla per scrivere commenti nel codice o documentazione.
C'è un modo rapido per verificare il tuo lavoro prima di affidartici. Chiedi direttamente a Claude:
"Quando useresti la skill commit-messages?"
Claude ti leggerà la tua descrizione con le sue parole. Se non corrisponde a quando vuoi effettivamente che la skill si attivi, hai trovato il problema, ed è nella descrizione, non nelle istruzioni sottostanti.
Scrivi istruzioni che Claude segua davvero
Sotto l'intestazione arriva il corpo, in plain Markdown. È qui che vive il tuo vero flusso di lavoro, e due abitudini separano le istruzioni che Claude segue da quelle che ignora silenziosamente.
La prima è essere specifici. Claude agisce su istruzioni concrete e sorvola su quelle vaghe, quindi più sei preciso, più affidabile sarà il suo comportamento:
1# Male2Convalida il commit prima di finalizzare.34# Bene5Esegui `python scripts/validate.py "<message>"`.6Se fallisce, correggi questi:7- Tipo non valido: usa feat, fix, docs, refactor, test, chore8- Riepilogo oltre 60 caratteri: accorcialo
La seconda è l'ordine. Claude dà peso a ciò che legge per primo, quindi una regola sepolta in fondo a un file lungo è una regola che viene ignorata. Metti tutto ciò che non deve essere infranto all'inizio, sotto un'intestazione che lo segnali:
1## Importante2- Riga di riepilogo sempre sotto i 60 caratteri3- Solo tempo presente: "add", non "added"
C'è anche un limite a ciò che il linguaggio può garantire. Le istruzioni vengono interpretate, il che significa che Claude le segue bene ma non in modo identico ogni volta. Quando un controllo deve assolutamente passare a ogni esecuzione, non descriverlo a parole, spostalo in uno script e fai in modo che le istruzioni lo eseguano. Il codice fa la stessa cosa ogni volta; una frase no. (Ecco a cosa serve la cartella scripts/, trattata in seguito.)
Una struttura che regge sulla maggior parte delle skill è questa:
1# Nome Skill23## Importante4Regole critiche che non devono essere trascurate.56## Istruzioni7Passo dopo passo, specifiche e attuabili.89## Esempi10Input e output concreti. Claude copia gli esempi in modo più affidabile di quanto segua le regole.
Mantieni il file snello. Nel momento in cui inizia a crescere oltre le istruzioni principali, è il momento di spostare i dettagli extra altrove, ed è esattamente a questo che servono le cartelle opzionali.
Script, riferimenti, asset
Finora tutto ciò che abbiamo visto produce una skill che dà istruzioni a Claude. Le tre cartelle opzionali la trasformano in una skill che dà a Claude degli strumenti, ed è qui che una skill fa cose che un semplice prompt non può fare.
scripts/ contiene codice che Claude esegue, per tutto ciò che deve essere preciso. Invece di affidarti a Claude per controllare a occhio se un commit è formattato correttamente, gli passi uno script che lo verifica:
1# scripts/validate.py2import sys3msg = sys.argv[1]4types = ("feat", "fix", "docs", "refactor", "test", "chore")56if msg.split(":")[0] not in types:7 print(f"Invalid type. Use: {', '.join(types)}")8elif len(msg.split("\n")[0]) > 60:9 print("Summary too long (over 60 chars)")10else:11 print("OK")
Poi dici a Claude di usarlo in SKILL.md:
1Prima di finalizzare, esegui `python scripts/validate.py "<message>"`2e correggi tutto ciò che segnala.
Ora la regola di formattazione è applicata da codice che viene eseguito sempre allo stesso modo, invece di dipendere dal fatto che Claude ricordi di controllare.
references/ contiene documentazione che viene caricata solo quando necessario. Supponiamo che le tue convenzioni di commit occupino due pagine di ambiti, piè di pagina e casi limite. Se metti tutto in SKILL.md, verrà caricato a ogni singolo commit, anche per una riga sola. Spostalo invece in un file di riferimento:
1your-skill-name/2├── SKILL.md3└── references/4 └── conventions.md
E punta ad esso dal file principale:
1Per l'elenco completo delle convenzioni, vedi references/conventions.md
Claude apre quel file solo quando l'attività lo richiede. Questo è il motivo principale per cui le skill rimangono economiche da eseguire: i dettagli pesanti restano su disco fino a quando non sono effettivamente rilevanti, invece di essere trasportati nel contesto ogni volta.
assets/ contiene file che la skill usa nel suo output anziché leggere per orientamento, come un template, un file di configurazione o un logo. Una skill per commit non ne ha bisogno, ma una skill che genera report potrebbe tenere un template.md qui e compilarlo ogni volta, in modo che ogni report esca con la stessa struttura.
Nel loro insieme, queste tre cartelle sono la differenza tra una skill che dice a Claude come lavori e una che dà a Claude gli strumenti esatti per fare il lavoro a modo tuo.
L'unica cosa da ricordare
Una skill non insegna a Claude una nuova abilità. Lui sa già come scrivere un commit. Quello che fa la skill è fargli fare il lavoro a modo tuo, ogni volta, senza che tu lo spieghi di nuovo.
E quando una skill non funziona, la causa non è quasi mai nelle istruzioni su cui hai faticato. È nella descrizione. Claude decide se caricare la skill da quella singola riga, prima ancora di leggere il lavoro sottostante. Metti a posto la descrizione e tutto ciò che c'è sotto verrà finalmente utilizzato.
Se questo è stato utile, vai sul mio profilo e seguimi. Scrivo di tecnologia, AI e sistemi che funzionano davvero.
