Come Scrivere uno Skill Claude (Struttura SKILL.md + Esempi Reali)

Ecco come scrivere uno skill Claude in una frase: crea una cartella, metti dentro un file SKILL.md e scrivi una description abbastanza chiara da far capire a Claude quando usarlo. Questo è tutto il meccanismo. La parte che decide davvero se il tuo skill funziona è lunga 1.024 caratteri, ed è il campo description che Anthropic usa per scegliere il tuo skill tra gli oltre 100 che potrebbero essere caricati. Noi gestiamo 25 skill in produzione nella libreria della community Techsy, e quelli che falliscono quasi mai falliscono per le istruzioni. Falliscono su quella singola riga.

Riepilogo rapido

Per scrivere uno skill Claude: (1) crea una cartella con il nome dello skill, (2) aggiungi un file SKILL.md con frontmatter YAML (name e description) più le istruzioni in Markdown, (3) scrivi la description in terza persona con parole chiave che ne attivino il trigger, (4) mantieni il corpo sotto le 500 righe e sposta i dettagli in file di riferimento, e (5) testalo con task reali prima di fidartene.

Cosa è davvero uno skill Claude

Uno skill è una cartella con un file SKILL.md alla radice. Non serve altro. Quel file contiene due cose: metadati che dicono a Claude quando usare lo skill, e istruzioni che dicono a Claude come svolgere il task una volta attivato.

Il motivo per cui tutto questo resta economico è un modello di caricamento che Anthropic chiama progressive disclosure. All'avvio, Claude legge solo name e description di ogni skill installato, circa 100 token ciascuno. Legge l'intero SKILL.md solo quando la tua description corrisponde al task che ha davanti, e legge gli eventuali file di riferimento allegati solo quando le istruzioni li richiamano. Così puoi pubblicare uno skill ampio e dettagliato senza pagarne il costo a ogni richiesta. Puoi vedere un catalogo funzionante di questi skill nella nostra libreria Skills.

Lo scheletro SKILL.md da copiare

Ogni skill parte dalla stessa forma. Ecco la versione minima che funziona:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Due marcatori --- racchiudono il frontmatter. Sotto di essi, il corpo è semplice Markdown. Tra i nostri 25 skill, la struttura che ha retto all'uso reale è noiosa e coerente: un titolo su una riga, poi una procedura numerata o puntata, poi eventuali template o esempi. Quando ci siamo messi a fare prosa elaborata, Claude l'ha solo scorsa. Quando abbiamo scritto passaggi, li ha seguiti. Se vuoi studiarne di già pronti, i 25 skill sul sito della community Techsy sono tutti file SKILL.md leggibili che puoi aprire e copiare.

Regole del frontmatter: name e description

Il frontmatter ha esattamente due campi obbligatori, ed entrambi hanno limiti rigidi che vale la pena memorizzare perché gli strumenti di Anthropic li validano.

Una convenzione utile dalla guida di best practice di Anthropic: dai un nome agli skill in forma gerundiva, quindi processing-pdfs, writing-documentation, analyzing-spreadsheets. Si legge bene in un elenco e descrive l'attività invece di un sostantivo vago come helper o utils. Mantieni il name allineato al nome della cartella, così i due non si disallineano mai. Per le regole di validazione complete, il documento di best practice di Anthropic è la fonte autorevole.

Scrivi una description che attivi davvero lo skill

Questa è la sezione che la maggior parte dei tutorial salta, ed è quella che decide se il tuo lavoro verrà mai usato. La description viene iniettata nel system prompt, e Claude la legge per decidere se caricare lo skill. Un corpo perfetto dietro una description vaga è uno skill che non parte mai.

Tre regole fanno la differenza:

Scrivi in terza persona. La description descrive lo skill, non te e non l'utente. Formulazioni in prima o seconda persona confondono la selezione.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Indica sia il cosa che il quando. "Processes data" non dice a Claude nulla su quale task corrisponda. Indica la capacità concreta e i trigger concreti.

