Claude Code Skills: cosa sono e come crearle (guida pratica in italiano)

Se usi Claude Code da qualche mese, ti sarà capitato di riscrivere le stesse istruzioni decine di volte: "segui questo stile per i commit", "quando tocchi le migration controlla anche le RLS", "i post LinkedIn vanno in questo tono, senza emoji". Ogni volta lo stesso copia-incolla nel prompt.

Le Claude Code Skills servono esattamente a questo: impacchettare una competenza — istruzioni, regole, a volte anche script — in una cartella che Claude carica da solo, quando serve. Non un altro prompt da ricordare, ma una capacità che vive nel progetto e si attiva al momento giusto.

In questa guida vediamo cosa sono davvero le skill, com'è fatto il file SKILL.md, come crearne una da zero, e — soprattutto — quando una skill è lo strumento giusto rispetto a un subagent o a un server MCP (e dove si collocano gli slash command, che ormai sono diventati skill anche loro). È la parte che genera più confusione, e quella su cui ti faccio risparmiare più tempo.

🎥 Video complementare. Questo post ti spiega cosa sono e come creare le tue skill. Se invece vuoi sapere come installarne di pronte — skill e MCP come plugin da un marketplace, come scegliere le fonti affidabili, come proteggerti dal malware, più 7 skill consigliate per sviluppare codice — guarda il video qui sotto.

Cosa sono le Claude Code Skills

Una skill è semplicemente una cartella con dentro un file SKILL.md. Quel file ha due parti: un'intestazione in formato YAML con un nome e una descrizione, e un corpo in Markdown con le istruzioni vere e proprie.

La parte che cambia tutto è come viene usata. Nel caso tipico una skill è model-invoked: non sei tu a richiamarla, è Claude che decide di usarla leggendo la sua description. Tu lavori normalmente, descrivi un task, e se quel task corrisponde a una skill disponibile, Claude la apre e ne segue le istruzioni. Senza che tu debba ricordarti che esiste.

Ma non è l'unico modo. Da un po' di tempo anche gli slash command sono diventati skill: quando digiti /nome-skill stai semplicemente invocando a mano una skill, invece di lasciare che sia Claude a sceglierla. Stessa primitiva, due modalità di attivazione — automatica o manuale. Anthropic ha unito i due concetti, e questo semplifica le cose: c'è una sola "scatola" da imparare, la skill, e tu decidi se lasciarla scattare da sola o lanciarla col comando. Ci torniamo tra poco.

Questo si appoggia a un meccanismo che vale la pena capire, perché spiega perché le skill non appesantiscono il contesto: la progressive disclosure (divulgazione progressiva).

• In ogni momento, Claude tiene in memoria solo il nome e la descrizione di ogni skill. Costa pochissimo: due righe a skill.
• Quando un task sembra rientrare in una skill, Claude carica il corpo completo del SKILL.md.
• Se la skill rimanda ad altri file (uno script, una checklist lunga, un template), quelli vengono letti solo se e quando servono.

Risultato: puoi avere venti skill installate senza pagare il prezzo di venti documenti sempre aperti nel contesto. È la differenza pratica più importante rispetto a mettere tutto dentro CLAUDE.md, che invece viene caricato per intero a ogni conversazione.

Com'è fatto un file SKILL.md

Ecco la struttura minima di una skill. Immagina una cartella commit-italiano/ con dentro un solo file, SKILL.md:

---
name: commit-italiano
description: >
  Scrive messaggi di commit in stile Conventional Commits, in italiano.
  Da usare ogni volta che si prepara un commit o si scrive un messaggio di commit.
---

# Messaggi di commit

Quando scrivi un messaggio di commit per questo progetto:

- Usa il formato Conventional Commits: `tipo(scope): descrizione`.
- Tipi ammessi: feat, fix, refactor, docs, chore, test.
- La descrizione è in **italiano**, minuscola, all'imperativo presente
  ("aggiungi", non "aggiunto").
- Massimo 72 caratteri sulla prima riga.
- Se il cambiamento non è banale, aggiungi un corpo che spiega il *perché*,
  non il *cosa*.

Due campi contano davvero nell'intestazione:

• name — un identificatore breve, in kebab-case.
• description — la riga più importante di tutta la skill. È quella che Claude legge per decidere se attivarla. Una descrizione vaga ("gestisce i commit") fa sì che la skill non scatti mai o scatti a sproposito. Una descrizione che dice cosa fa e quando usarla ("...da usare ogni volta che si prepara un commit") la rende affidabile.

