Skill di Claude Code: come sono fatti, SKILL.md e quando l'agente li carica

Che cosa sono le skill in Claude Code

Una skill (competenza) è una cartella con un file SKILL.md, in cui è descritta un'istruzione per un tipo specifico di attività: come fare il deploy di un progetto, come condurre una review, come pubblicare un rilascio. L'agente conosce l'esistenza della skill fin dall'inizio della sessione, ma la legge per intero solo quando il compito lo richiede davvero.

Le skill di Claude Code risolvono un problema noto a chiunque mantenga a lungo un CLAUDE.md: il file delle istruzioni cresce. Una procedura di deploy di 80 righe serve una volta alla settimana, ma occupa spazio nel contesto di ogni sessione — anche quando si corregge un refuso nel README. La skill sposta queste procedure fuori dal contesto permanente e le richiama quando servono.

Di cosa è fatta una skill

La skill minima è una cartella e un file. Le skill di progetto stanno nel repository, quelle personali nella cartella home dell'utente:

.claude/skills/deploy/SKILL.md      # skill di progetto, condivisa dal team tramite git
~/.claude/skills/review/SKILL.md    # skill personale, disponibile in tutti i progetti

Accanto a SKILL.md si possono mettere file di supporto: modelli, script, riferimenti. L'agente li apre solo se il testo principale della skill vi rimanda e se servono davvero:

.claude/skills/deploy/
├── SKILL.md           # istruzione principale
├── checklist.md       # checklist dettagliata, letta tramite link
└── rollback.sh        # script di rollback

Frontmatter: name e description

Il file inizia con un blocco YAML tra le righe ---. Due campi contano più di tutti gli altri: name — il nome breve della skill, e description — la descrizione di che cosa fa la skill e di quando applicarla.

---
name: deploy
description: Deploy del sito sull'hosting via FTP. Usare quando serve caricare le modifiche sul server, verificare le differenze con il server o annullare un deploy.
---

# Deploy

1. Prima una prova a secco: `./deploy.sh -n`.
2. Controllare l'elenco dei file: non devono comparire segreti né script di test.
3. Caricare: `./deploy.sh`.
4. Aprire le pagine modificate e verificare che rispondano con 200.

Rollback — vedi rollback.sh in questa cartella.

Sotto il frontmatter c'è un normale Markdown: passi, comandi, limiti, link ai file vicini. Scrivetelo come scrivereste un'istruzione per un nuovo collega che svolge quel compito per la prima volta.

Quando l'agente carica una skill

All'inizio della sessione nel contesto finiscono solo nome e descrizione di ogni skill disponibile. Sono poche righe per skill, quindi se ne possono tenere decine. Quando la richiesta dell'utente o il passo di lavoro corrente corrisponde alla descrizione, l'agente invoca la skill — e solo allora nel contesto viene caricato il testo completo di SKILL.md.

Ne segue la regola pratica principale: la skill si attiva in base alla descrizione. L'agente non vede il corpo della skill finché non decide di aprirla. Se nella description c'è scritto «Skill di supporto», l'agente non capirà quando serve. Se c'è scritto «Deploy sull'hosting; usare quando bisogna caricare le modifiche sul server o annullare un deploy», lo capirà.

Oltre alla scelta automatica, la skill si può richiamare esplicitamente per nome con la barra, per esempio /deploy. È comodo quando sapete esattamente quale procedura serve e non volete affidarvi alla corrispondenza tra richiesta e descrizione fatta dall'agente.

Come scrivere la description perché la skill si attivi

• Che cosa fa — in una frase, con un verbo: «Deploy del sito», «Review delle modifiche prima del commit».
• Quando usarla — elencate le formulazioni con cui l'utente chiede davvero questo compito: «carica sul server», «pubblica», «annulla».
• Quando non usarla, se la skill è facile da confondere con una vicina: «non per il deploy del bot, solo del sito».
• Niente frasi generiche come «skill utile» o «aiuta nel lavoro» — non portano alcun segnale.

Caricamento progressivo

Le skill si basano sul principio del caricamento progressivo (progressive disclosure): le informazioni arrivano a strati, e ogni strato successivo si carica solo quando serve.

È la stessa idea di un router al posto di un muro di testo nel file delle istruzioni: una mappa breve sempre a portata di mano, i dettagli via link. La differenza è che la skill rende questo caricamento un meccanismo standard, invece di affidarsi alla speranza che l'agente apra da solo il documento giusto. In più, uno script dal terzo strato l'agente può semplicemente eseguirlo, senza caricarne tutto il codice nel contesto.

Skill, CLAUDE.md e comandi slash: qual è la differenza

Tutti e tre i meccanismi trasmettono istruzioni all'agente, ma in momenti diversi e con costi diversi per il contesto.

La regola pratica per scegliere è semplice. Se un'istruzione serve quasi in ogni attività, il suo posto è il CLAUDE.md. Se serve in attività di un certo tipo, è una skill. Se digitate ogni volta a mano la stessa lunga richiesta, è un candidato per un comando o per una skill richiamata manualmente.

