Claude Code Skills: File SKILL.md che il modello invoca effettivamente

Ultimo aggiornamento: June 28, 2026

Una Claude Code Skill è una cartella con un file SKILL.md che l'agente carica nel contesto solo quando un compito corrisponde ad essa. Ho creato la mia prima skill per smettere di incollare la stessa checklist di migrazione del database da 200 parole in ogni sessione. Quel singolo file mi fa risparmiare circa un'ora a settimana.

Ecco la versione breve, seguita dall'anatomia pratica: cos'è uno skill, come scrivere il frontmatter e il corpo di SKILL.md, come il modello decide di invocare una skill e quando una skill è eccessiva rispetto a un semplice prompt. Se utilizzi già Claude Code, puoi creare la tua prima skill in meno di cinque minuti.

Risposta rapida: cos'è una Claude Code Skill?

Una skill è una capacità riutilizzabile, invocata dal modello e archiviata come SKILL.md (più script di supporto opzionali). A differenza di un prompt di sistema che viene sempre caricato, una skill viene caricata su richiesta quando il modello decide che è rilevante per la tua richiesta. Tu scrivi un nome, una descrizione di quando usarla e le istruzioni del corpo. La descrizione è il campo più importante perché è ciò che il modello legge per decidere se attivare lo skill. Le skills vivono localmente in .claude/skills/ o vengono inviate da un registro, permettendo a un team di condividere un modo canonico per eseguire migrazioni, revisioni del codice o rilasci.

Se desideri un contesto più ampio sulla CLI stessa, consulta la mia guida definitiva su Claude Code per il 2026. Per sapere come le skills differiscono dai sub-agent sempre attivi, leggi come ho automatizzato il mio flusso di lavoro con i sub-agent di Claude Code.

Cos'è realmente una skill e di cosa è composta?