C'è poi un campo opzionale utile: allowed-tools, con cui restringi gli strumenti che la skill può usare (per esempio, solo lettura e Bash, niente scrittura su file). Serve quando vuoi che una skill resti deliberatamente limitata.

Il corpo, sotto l'intestazione, è Markdown normale. Scrivilo come scriveresti istruzioni a un collega bravo ma nuovo: chiaro, concreto, con esempi. Niente fronzoli.

Come creare la tua prima skill con skill-creator

Tecnicamente potresti creare la cartella e il SKILL.md a mano: è solo un file su disco. Ma il modo consigliato — e più veloce — è lasciar fare a Claude Code stesso, usando una skill apposita: /skill-creator:skill-creator.

È una skill ufficiale che fa una cosa sola, e la fa bene: ti intervista su cosa deve fare la nuova skill e quando va usata, poi genera per te la cartella, il SKILL.md con l'intestazione già impostata e una description scritta come si deve. Esattamente la parte su cui sbagliano tutti quando partono da zero.

Il flusso è questo:

1. Lancia la skill. In Claude Code digita:

   /skill-creator:skill-creator
   

2. Rispondi alle domande. Ti chiede a cosa serve la skill, in quali situazioni dovrebbe attivarsi, se deve usare script o restare solo istruzioni. Sii concreto: più sei preciso sul quando, migliore sarà la description generata — ed è quella che determina se la skill scatterà davvero.

3. Scegli dove farla vivere. Hai due opzioni, e skill-creator scaffolda nel posto giusto:

   • ~/.claude/skills/<nome>/SKILL.md → skill personale, disponibile in tutti i tuoi progetti, solo per te.
   • .claude/skills/<nome>/SKILL.md → skill di progetto, versionata in git e condivisa con tutto il team. Chiunque cloni il repo se la ritrova.

4. Rivedi quello che ha generato. Apri il SKILL.md prodotto e controlla l'intestazione: il name, e soprattutto la description. È il 90% del lavoro, ed è normale rifinirla a mano per renderla ancora più esplicita su quando usarla.

5. Provala. Lancia un task che dovrebbe attivarla ("preparami il commit per queste modifiche"). Se non scatta, quasi sempre il problema è la description troppo generica: rendila più precisa sul contesto d'uso.

Il vantaggio non è risparmiare i trenta secondi per creare una cartella. È che skill-creator ti forza a ragionare sulla descrizione e sui casi d'uso prima di scrivere le istruzioni — l'ordine giusto — e ti consegna una struttura già coerente con le convenzioni. Per la tua prima skill, parti da qui.

Quando la skill cresce, sposta i dettagli pesanti in file separati nella stessa cartella e rimandaci dal SKILL.md ("per la checklist completa vedi checklist.md"). Così sfrutti la progressive disclosure: il corpo resta snello, il dettaglio si carica solo all'occorrenza. E se un'operazione è deterministica — formattare un file, generare un report — falla fare a uno script dentro la cartella, invece di descriverla a parole: è più affidabile e consuma meno token. Anche qui skill-creator può aiutarti a impostare lo scheletro.

Skill, subagent o MCP: quando usare cosa (e dove stanno gli slash command)

Qui sta la confusione che vedo più spesso. La domanda da farsi è sempre: chi decide, e cosa porta in tavola?

• Skill → porta istruzioni (più eventuali script). È una competenza impacchettata, e si attiva in due modi: automatico, quando Claude la sceglie da solo leggendo la description; oppure manuale, quando sei tu a invocarla digitando /nome. Già: è qui che entrano gli slash command. Non sono più una primitiva a parte — oggi uno slash command è una skill che lanci a mano, quando vuoi tenere tu il controllo del momento ("ora esegui la mia routine di review"). Una sola scatola, due interruttori.

• Subagent → porta un contesto separato. Un subagent è un agente a sé, con una propria finestra di contesto e i propri strumenti, a cui viene affidato un compito che torna indietro come risultato. Lo usi quando un lavoro è grosso e vuoi isolarlo — una ricerca ampia, un'analisi che sporcherebbe la conversazione principale. Non è "istruzioni", è "lavoro svolto altrove".

• MCP (Model Context Protocol) → porta dati o strumenti esterni. Un server MCP dà a Claude l'accesso a sistemi fuori dal progetto: un database, le issue di GitHub, un browser, un'API interna. È la scelta giusta quando il problema non è "spiegare a Claude come fare una cosa", ma "dargli la possibilità di toccare un sistema che altrimenti non vede".