I divieti assoluti non vanno spostati nella skill. La skill potrebbe non caricarsi, mentre la regola «non committare mai i segreti» deve valere sempre. Tali invarianti restano nel CLAUDE.md e, dove possibile, sono rafforzati da un meccanismo: hook, permessi di accesso, controlli nel CI.

Come creare una skill per Claude Code: passo dopo passo

1. Trovate la procedura che si ripete. Un buon segnale: avete già spiegato all'agente la stessa cosa tre volte, oppure nel CLAUDE.md c'è una sezione che serve in una attività su dieci.
2. Create la cartella .claude/skills/<nome>/ e al suo interno il file SKILL.md.
3. Scrivete il frontmatter con name e description, in cui è detto esplicitamente quando applicare la skill.
4. Descrivete i passi con comandi concreti e criteri di completamento: che cosa verificare, quale risultato considerare un successo.
5. Spostate la parte lunga in file vicini e richiamateli dal testo principale.
6. Togliete il duplicato dal CLAUDE.md, lasciando una sola riga di rinvio: «Deploy — skill deploy».
7. Verificate: in una nuova sessione chiedete il compito con parole vostre, senza nominare la skill, e controllate se l'agente la richiama. Se no, riscrivete la descrizione.

Esempi di skill

Skill di deploy

Un candidato classico: la procedura è rara, lunga e pericolosa, e un errore costa caro. Nella skill si fissano l'ordine dei passi (prima la prova a secco, poi il caricamento), che cosa non va pubblicato, come verificare il risultato e come annullare. All'agente non serve tenere tutto questo in mente a ogni modifica del codice — solo quando si parla del server.

Skill di review

---
name: review
description: Review delle modifiche correnti prima del commit. Usare quando si chiede di controllare il diff, trovare errori nelle modifiche o preparare le modifiche al commit.
---

# Review delle modifiche

1. Ottenere il diff: `git diff` e `git diff --staged`.
2. Per ogni file modificato verificare:
   - l'input dell'utente viene sottoposto a escape in output;
   - le query SQL sono parametrizzate;
   - non ci sono output di debug né file temporanei.
3. Eseguire test e linter del progetto (i comandi sono nel CLAUDE.md).
4. Report: elenco dei problemi con file e riga, dal più grave al più lieve.
   Se non ci sono problemi, scriverlo così, senza inventare osservazioni.

Una skill del genere trasforma «guarda se va tutto bene» in un controllo ripetibile, con lo stesso insieme di punti ogni volta.

Skill di fine sessione

Un altro tipo utile è il rituale di chiusura del lavoro: fermare l'ambiente locale, eliminare i file temporanei, annotare nel registro del progresso che cosa è stato fatto e che cosa resta, fare un commit con una descrizione dettagliata. Questo cura direttamente la perdita di contesto tra una sessione e l'altra: la sessione successiva parte dallo stato aggiornato del repository, non da supposizioni.

Errori tipici

• Descrizione vaga. La skill esiste, ma l'agente non la richiama. Si risolve riscrivendo la description con trigger concreti.
• Skill-muro. In SKILL.md è stata spostata l'intera vecchia sezione da 400 righe. Il problema del contesto gonfio torna, solo più tardi. Tenete breve il testo principale e spostate i dettagli nei file vicini.
• Duplicazione con il CLAUDE.md. La stessa procedura è descritta in due posti e col tempo diverge. La fonte della verità deve essere una sola.
• Skill sovrapposte. Due skill con descrizioni simili: l'agente sceglie tra loro a caso. Separatele con indicazioni esplicite «usare / non usare».
• Comandi obsoleti. Lo script è stato rinominato, ma la skill fa ancora riferimento al vecchio nome. La skill è parte del codice del progetto: aggiornatela nello stesso commit della procedura.

Come capire che è il momento di spostare una sezione in una skill

Conviene ogni tanto scorrere il CLAUDE.md e chiedersi, per ogni sezione: in quale quota delle attività normali serve davvero? Se serve quasi sempre, è al posto giusto. Se serve in una attività su dieci, è un candidato per una skill.

Un secondo segnale è la lunghezza. Una sezione che non sta su una schermata descrive quasi certamente una procedura, non una regola. Le procedure si leggono meglio per intero nel momento in cui si eseguono, invece di tenerle sullo sfondo per tutta la sessione.

Un terzo segnale sono le spiegazioni ripetute. Se continuate a dire all'agente le stesse precisazioni sulla stessa attività, scrivetele una volta nella skill. Dopo una settimana controllate se sono diminuite le correzioni manuali: è la prova che la skill funziona.

Riepilogo

Le skill di Claude Code sono un modo per conservare le procedure accanto al progetto senza pagarle in contesto a ogni sessione. La descrizione della skill è sempre visibile, il corpo si carica quando serve, i file di supporto ancora più tardi. Nel CLAUDE.md restano la mappa del progetto e le regole assolute, nelle skill vanno deploy, review, rilasci e le altre attività di un certo tipo. La struttura dei file delle istruzioni e il caricamento progressivo del contesto li affrontiamo in pratica nel corso di harness engineering.