Una skill è una directory. Il minimo che le serve è un file SKILL.md. Opzionalmente, può raggruppare script, template o documenti di riferimento che viaggiano con la skill. La documentazione delle agent-skills di Anthropic descrive una skill come un set di istruzioni e risorse impacchettizzate che il modello può caricare quando è rilevante (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Io considero una skill come una subroutine nominata e versionata per il modello. Tre cose la rendono diversa da un lungo prompt:

1. È opt-in. Il modello la carica solo quando un compito sembra corrispondere alla descrizione.
2. È scope-limitata. Puoi allegare file e script che hanno senso solo per quella specifica capacità.
3. È condivisibile. La cartella è portatile tra progetti e membri del team.

La CLI stessa è open source e la convenzione delle skills è documentata accanto ad essa su GitHub (github.com/anthropics/claude-code), dove controllo quando cambiano i comportamenti tra i rilasci.

Come si struttura un file SKILL.md?

Il file ha due parti: il frontmatter YAML e un corpo Markdown. Il frontmatter dice al modello quando eseguire; il corpo gli dice cosa fare. Ecco l'anatomia che utilizzo.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

Il corpo è Markdown semplice. Mantengo tre sezioni: un obiettivo di una riga, una procedura numerata e un gate esplicito "fermati e conferma". Il name deve corrispondere al nome della cartella. La description dovrebbe essere scritta per il modello, non per un umano, quindi deve sembrare una condizione di attivazione.

L'ho testato direttamente. Con una descrizione vaga come "aiuta con i database", lo skill si attivava su domande SQL non correlate. Dopo averlo riscritto in "Use when the user asks to create, modify, or roll back a database migration," la precisione di invocazione è passata da circa il 60% ad affidabile. È la descrizione a fare l'instradamento, quindi dedica tempo alla modifica lì.

Quando dovresti trasformare qualcosa in una skill?

Questa è la domanda che mi fanno più spesso. La mia regola: se ho incollato lo stesso blocco di istruzioni tre volte in due settimane, ed è più lungo di un paragrafo, diventa una skill. Di seguito trovi la matrice decisionale che effettivamente utilizzo.

L'asse secondario è il costo. Ogni skill caricata aggiunge token al contesto, quindi un blocco di istruzioni grande e sempre rilevante è meglio come memoria a livello di progetto o un comando personalizzato piuttosto che come skill. Le skills eccellono per l'esperienza condizionalmente rilevante.

Un caso concreto in cui ho scritto una skill: il nostro processo di rilascio richiede l'aggiornamento di un changelog, l'incremento di tre file di versione, il tagging e la pubblicazione di un riepilogo su Slack. L'ho scritto una volta come skill, e ora dico "cut a release" e il modello esegue l'intera checklist in ordine. Un caso concreto in cui non l'ho fatto: un refactoring occasionale di un file di configurazione. Quello è rimasto un prompt.

Come funziona lo schema dello skill invocato dal modello?

Lo schema che fa sembrare le skills magiche è che tu non le chiami. Tu descrivi il lavoro, e il modello legge le descrizioni delle skill disponibili e ne carica quella corrispondente. Questo è documentato nella guida ufficiale di Claude Code (docs.anthropic.com/en/docs/claude-code).

Il flusso è il seguente:

1. Inserisci una richiesta in linguaggio naturale.
2. Il modello vede il name e la description di ogni skill installata.
3. Assegna un punteggio di rilevanza rispetto alla tua richiesta.
4. Il corpo (e i file allegati) dello skill vincente entrano nel contesto.
5. Il modello esegue le istruzioni.

La conseguenza pratica: devi scrivere la description come se stessi scrivendo una voce di ricerca per il modello. Inizia con il verbo e lo scope del trigger. Confronta queste due descrizioni:

• Debole: "Una skill per gestire cose git."
• Forte: "Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite."

La seconda nomina i verbi trigger e il guardrail. Questo è ciò che rende l'invocazione affidabile. Se stai collegando skills con strumenti, la guida di integrazione Claude Code MCP copre come i server di strumenti esterni si adattano ai bundle di skill. Per il protocollo sottostante che li collega, consulta MCP e contesto del modello.

Come si attiva e si debugga una skill?

L'attivazione è per lo più automatica, ma ho tre tecniche deliberate per il controllo e il debugging.

• Sii esplicito. Dire "use the safe-migration skill" la forza. Utile quando la descrizione è ambigua.
• Elenca le skills installate. Chiedi al modello di elencare le skills disponibili e le loro descrizioni. È così che confermo che una nuova skill è registrata.
• Ispeziona il trace. Quando uno skill si attiva erroneamente, leggo quale descrizione ha corrisponduto e rafforzo la formulazione del trigger.

Quando uno skill non si attiva, la causa è quasi sempre la descrizione, non la posizione del file. Riscrivo la prima frase per iniziare con "Use when..." e aggiungo i verbi specifici. Questo risolve il problema nove volte su dieci.

Ecco la checklist di debug che eseguo, in ordine:

Skill contro sub-agent contro comando slash

Questi tre si sovrappongono, e la gente li confonde costantemente. Li tengo distinti con una semplice distinzione.

• Skill: istruzioni invocate dal modello più file opzionali. Ideale per l'expertise condizionale.
• Sub-agent: un'istanza separata di Claude Code che esegue lavoro isolato. Ideale per compiti paralleli e a lunga durata. Il mio articolo sulla creazione di sub-agent approfondisce questo argomento.
• Comando slash: una scorciatoia che digiti deliberatamente. Ideale per cose che vuoi sempre su richiesta.

Le skills sono l'unica delle tre che il modello sceglie per te. Questo è il loro superpotere e il loro rischio: uno skill descritto male spreca contesto in silenzio.

Come si condividono le skills e si usa un registro?

Una skill è solo una cartella, quindi la condivisione è banale in linea di principio. Posiziono la cartella sotto .claude/skills/ nel repo e la commito. I colleghi lo ricevono al clone. Per la condivisione inter-team, la community mantiene dei registri e gli strumenti ufficiali puntano a posizioni comuni.

La mia configurazione pratica:

1. Mantenere le skills specifiche del progetto nel repo, versionate.
2. Mantenere le skills personali in un repo dotfiles collegato tramite symlink a .claude/skills/.
3. Fissare le versioni delle skill quando si condividono esternamente, poiché un cambiamento nella descrizione può cambiare silenziosamente il comportamento.

L'onesta avvertenza sulla condivisione: una skill codifica assunzioni sul tuo stack. Una skill di migrazione scritta per Drizzle produrrà con sicurezza output errato in un progetto Prisma se la descrizione non tutela lo scope. Indica sempre il framework e i guardrail nella descrizione, e aggiungi un passaggio "fermati e conferma" prima delle azioni distruttive. Ho imparato questo modo difficile quando una skill condivisa ha eseguito un rewrite distruttivo sul branch sbagliato, quindi tratta ogni skill condivisa come non fidata finché la sua descrizione non ne dimostra diversamente.

Crediti delle immagini

• Schermo nero con testo codice sovrapposto su una postazione di lavoro per sviluppatori — foto di Pixabay su Pexels
• Primo piano del codice di programmazione su un monitor durante lo sviluppo — foto di Christina Morillo su Pexels
• Laptop che mostra un editor di codice durante lo sviluppo software — foto di luis gomes su Pexels