La regola pratica che uso: se stai scrivendo istruzioni riutilizzabili, è una skill — e poi decidi tu se lasciarla scattare da sola o lanciarla a mano con /nome. Se vuoi delegare un lavoro pesante e isolato, è un subagent. Se ti serve toccare un sistema esterno, è MCP. Spesso convivono: una skill può benissimo dire a Claude di interrogare un server MCP.

Skill di progetto contro CLAUDE.md: non sono la stessa cosa

Molti, all'inizio, infilano ogni regola dentro CLAUDE.md. Funziona finché le regole sono poche. Il problema è che CLAUDE.md viene caricato per intero, sempre: dieci procedure specialistiche lì dentro significano dieci procedure che occupano contesto a ogni conversazione, anche quando ne serve una sola.

Le skill ribaltano la logica. In CLAUDE.md tieni ciò che vale sempre (lo stack, le convenzioni generali, i comandi base del progetto). Tutto ciò che è specialistico e situazionale — "come si scrive un post per il blog", "come si imposta una nuova migration", "come si genera il changelog di release" — diventa una skill, che pesa due righe finché non serve davvero. Il contesto resta pulito e la conoscenza scala.

Errori comuni da evitare

• Descrizione troppo vaga. È l'errore numero uno. Se la skill non scatta mai, riscrivi la description dicendo chiaramente quando va usata, non solo cosa fa.
• Mettere tutto nel SKILL.md. Se diventa lungo, spezzalo: dettagli e materiali pesanti in file a parte, richiamati dal corpo.
• Descrivere a parole ciò che andrebbe in uno script. Le operazioni deterministiche falle eseguire da uno script nella cartella della skill: più affidabili, meno token.
• Usare una skill quando serviva un MCP (o viceversa). Le istruzioni non danno accesso a un database; un server MCP non insegna lo stile dei tuoi commit. Tienili distinti.

In sintesi

Le Claude Code Skills sono il modo più pulito per dare a Claude una competenza ricorrente senza riempire ogni prompt di istruzioni. Una cartella, un SKILL.md, una descrizione scritta bene: tanto basta per trasformare un copia-incolla che ripeti da mesi in una capacità che si attiva da sola, condivisibile con tutto il team via git.

Se costruisci con l'AI ogni giorno e vuoi confrontarti con altri che lo fanno sul serio — skill, workflow, automazioni reali su progetti veri — è esattamente quello che facciamo dentro AI Builders Italia: la community italiana di chi sviluppa con l'AI.

Domande frequenti

Cosa sono le Claude Code Skills?

Sono cartelle contenenti un file SKILL.md (con nome, descrizione e istruzioni in Markdown) che impacchettano una competenza riutilizzabile. Claude Code le carica automaticamente quando un task corrisponde alla loro descrizione, senza che tu debba richiamarle a mano.

Dove si salvano le skill di Claude Code?

In due posti: ~/.claude/skills/<nome>/SKILL.md per le skill personali, disponibili in tutti i tuoi progetti; oppure .claude/skills/<nome>/SKILL.md per le skill di progetto, versionate in git e condivise con il team.

Come si crea una skill in Claude Code?

Il modo più veloce è la skill /skill-creator:skill-creator: la lanci in Claude Code, rispondi alle domande su cosa deve fare e quando va usata, e lei genera la cartella e il file SKILL.md con l'intestazione già impostata. Poi rivedi e rifinisci la description. In alternativa puoi creare cartella e SKILL.md a mano, ma skill-creator ti aiuta a impostare bene la descrizione, che è la parte decisiva.

Qual è la differenza tra una skill e uno slash command?

Oggi non è più una vera differenza: Anthropic ha unificato i due concetti. Uno slash command è una skill che invochi manualmente digitando /nome, mentre una skill "classica" si attiva da sola quando Claude la ritiene pertinente in base alla description. Stessa primitiva, due modalità di invocazione — manuale o automatica.

Una skill è la stessa cosa di un server MCP?

No. Una skill contiene istruzioni (e al massimo script) per spiegare a Claude come fare qualcosa. Un server MCP dà a Claude l'accesso a sistemi esterni — database, GitHub, API, browser. Le istruzioni non danno accesso ai dati; l'accesso ai dati non insegna una procedura. Spesso si usano insieme.

Meglio una skill o CLAUDE.md per le mie regole?

In CLAUDE.md metti ciò che vale sempre (stack, convenzioni generali, comandi base), perché viene caricato a ogni conversazione. Le competenze specialistiche e situazionali stanno meglio come skill: pesano pochissimo finché non servono, grazie alla progressive disclosure, e mantengono il contesto pulito.