Come creare una skill Claude: SKILL.md in 10 minuti

Testiamo le skill di Claude per lavoro, centinaia finora, e il pattern è deprimente: la maggior parte delle skill che falliscono la nostra revisione non ha fallito perché l'autore non sapeva scrivere istruzioni. Ha fallito perché la skill non si è mai caricata, o si è caricata quando non doveva, o era tre skill travestite da una sola. Tutto risolvibile in fase di scrittura, niente risolvibile dopo il fatto scrivendo un README più carino.

Questo è il tutorial che vorremmo avesse letto ogni autore prima di sottoporre una skill. Alla fine avrai una skill funzionante: una checklist di code review che spinge Claude oltre il "sembra a posto, magari rinomina questa variabile" fino a controllare condizioni limite, percorsi di errore e codice morto. È un esempio reale di proposito. La migliore skill della community nella nostra categoria coding, Code Review Checklist, fa esattamente questo e ottiene 8/10 sull'output. La tua non la batterà il primo giorno, ma capirai ogni decisione presa dall'autore di quella skill.

La promessa dei 10 minuti è onesta con un asterisco. Scrivere la prima versione funzionante richiede circa 10 minuti. Testarla a dovere ne richiede altri 30. Salta la seconda parte e ti unirai alla metà delle skill pubblicate che non sopravvive al contatto con una sessione nuova. Abbiamo scritto l'autopsia in perché metà delle skill Claude non funzionano, e preferiremmo non aggiungere la tua al dataset.

Se non hai mai installato una skill e non sai cosa sia, leggi prima cosa sono le skill di Claude e come installarle. Questo articolo presuppone che tu ne abbia già usata almeno una.

Passo 1: limitala a un solo compito

Prima di scrivere una riga, decidi cosa fa la tua skill. Poi dimezzalo.

Il fallimento più grande che vediamo nei test sono le skill che cercano di fare tutto. "Aiuta con la qualità del codice" suona come un ambito ragionevole. Non lo è. Una skill del genere vuole attivarsi su review, refactoring, scrittura di test, domande di linting e dibattiti di architettura, il che in pratica significa che Claude non riesce a capire quando caricarla, quindi si carica in modo imprevedibile o non si carica affatto. I problemi di attivazione sono la prima ragione per cui una skill ottiene un punteggio basso nella nostra metodologia, davanti a istruzioni scadenti e installazioni rotte. Non perché l'attivazione sia la parte più difficile della scrittura di una skill, ma perché lo scope creep a monte la rende irrisolvibile a valle.

Una skill, un compito. Ecco il test: riesci a completare la frase "usa questa skill quando l'utente chiede di ___" con una singola frase verbale concreta? "Revisionare una pull request o un diff" supera il test. "Migliorare il loro codice" no. Se la tua frase ha "e" oppure "o" a unire attività non correlate, stai scrivendo due skill. Scrivi due skill. Le cartelle sono gratis.

Per il nostro esempio, l'ambito è: revisionare un diff o una PR per bug di correttezza, usando una checklist fissa, sopprimendo le pignolerie di stile. Non "aiuta con le review". Non "revisiona e correggi". Revisiona, riporta, fermati.

Passo 2: il template di SKILL.md

Una skill è una cartella con un unico file obbligatorio. La nostra va in ~/.claude/skills/ per uso personale, oppure in .claude/skills/ dentro un repository se l'intero team deve averla:

review-checklist/
  SKILL.md          ← obbligatorio, e spesso è tutto ciò che serve
  reference/        ← opzionale, caricato solo quando Claude decide di leggerlo
  templates/        ← opzionale, file a cui puntano le tue istruzioni

Ecco il SKILL.md completo che costruiremo, annotato. Copialo, poi leggi le annotazioni, perché due di queste righe contano molto più delle altre:

---
# 'name' è un identificatore: minuscolo, trattini, niente spazi.
# Claude lo vede, ma NON guida l'attivazione.
name: review-checklist

# 'description' è l'UNICA cosa che Claude legge per decidere
# se caricare questa skill. Tutto ciò che segue il frontmatter
# è invisibile finché quella decisione non è presa. Scrivila come
# una condizione di trigger, non come testo pubblicitario.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

Questa è l'intera skill. Nessuna fase di build, nessun manifest, nessuna registrazione. Riavvia la tua sessione Claude ed è attiva.