Includi le parole che un utente scriverebbe davvero. Se le persone dicono "PR", "diff" e "code review", metti questi termini nella description. Claude li usa per il matching. È la modifica a più alto impatto che puoi fare a uno skill, e costa una sola riga.

Progressive disclosure e struttura dei file

Quando uno skill cresce oltre una o due schermate, la struttura inizia a contare. L'indicazione di Anthropic è concreta: mantieni il corpo del SKILL.md sotto le 500 righe, e sposta tutto ciò che è più lungo in file di riferimento separati collegati dal corpo. Quei file non costano token finché Claude non li legge davvero.

Uno skill cresciuto ha questo aspetto:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Due regole tengono in piedi questo sistema. Primo, mantieni i riferimenti a un solo livello di profondità: collega ogni file direttamente da SKILL.md, mai file-a-file-a-file, perché Claude potrebbe leggere solo parzialmente i file annidati in profondità e perdere contenuto. Secondo, dai a ogni file di riferimento più lungo di 100 righe un sommario in cima, così anche una lettura parziale mostra l'intero perimetro. L'approfondimento tecnico di Anthropic sugli Agent Skills spiega l'architettura dietro a tutto questo se vuoi il modello più approfondito. Quando il tuo skill inizia a orchestrare strumenti, il nostro catalogo MCP è un buon complemento per collegare i server.

Gradi di libertà (e quando aggiungere script)

Non tutte le istruzioni devono essere ugualmente rigide. Calibra quanto rigidamente scriptare un passaggio in base a quanto è fragile.

Quando un passaggio è deterministico, distribuisci uno script invece di chiedere a Claude di generare codice ogni volta. Uno script incluso è più affidabile, risparmia token e resta coerente tra un'esecuzione e l'altra. Due abitudini tengono gli script onesti: gestisci gli errori dentro lo script invece di rimandarli a Claude, e motiva ogni costante così non hai numeri magici inspiegati. È anche qui che gli skill si differenziano dai subagent, che portano con sé un proprio tool allowlist e system prompt; la nostra libreria automations raccoglie esempi di subagent, e puoi confrontare i due approcci sulla pagina Techsy AI automations.

Testalo: sviluppo di skill guidato dagli eval

I migliori autori di skill scrivono i test prima della documentazione. Anthropic consiglia di costruire prima le evaluation: esegui Claude su tre task rappresentativi senza lo skill, annota esattamente dove fallisce, poi scrivi solo le istruzioni necessarie a correggere quei fallimenti. Così continui a risolvere problemi reali invece di documentare problemi immaginati.

Un ciclo pratico:

1. Scegli tre task reali che lo skill dovrà gestire.
2. Eseguili senza alcuno skill caricato e registra cosa si rompe.
3. Scrivi il SKILL.md minimo che corregge quei problemi.
4. Testa di nuovo con lo skill caricato, idealmente su Claude Haiku, Sonnet e Opus, perché uno skill che guida bene Opus può risultare sotto-specificato per Haiku.
5. Osserva come Claude naviga tra i file. Se ignora un riferimento, il tuo link non è abbastanza in evidenza. Se rilegge costantemente lo stesso file, quel contenuto appartiene al SKILL.md.

Per una guida pratica che costruisce uno skill dall'inizio alla fine, il nostro sito gemello ha un tutorial completo sui Claude Skills; si accompagna bene alle regole di scrittura qui sopra. Puoi anche monitorare la tua build con le nostre checklist enterprise.

Errori comuni che uccidono uno skill

La maggior parte degli skill rotti fallisce per uno di questi motivi:

• Una description scritta per gli umani. Un testo da marketing si legge bene ma non attiva nulla. Scrivi per il modello: capacità e trigger.
• Troppe opzioni. "Usa pypdf, oppure pdfplumber, oppure PyMuPDF, oppure..." fa esitare Claude. Dai un'opzione predefinita con un'unica via di fuga.
• Riferimenti annidati in profondità. File che rimandano a file che rimandano ad altri file vengono letti solo in parte. Tieni tutto a un solo passo da SKILL.md.
• Istruzioni legate al tempo. "Prima di agosto, fai X" invecchia male. Metti invece le indicazioni superate in una nota collassata "vecchi pattern".
• Percorsi in stile Windows. Usa sempre le barre in avanti; le backslash si rompono sui runner Unix.
• Terminologia incoerente. Scegli una sola parola per una cosa ("campo", non "campo/casella/elemento/controllo") e usala ovunque.

