Claude Code ha ignorato la mia skill 5 volte. 1 riga l'ha risolto

Una skill di Claude Code può girare alla perfezione quando la chiami per nome e non caricarsi mai da sola. La nostra girava ogni volta che ne scrivevamo il nome, e veniva saltata ogni volta che chiedevamo lo stesso compito a parole nostre. L'abbiamo vista saltare, abbiamo letto il perché e abbiamo riscritto l'unica riga che ha risolto il problema.

Una skill è un insieme salvato di istruzioni che Claude Code carica da solo quando la tua richiesta corrisponde. A decidere la corrispondenza è una riga che Claude legge prima di scegliere, e non sono le tue istruzioni. I sei passi qui sotto ti portano dal prompt che continui a riscrivere a una skill che si carica da sola, più un test da venti richieste che scopre una skill saltata prima che lo faccia il tuo team.

Test (stessa richiesta, sessioni nuove)	Skill caricata
Chiamata per nome (/release-notes)	2 su 2
Parole nostre, descrizione originale	0 su 5
Parole nostre, descrizione riscritta	5 su 5

Una skill è una cartella con un solo file dentro, SKILL.md. Il file inizia con una breve intestazione (un nome e una descrizione di una frase) seguita dalle istruzioni. Funziona come una funzione: chi la chiama legge la firma e la docstring, e il corpo gira solo quando viene chiamata. Salvala nella tua cartella home per averla in ogni progetto, oppure dentro il repository così la ricevono tutti quelli che ci lavorano.

Parti dal compito, non dal file. Scegli il prompt che continui a riscrivere e annota l'output esatto che vuoi. Il nostro erano le release notes settimanali: i commit da lunedì, raggruppati per area, senza le attività di manutenzione, una riga per modifica con il numero della pull request. Sul repository open source Hono, quel prompt lungo ha prodotto note pulite per otto correzioni di bug di quella settimana, e quell'output è diventato il bersaglio che la skill doveva centrare.

Crea .claude/skills/release-notes/SKILL.md nel tuo progetto: una cartella skills dentro la cartella nascosta .claude, una cartella con il nome della skill e dentro il file della skill. La cartella conta. Un release-notes.md sciolto non si carica affatto, e la documentazione lo indica come prima cosa da controllare.

L'intestazione è fatta di poche righe con etichetta tra due file di trattini, e deve iniziare alla prima riga del file, altrimenti Claude Code la ignora. La nostra aveva un nome, release-notes, e la descrizione che scriverebbe la maggior parte delle persone:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Sotto l'intestazione vanno le istruzioni, in passi numerati, quelli che daresti a un collega appena arrivato. La nostra ne ha cinque: trovare i commit da lunedì, scartare i commit chore e docs, raggruppare per scope dei conventional commit, scrivere una riga semplice per modifica e produrre un blocco con titolo e un breve riassunto in cima. Anthropic consiglia di tenere breve questa parte. Non serve riavviare: Claude Code recepisce una skill nuova o modificata nella sessione in cui sei già.

Provala per nome: scrivi una barra, scegli la skill nel menu, premi invio. In sessioni nuove, la nostra ha letto il log dei commit, ha raggruppato le correzioni per area e ha scritto le note esattamente come volevamo, ogni volta. Il problema è che tu, e tutto il tuo team, dovete ricordarvi il suo nome.

Un collega non scriverà il nome della skill. Aprirà una sessione nuova e chiederà come lo chiederebbe a te. Quindi prova proprio questo: apri una sessione nuova (una conversazione nuova senza niente di caricato) e chiedi il compito con parole tue. Deve essere nuova, perché una skill già usata resta nella conversazione e un test in quella sessione non dimostra nulla.

Abbiamo scritto "what did we ship this week?". Claude ha lanciato da solo il log dei commit e ha scritto un riassunto a modo suo, senza alcun segno della skill. Le risposte non erano male, ma cambiavano da una prova all'altra: una contava da lunedì, un'altra dall'ultimo tag di release e includeva una modifica alla documentazione che la skill avrebbe scartato. Su cinque sessioni nuove, la skill è stata saltata in tutte e cinque.

Cinque prove sono una dimostrazione, non una statistica. Ma una skill che funziona per nome ed è saltata ogni volta a parole nostre non sta facendo il suo lavoro, e dato che ha superato il test per nome del passo due, non penseresti mai di controllare.

Prima di cambiare una parola, fai tre controlli:

1. /skills elenca tutte le skill che la sessione vede. Cerca la tua. La nostra era elencata e attiva, ma il setup contava 277 skill, e diverse skill di plugin corrispondevano a "release" prima della nostra.
2. claude --debug scrive un log dettagliato di ciò che Claude Code carica. Cerca le righe sulle skill. Il nostro mostrava la skill del progetto caricata, e anche un avviso: l'elenco delle skill superava il budget, quindi alcune descrizioni vengono tagliate.
3. claude plugin validate .claude/skills verifica che l'intestazione sia ben formata. Questo conta: un'intestazione rotta lascia comunque girare la skill per nome, ma Claude non riesce più ad abbinarla da solo. La nostra l'ha superato.