Il frontmatter ha esattamente due campi che contano. name è amministrazione. description decide tutto, ed ecco perché: Claude tiene in contesto solo il nome e la descrizione di ogni skill installata. Il corpo del tuo SKILL.md non esiste, per quanto riguarda il modello, finché non legge la tua descrizione, decide "questo corrisponde a ciò che l'utente vuole", e carica il resto. Una brillante checklist di 200 righe dietro una descrizione vaga è una brillante checklist di 200 righe che nessuno eseguirà mai. Nella nostra griglia di valutazione, l'attivazione pesa quanto la qualità dell'output esattamente per questo motivo. Una skill che si attiva il 40% delle volte è un lancio di moneta con passaggi in più.

Passo 3: scrivi la descrizione trigger

Dato che la descrizione è una condizione di trigger, scrivila come tale. Nomina le formulazioni che un utente reale digiterebbe. Includi lo spazio negativo, cioè le richieste vicine in cui la skill dovrebbe restare silente.

Affiancate, da invii reali che abbiamo testato (leggermente anonimizzati):

Cattiva:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Buona:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

Quella cattiva descrive il beneficio. Quella buona descrive il momento. Claude non legge la tua descrizione per farsi convincere; sta facendo pattern-matching contro le parole reali dell'utente. "Revisiona questa PR" non condivide vocabolario con "aiuta a migliorare la qualità del codice", quindi la skill dorme proprio nel suo caso d'uso. Abbiamo testato un invio quasi identico a quell'esempio cattivo: si è attivato su 1 di 8 prompt a forma di review. Dopo aver riscritto la descrizione per nominare le formulazioni, stesso corpo, si è attivato su 8 di 8.

Un'altra coppia, questa sullo spazio negativo:

Cattiva:

description: Use for anything related to testing.

Buona:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

"Qualsiasi cosa legata ai test" è il modo in cui finisci per dirottare una sessione di debug. L'attivazione eccessiva è più silenziosa della mancata attivazione e altrettanto dannosa: l'utente riceve risposte in stile checklist a domande che avevano bisogno di altro, incolpa il modello, disinstalla la skill.

Regole meccaniche che reggono in tutto ciò che abbiamo testato: nomina da tre a cinque formulazioni utente concrete, includi almeno una clausola "do NOT use", resta sotto circa 500 caratteri, e non usare mai le parole "powerful", "comprehensive" o "helps with". Quelle parole correlano con punteggi di attivazione scadenti nei nostri dati in modo così coerente che ormai trasaliamo a vederle.

Passo 4: scrivi un corpo che Claude segue davvero

Una volta caricata la skill, il corpo è l'insieme di istruzioni. Il modo di fallimento qui è più sottile dell'attivazione ma altrettanto comune: istruzioni che ispirano invece di vincolare. "Scrivi una review accurata e ponderata" è un poster motivazionale. Claude vuole già essere accurato e ponderato; quello è il comportamento predefinito che stai cercando di plasmare, non la forma.

Le skill che dominano le nostre classifiche sono elenchi di vincoli. Test-Driven Development vieta l'implementazione prima che esista un test fallito, punto. La nostra skill di esempio limita i risultati a 10 e vieta del tutto le pignolerie di stile. Nota quante delle sue righe iniziano con "non fare". È deliberato. I modelli generano più del necessario di default, quindi le istruzioni di maggior valore sono di solito sottrattive.

Regole pratiche per il corpo:

1. Le procedure numerate battono la prosa. "Procedi in quest'ordine" dà a Claude una spina dorsale; i paragrafi danno vibrazioni.
2. Dichiara la condizione di arresto. La nostra skill dice riporta i risultati, non correggerli. Senza quella riga, Claude inizierà utilmente a riscrivere il codice, cosa che nessuno ha chiesto.
3. Legifera sul formato dell'output. Conteggi massimi, campi obbligatori, come appare un risultato pulito. "Se il diff è pulito, dillo" impedisce risultati inventati, un fallimento che riscontriamo costantemente nelle skill di tipo review.
4. Metti i dettagli usati raramente in file reference/. Se la tua skill ha una guida di stile di 300 righe che si applica una volta al mese, non incollarla in SKILL.md dove brucia contesto a ogni attivazione. Salvala come reference/style-guide.md e scrivi "quando l'utente chiede di X, leggi prima reference/style-guide.md". Claude la carica su richiesta.