Il filo conduttore di tutti e sei: uno skill è un set di istruzioni per un lettore molto capace che non ha pazienza per l'ambiguità. Di' la cosa specifica, una volta sola.

Informazioni sull'autore

Mert Batur Gurbuz è Co-Founder di Techsy, University of Birmingham. Insieme al team Techsy costruisce agenti AI, sistemi di automazione e pipeline voice/SDR per clienti B2B, e cura la libreria di 25 skill citata in questa guida. Connettiti su LinkedIn. Altre guide per builder sono sul blog di TECHSY.community.

Domande frequenti

Dove si trovano i file degli skill Claude?

Uno skill è una cartella che contiene un file SKILL.md. In Claude Code, gli skill personali vanno in ~/.claude/skills/{skill-name}/ e quelli di progetto in .claude/skills/{skill-name}/. Su API e claude.ai, carichi tu la cartella dello skill. Il nome della cartella dovrebbe corrispondere al campo name nel frontmatter.

Il nome dello skill deve corrispondere al nome della cartella?

Sì, tienili identici. Il campo name deve avere massimo 64 caratteri, usare solo lettere minuscole, numeri e trattini, ed evitare le parole riservate "anthropic" e "claude". Far corrispondere il nome della cartella evita disallineamenti e rende lo skill facile da citare in conversazione e documentazione.

Quanto può essere lungo un SKILL.md?

Mantieni il corpo del SKILL.md sotto le 500 righe per prestazioni affidabili. Non c'è un limite rigido di token, perché file di riferimento e script non costano nulla finché non vengono letti, ma un file principale gonfio compete con tutto il resto nella finestra di contesto. Quando ti avvicini alle 500 righe, sposta i dettagli in file di riferimento collegati direttamente dal SKILL.md.

Perché il mio skill non si attiva?

Quasi sempre è la description. Claude seleziona gli skill facendo corrispondere il task al campo description, quindi se la tua è vaga o scritta in prima persona, non si attiva mai. Riscrivila in terza persona, indica cosa fa lo skill e quando usarlo, e includi le parole esatte che un utente digiterebbe per quel task.

Qual è la differenza tra uno skill, un subagent e un server MCP?

Uno skill è un insieme di istruzioni impacchettate che Claude carica quando è rilevante. Un subagent è un agente separato con un proprio tool allowlist e system prompt che gestisce un task delegato. Un server MCP espone strumenti e dati esterni tramite il Model Context Protocol. Gli skill descrivono come svolgere il lavoro; i server MCP forniscono su cosa agire.

Uno skill Claude può eseguire codice?

Sì. Gli skill possono includere script eseguibili che Claude esegue come strumenti invece di leggerli nel contesto, il che è più economico e affidabile per lavori deterministici come validazione o conversione di file. Rendi esplicita l'intenzione nelle tue istruzioni: scrivi "esegui questo script" per l'esecuzione, oppure "consulta questo script" quando è materiale di riferimento.

Gli skill funzionano sia su API che su claude.ai?

Sì, anche se il runtime differisce. Su claude.ai l'ambiente di esecuzione del codice può installare pacchetti da npm e PyPI, mentre l'API di Claude non ha accesso alla rete né installazione di pacchetti a runtime. Elenca i pacchetti richiesti nel tuo SKILL.md e verifica che siano disponibili nell'ambiente di destinazione prima di farci affidamento.

Quanti skill può avere Claude caricati contemporaneamente?

Molti, perché all'avvio nel contesto restano solo il name e la description di ogni skill, circa 100 token ciascuno. Ecco perché la description conta così tanto: Claude potrebbe scegliere tra oltre 100 skill, ed è una description precisa a permettergli di scegliere correttamente il tuo. Il corpo completo si carica solo una volta selezionato lo skill.