Controllo	Cosa ti dice	Il nostro risultato
/skills	La skill è visibile e attiva?	Elencata, attiva (277 skill)
--debug	Si è caricata? L'elenco è tagliato?	Caricata; avviso di elenco oltre il budget
plugin validate	L'intestazione viene interpretata?	Superato

Con il file caricato e l'intestazione valida, la causa è la descrizione. Finché non decide di caricare una skill, Claude non legge le tue istruzioni. Legge una riga per skill, il nome e la descrizione, e le confronta con le tue parole. La nostra diceva "generates changelog documents from repository history"; la richiesta diceva "what did we ship this week". Le due frasi non hanno nessuna parola in comune. Claude non ha mai letto le nostre istruzioni; ha letto una riga, e quella riga non usava le nostre parole.

L'avviso sul budget significa che Claude Code taglia le descrizioni per farle stare, partendo dalle meno usate, e una skill appena creata è la meno usata di tutte. Controlla che la tua sia sopravvissuta: la nostra sì, dato che le richieste con le sue parole la caricavano ancora.

Scrivi la descrizione per il momento in cui qualcuno chiede, non per il file. Di' cosa fa la skill, quando usarla e le parole che le persone scrivono davvero. La nostra è diventata:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

La guida alla scrittura di Anthropic aggiunge una regola: scrivila alla terza persona ("Writes"), mai "I can help" o "You can use this".

Poi provala in una sessione nuova con la stessa richiesta. "What did we ship this week?" ora ha caricato la skill prima che Claude toccasse qualsiasi cosa, e le note sono uscite nel nostro formato, in cinque sessioni nuove su cinque.

Fai anche un riferimento: spegni la skill con uno skill override nel file di impostazioni locale (la nasconde senza cancellarla). Da spenta, Claude è tornato al proprio riassunto; da accesa, la skill si è caricata. A fare la differenza è stata la skill, non la fortuna.

Il limite: una descrizione che corrisponde a troppe cose fa scattare la skill dove non dovrebbe. Aggiungi le parole che usi davvero, non tutte quelle che ti vengono in mente.

Una richiesta ha dimostrato la correzione; una skill su cui un team fa affidamento viene chiesta in tanti modi. Lo skill-creator di Anthropic descrive il test: venti richieste, un misto di quelle che devono caricare la skill e di quasi-errori che non devono. Un quasi-errore suona simile ma è un altro lavoro, come "write a commit message for my staged changes". Esegui ogni richiesta nella sua sessione nuova e annota se la skill si è caricata. Lo script dello stesso skill-creator non vedeva la skill sulla nostra versione di Claude Code, quindi abbiamo eseguito le stesse venti richieste con un breve script nostro.

Descrizione	Richieste da caricare che l'hanno caricata	Quasi-errori che l'hanno caricata
Originale	4 su 10	0 su 10
Riscritta	10 su 10	0 su 10

Prima della riscrittura la skill si caricava solo sulle richieste che contenevano già "release notes", "changelog" o "release": la corrispondenza per parole del passo quattro, in piena vista. Dopo la riscrittura si è caricata su ogni richiesta che doveva caricarla ed è rimasta fuori da ogni quasi-errore.

Per una skill che non deve mai mancare, forzala. Scrivi il suo nome, oppure aggiungi un hook (un piccolo script che Claude Code esegue in un momento fisso, qui a ogni messaggio che invii) il cui output dice a Claude di usare la skill per quel compito. Con l'hook al suo posto, anche la descrizione originale si è caricata sulla richiesta a parole nostre. Il limite: ogni prova di test consuma utilizzo vero e un hook aggiunge una riga a ogni messaggio, quindi riservalo alle poche skill che devono davvero scattare. Rilancia la tua lista ogni volta che cambi la descrizione.

La nostra skill per le release notes ha funzionato ogni volta per nome, è stata saltata in ogni sessione nuova a parole nostre, e una riga riscritta l'ha fatta caricare ogni volta. Il motivo: Claude legge una riga per skill prima di decidere, e la confronta con le tue parole, non con le tue intenzioni.

Una skill vale per un compito che ripeti con un output fisso: note settimanali, la descrizione di una pull request, una checklist di release. Non vale per una domanda occasionale, e non è lo strumento per una regola che deve valere sempre; quello è il lavoro di un hook. Anche un mucchio di skill inutilizzate costa, perché con troppe skill Claude Code comincia a tagliare le descrizioni, dalle meno usate. Una buona descrizione alza le probabilità ma non farà scattare una skill per un lavoro per cui non è nata, e una manciata di prove è una dimostrazione, quindi la tua lista di richieste di test è la vera verifica.

La regola: scrivi la descrizione con le parole che scrivi davvero quando chiedi il compito.