Quando aggiungere script e template? Solo quando le istruzioni non possono fare il lavoro. Una skill che genera un file di configurazione specifico dovrebbe fornire un templates/config.yaml e dire "copia questo, poi modificalo". Una skill che ha bisogno di comportamento deterministico, per esempio analizzare un formato di lockfile, dovrebbe fornire uno script e istruire Claude a eseguirlo piuttosto che reimplementarlo a memoria ogni volta. Ma la maggior parte delle skill non ha bisogno di nessuno dei due. Il nostro esempio non ne ha bisogno. Ogni file nella cartella è qualcosa che ora devi mantenere, quindi guadagnati ciascuno di essi.

Passo 5: testala localmente

Non hai finito quando funziona una volta. "Ha funzionato quando l'ho provata" è lo standard di test di ogni skill rotta che abbiamo mai bocciato. Ecco la batteria minima, e ricalca da vicino ciò che esegue la nostra metodologia sugli invii:

1. Sessione nuova. Riavvia completamente Claude Code. Le skill si caricano all'avvio della sessione; testare nella sessione in cui l'hai scritta non dimostra nulla.
2. Test di attivazione, positivo. Prova tre formulazioni diverse che un utente reale digiterebbe: "revisiona questa PR", "puoi controllare questo diff prima che faccia merge", "dai un'occhiata alle mie modifiche". Tutte e tre dovrebbero attivare la skill. Puoi capire se si è attivata dal fatto che l'output segue le tue regole (un elenco di risultati limitato e ordinato per gravità non somiglia per niente a una review di default). Se non sei sicuro, chiedi direttamente a Claude se ha usato la skill.
3. Test di attivazione, negativo. Prova tre richieste vicine che NON dovrebbero attivarla: "correggi questo bug", "scrivi una funzione che analizza le date", "perché questo test fallisce?". Se la tua checklist di review compare in una sessione di debug, la tua descrizione ha bisogno di una clausola "do NOT use".
4. Confronto con la baseline. Esegui lo stesso prompt di review in una sessione con la skill e una senza. Se non riesci a distinguere gli output, la skill non si sta guadagnando il suo contesto e dovresti affinare i vincoli. Questo è il nostro test preferito perché è spietato. Circa un terzo delle skill che revisioniamo lo fallisce.
5. Test di installazione pulita. Se hai intenzione di pubblicare: copia la cartella su un'altra macchina (o cancella e riclona), segui il tuo README alla lettera, e verifica se funziona. Le note sulle dipendenze mancanti muoiono qui.

L'intera batteria richiede 30 minuti. Filtra circa l'80% dei fallimenti che vediamo, un ottimo ritorno per mezz'ora.

Passo 6: passala nel validatore

Prima di pubblicare, incolla il tuo SKILL.md nel nostro validatore di skill gratuito. Valuta secondo la stessa griglia che usiamo nelle revisioni: lunghezza e specificità della descrizione, presenza di formulazioni trigger concrete, clausole di spazio negativo, densità di vincoli nel corpo, legislazione del formato, anti-pattern evidenti come "powerful" e "anything related to".

È analisi statica, quindi trattala di conseguenza. Cattura gli errori visibili nel testo, che nella nostra esperienza sono la maggior parte, ma non può eseguire la tua skill contro prompt live. Un validatore superato più la batteria del Passo 5 è la vera soglia. Un validatore superato da solo è una skill lintata che potrebbe ancora non attivarsi.

Se preferisci un aiuto interattivo a un controllore, Skill Creator di Anthropic è lo strumento che consigliamo. Ha ottenuto 9,6 nei nostri test, struttura la cartella, e il suo passaggio di ottimizzazione della descrizione ha migliorato in modo misurabile l'attivazione sulle nostre skill interne. Usare una skill per scrivere skill sembra uno scherzo e funziona comunque.

Passo 7: pubblica e invia

Pubblicare è un normale repository GitHub. Convenzione di struttura:

your-repo/
  README.md           ← cosa fa, comando di installazione, un esempio
  review-checklist/
    SKILL.md
    reference/

Metti il comando di installazione nel README come blocco copia-incolla, lo schema standard è git clone più cp -r review-checklist ~/.claude/skills/. Poi aggiungi il tag topic claude-skills al repository. Non è decorazione: il tag topic è il modo in cui il nostro crawler e ogni altra directory scoprono nuove skill. Un repository di skill senza tag è invisibile nella pratica.

Un README che vale la pena scrivere ha quattro cose: una frase su cosa fa la skill, il blocco di installazione, un esempio prima/dopo, e qualsiasi dipendenza. L'esempio prima/dopo fa più per l'adozione di tutto il resto messo insieme, perché è l'unica parte che mostra invece di dichiarare.

Poi invialo a SkillProof. Test e inserimento nell'elenco sono gratuiti. Facciamo passare l'invio attraverso lo stesso processo di tutto il resto nel catalogo: installazione pulita dal tuo README, batteria di attivazione, confronto con la baseline, valutazione dell'output. Se supera il test, viene elencata con un punteggio, e puoi inserire un badge "SkillProof tested" nel tuo README. Per un autore sconosciuto con un repository vecchio di due giorni, un verdetto di test indipendente è la differenza tra "un SKILL.md a caso da internet" e qualcosa che uno sconosciuto installerà davvero. Se non supera il test, ricevi le note sul fallimento, correggi e reinvii. Molte skill elencate sono passate per due round.

Errori comuni che vediamo negli invii

Dopo qualche centinaio di revisioni, gli stessi cinque continuano a comparire.

Descrizioni vaghe. Ancora al primo posto per ampio margine. Se la tua descrizione potrebbe descrivere altre tre skill, non ne descrive nessuna.

La skill tuttofare. Un unico SKILL.md che gestisce review, commit, refactoring e documentazione. Ogni compito diluisce il trigger degli altri. Dividila.

Ripetere i comportamenti predefiniti del modello. Un corpo che dice "sii chiaro, sii accurato, pensa passo dopo passo" non aggiunge nulla. Claude lo fa comunque. Se cancellare una riga non cambierebbe l'output, cancella la riga.

Nessun vincolo negativo. Skill che dicono solo cosa fare, mai cosa smettere di fare. Le righe "non fare" sono dove vive la maggior parte del cambiamento di comportamento.

Istruzioni di installazione non testate. Il README dice di copiare una cartella; la skill dipende silenziosamente da una seconda skill o da un pacchetto Python. Muore nel nostro test di installazione pulita ogni volta, ed è il fallimento più evitabile di questa lista.

Domande frequenti

Devo saper programmare per creare una skill Claude? No. Un SKILL.md è markdown con un'intestazione YAML. Se la tua skill include script di supporto dovrai scriverli, ma le skill solo a istruzioni, che sono la maggioranza, sono pura scrittura. La skill di questo articolo non contiene una riga di codice.

Quanto dovrebbe essere lungo un SKILL.md? Il più breve possibile pur vincolando il comportamento, tipicamente 30-150 righe. Sotto circa 20 righe di solito non aggiunge nulla oltre i comportamenti predefiniti; oltre qualche centinaio dovresti spostare i dettagli in file reference/. La lunghezza è un costo che paghi per ogni attivazione, non un segnale di qualità.

Perché la mia skill non si attiva? Quasi sempre la descrizione. Controlla che nomini formulazioni che un utente digiterebbe davvero invece di descrivere benefici, e conferma di aver riavviato la sessione dopo l'installazione, dato che le skill si caricano all'avvio della sessione. Se si attiva su alcune formulazioni e non su altre, aggiungi esplicitamente quelle mancanti alla descrizione.

Qual è la differenza tra una skill e un server MCP? Una skill è istruzioni: markdown che modella il comportamento di Claude, nessun codice in esecuzione da nessuna parte. Un server MCP è un programma che dà a Claude nuove capacità, come interrogare il tuo database. Se la tua idea è "Claude dovrebbe affrontare X diversamente", è una skill. Se è "Claude ha bisogno di accedere a Y", è MCP. Versione più lunga in Claude skills vs MCP.

Posso far pagare per una skill Claude? Non esiste un meccanismo di pagamento integrato; le skill sono file, e l'ecosistema pubblico gira su repository aperti. Alcuni autori vendono pack di skill private ai team come consulenza, il che funziona perché il valore è la competenza codificata, non il file. Qualsiasi cosa destinata al catalogo pubblico dovrebbe avere licenza aperta, dato che nessuno installa una skill che non può leggere.

Limita a un compito, scrivi il trigger come una regex in prosa, vincola invece di ispirare, e testa in una sessione nuova prima di dirlo a chiunque. Questo è tutto il mestiere. Il resto è iterazione, e la coda degli invii è aperta.