La skill di Claude non si attiva? Risolvi in 6 controlli

Hai installato una skill, hai chiesto a Claude di fare la cosa per cui la skill esiste, e Claude è andato avanti come se la skill non esistesse. Nessun errore, nessun warning, niente da greppare. Solo silenzio.

Lo vediamo di continuo. SkillProof installa e testa ogni skill del catalogo su una macchina pulita, e il mancato trigger è il singolo difetto più comune che troviamo. È anche il più risolvibile: quasi ogni segnalazione "la skill non funziona" nei nostri log di test risale a una di sei cause, e cinque si escludono in meno di un minuto.

Parti dalla checklist. Il resto dell'articolo espande ogni controllo con sintomo, causa e fix.

La checklist da 30 secondi

1. Cartella giusta? Il file deve stare in ~/.claude/skills/<skill-name>/SKILL.md, una cartella per skill, nome file esattamente SKILL.md.
2. Hai riavviato? Claude scansiona le skill all'avvio della sessione. Le modifiche fatte a metà sessione sono invisibili finché non riavvii.
3. Collisione di nomi? Due skill con lo stesso name si oscurano a vicenda. Ne sopravvive solo una.
4. Description troppo vaga? Se la description non menziona quello che gli utenti chiedono letteralmente, Claude non fa mai il match. È la causa numero uno.
5. Frontmatter valido? Un solo carattere YAML rotto rende l'intera skill invisibile, in silenzio.
6. Skill in conflitto? Un'altra skill installata con una description sovrapposta potrebbe star vincendo il match.

Se tutti e sei i controlli passano e la skill si attiva ma l'output non cambia, è un fallimento diverso. Salta a quando si attiva ma non fa nulla.

Controllo 1: la skill è nella cartella sbagliata

Sintomo. La skill non compare mai quando chiedi a Claude "che skill hai installate?". Come se non l'avessi mai copiata.

Causa. Claude guarda solo in posti precisi: ~/.claude/skills/ per le skill personali e .claude/skills/ dentro un progetto per quelle di progetto. Al loro interno il layout è rigido: una cartella per skill, contenente un file chiamato esattamente SKILL.md. Gli errori che vediamo più spesso quando installiamo skill della community per testarle: copiare l'intero repo clonato (così il percorso diventa skills/some-repo/skills/pdf-helper/SKILL.md, un livello di troppo), buttare SKILL.md direttamente in ~/.claude/skills/ senza la sua cartella, e skill.md minuscolo, che alcuni filesystem perdonano e altri no.

Fix. Verifica da terminale:

ls ~/.claude/skills/*/SKILL.md

Ogni skill che ti aspetti dovrebbe stampare esattamente una riga. Se una skill manca o il suo percorso ha annidamenti extra, sposta la cartella così che SKILL.md stia un livello sotto skills/. La nostra guida all'installazione mostra il layout corretto per ogni piattaforma.

Controllo 2: non hai riavviato

Sintomo. La struttura delle cartelle è corretta, l'hai sistemata due minuti fa, e Claude continua a non vedere la skill nella stessa conversazione.

Causa. La discovery delle skill avviene una volta sola, all'avvio. Claude legge il frontmatter di ogni SKILL.md che trova e tiene quell'indice per la sessione. Una skill aggiunta, rinominata o modificata a metà sessione non esiste, per quanto riguarda la sessione in corso.

Fix. In Claude Code, esci e apri una sessione nuova. Nell'app desktop, chiudi del tutto con Cmd+Q su macOS (chiudere la finestra non conta) e riapri. Questo controllo è così economico da escludere che lo facciamo prima di qualsiasi debugging più profondo, come faresti un power-cycle del router prima di chiamare il provider.

Controllo 3: una collisione di nomi sta oscurando la tua skill

Sintomo. Hai installato la skill, la cartella è giusta, hai riavviato, e la lista delle skill mostra o niente di nuovo o una skill diversa che risponde allo stesso nome.

Causa. I nomi delle skill devono essere univoci. Se una skill personale e una di progetto condividono il name, o due pack installati includono entrambi una skill chiamata seo-audit, una oscura l'altra senza alcun avviso. Ci siamo cascati anche noi nel lavoro sul catalogo: due pack di marketing installati fianco a fianco hanno prodotto un duplicato silenzioso, e quella che volevamo non si è mai caricata.

Fix. Cerca i duplicati:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Qualsiasi output significa collisione. Rinomina la cartella e il campo name della copia che controlli, riavvia e ricontrolla la lista.

Controllo 4: la description non dice mai quando attivarsi

Sintomo. La skill compare nella lista delle installate. Chiedila per nome e funziona benissimo. Chiedi il task con parole tue e non succede niente.

Causa. Questo è il problema grosso, e merita una sezione dedicata, quindi ecco la versione corta: Claude decide se caricare una skill leggendo solo il suo campo description e confrontandolo con la tua richiesta. Se la description dice cos'è la skill invece di quando usarla, il match non avviene mai. La skill non è rotta. È senza pubblicità.

Fix. Riscrivi la description intorno alle frasi che gli utenti digitano davvero. L'approfondimento più sotto mostra tre pattern di fallimento reali e le loro riscritture.

Controllo 5: il frontmatter non è valido

Sintomo. Cartella corretta, restart fatto, nessuna collisione di nomi, e la skill continua a non comparire affatto nella lista. Sembra il controllo 1, ma il percorso è a posto.

Causa. Il blocco YAML in cima a SKILL.md non è stato parsato, e una skill con frontmatter non parsabile viene semplicemente saltata. I soliti colpevoli dalle nostre note di test: un --- di chiusura mancante, un due punti non quotato dentro la description ("Use for: reports" rompe il parser), virgolette curve incollate da un blog o da un Google Doc, tab usati per l'indentazione, e un name che viola le regole di formato (solo lettere minuscole, cifre e trattini, massimo 64 caratteri; le description hanno un tetto di 1024).

Fix. Apri il file e passa il blocco a occhio, o salta direttamente l'occhio: incollalo nel nostro validator per le skill e ti segnala subito errori di parsing, violazioni di formato e contaminazione da virgolette curve. Se il frontmatter parsa e la skill continua a nascondersi, torna al controllo 1, perché a quel punto è quasi sempre il percorso.

Controllo 6: un'altra skill sta vincendo il match

Sintomo. Chiedi il task e una skill si attiva, solo che non è la tua. Oppure il comportamento cambia in un modo che corrisponde alle istruzioni di un'altra skill.

Causa. Quando più description coprono plausibilmente una richiesta, Claude sceglie quella che sembra la più adatta, e una description più ampia e sicura di sé tende a battere una più ristretta. Installa una skill generica da "writing assistant" accanto al tuo "release notes formatter" e la generalista può inghiottirsi ogni richiesta di scrittura, note di rilascio incluse.

Fix. Affila entrambe le description così che i loro territori non si sovrappongano, e aggiungi esclusioni esplicite. Una riga come "Do NOT use for release notes or changelogs" nella description della generalista è rozza e funziona. Se la skill che disturba non è tua, disabilitala mentre testi la tua, poi decidi se ti servono davvero entrambe.

Perché le description falliscono: l'approfondimento

Testiamo ogni skill che pubblichiamo, e i problemi di trigger sono il motivo numero uno per cui le skill prendono punteggi bassi nelle nostre recensioni. Non script rotti, non istruzioni scadenti. Description che non vengono mai matchate.

I meccanismi spiegano perché. All'avvio Claude carica solo il name e la description di ogni skill, un centinaio di token circa. Il corpo, per quanto brillante, resta su disco finché la description non vince un match contro la tua richiesta. La description è un pitch di vendita consegnato a un modello, e la maggior parte degli autori la scrive come l'etichetta di un museo.

Ecco i tre pattern che penalizziamo più spesso, con le riscritture che li hanno sistemati nei nostri retest.

Pattern 1: l'etichetta modesta.

description: Helps with documents.

Niente qui si collega a qualcosa che un utente digiterebbe. Confrontala con la skill DOCX di Anthropic, che ha superato i nostri test di trigger al primo colpo. La sua description nomina il formato di file, le azioni e le formulazioni che dovrebbero attivarla. La riscrittura che segue la stessa logica:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Pattern 2: il nome interno.

description: Runs the acme-formatter pipeline with corporate config.

Questa descrive l'implementazione. Nessun utente chiede a Claude di "run the acme-formatter pipeline"; chiede di "ripulire questo report prima di mandarlo a un cliente". La riscrittura traduce la skill nel vocabolario dell'utente:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Pattern 3: la coperta ingorda.

description: Use for any writing task.

Il fallimento opposto. Questa matcha tutto, il che significa che collide con ogni altra skill vicina alla scrittura e si attiva quando non dovrebbe, e gli utenti la disabilitano entro una settimana. La riscrittura restringe la pretesa e recinta i bordi:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

Il test che applichiamo in fase di review: leggi solo la description e chiediti "se un utente digitasse la sua richiesta in modo naturale, queste parole la matcherebbero?". Scrivi in terza persona, dichiara cosa fa la skill e quando si applica, e includi i sostantivi che la gente usa davvero. Se stai scrivendo una skill da zero, la nostra guida all'authoring copre il tema più in profondità, e la Skill Creator di Anthropic genera di default description che superano questo test.

Come testare i trigger per bene

La maggior parte delle persone testa una skill nominandola: "usa la skill delle fatture su questo". Non prova nulla, perché nominare una skill bypassa del tutto il match sulla description. È come testare un rilevatore di fumo premendo il pulsante di test e concludere che la casa è ignifuga.

Testa come chiederebbe un utente, ogni volta in una sessione fresca. Per una skill di estrazione fatture, tre formulazioni che dovrebbero attivarla:

• "Tirami fuori i totali da questi PDF di fatture."
• "Ho 30 fatture dai fornitori, mettimi importi e date in una tabella."
• "Estrai le voci di dettaglio da questa bolletta."

E due che non dovrebbero:

• "Riassumimi questo PDF." (Lavoro PDF generico; territorio di un'altra skill.)
• "Scrivi un'email con la fattura a questo cliente." (Comporre, non estrarre.)

Se una formulazione che dovrebbe attivarla non fa nulla, chiedi direttamente a Claude: "Quale delle tue skill installate useresti per questa richiesta, e perché?" La risposta ti mostra il ragionamento del match, e di solito punta dritto al punto debole della description. Se le formulazioni che non dovrebbero attivarla la attivano comunque, hai una coperta ingorda e ti servono esclusioni. È esattamente il protocollo che eseguiamo nei test di catalogo, ed è la stessa disciplina che insegna la skill Systematic Debugging: prima riproduci, una variabile alla volta, credi alle prove.

Quando si attiva ma non fa nulla

Supponiamo che la skill si attivi davvero. Puoi confermarlo chiedendo a Claude a metà conversazione se una skill si è caricata per la richiesta, e te lo dirà. Ma l'output sembra identico a prima che installassi qualsiasi cosa.

Non è un problema di trigger, e niente di quanto sopra lo risolverà. È un problema di corpo: le istruzioni dentro la skill sono troppo vaghe per cambiare il comportamento, o la skill referenzia file inclusi che non esistono ai percorsi che si aspetta, o chiama uno script le cui dipendenze non sono mai state dichiarate. La description ha fatto entrare la skill dalla porta e il contenuto è crollato una volta dentro.

Nei nostri test questo è l'altro grande secchio di fallimenti, più o meno l'immagine speculare dei difetti di trigger, ed è il motivo principale per cui circa metà delle skill della community fallisce i nostri test. Il discriminatore rapido: se il comportamento non è cambiato affatto, sospetta il trigger; se è cambiato ma male o a metà, sospetta il corpo. Debugga di conseguenza, perché i fix non si sovrappongono.

Trappole di piattaforma

Il formato delle skill è identico ovunque, ma la discovery no, e una skill che funziona in un posto può sembrare morta in un altro.

Claude Code legge cartelle su disco: ~/.claude/skills/ per le personali, .claude/skills/ per progetto. Si caricano entrambe; le collisioni di nomi tra i due scope si risolvono con un solo vincitore (controllo 3). Riavvia la sessione dopo ogni modifica.

Claude Desktop non legge le tue cartelle skills. Le skill si caricano come zip dalle Settings, sotto Capabilities, e lo zip deve contenere la cartella della skill al livello superiore, non il SKILL.md nudo né una directory contenitore. Una skill che si attiva benissimo in Claude Code sarà semplicemente assente su Desktop finché non la carichi lì separatamente.

claude.ai usa lo stesso percorso di upload di Desktop, con due modi extra di perdere: le skill richiedono la funzione di esecuzione codice abilitata sul tuo piano, e gli admin del workspace possono disabilitare le skill a livello di organizzazione, nel qual caso nulla di ciò che carichi si attiverà mai e nessun errore te lo dirà. Chiedi al tuo admin prima di passare una serata a riscrivere description.

Un'altra trappola cross-platform: una skill scritta per Claude Code che invoca git o legge file locali del progetto si attiverà correttamente su claude.ai e poi fallirà dentro la sandbox. È un problema di corpo travestito da problema di piattaforma.

Quando smettere di debuggare

Se la skill è tua, continua, perché ogni fix qui sopra è permanente e il validator più il test delle cinque formulazioni ti porteranno a destinazione. Se è una skill di terzi e hai bruciato più di venti minuti sul campo description di qualcun altro, è legittimo sostituirla con una che questa checklist l'ha già passata: ogni skill nelle nostre liste best-of ha superato i test di trigger su una macchina pulita prima della pubblicazione.

FAQ

Come confermo che una skill è davvero installata?

Chiedi a Claude "che skill hai installate?" in una sessione fresca. Se la tua skill non è nella risposta, il problema è la discovery (controlli 1, 3 e 5: cartella, collisione, frontmatter), non il trigger. Se è in lista ma non si attiva mai, il problema è la description (controlli 4 e 6).

Posso semplicemente forzare la skill nominandola?

Sì. "Usa la skill docx per scrivere questo memo" carica la skill direttamente, ed è un workaround accettabile mentre debuggi. Non è un fix, però: una skill che devi evocare per nome ogni volta è una skill con la description rotta, e ti dimenticherai di evocarla esattamente quando conta.

Perché la mia skill funziona in Claude Code ma non su Desktop o claude.ai?

Percorsi di discovery diversi. Claude Code legge cartelle su disco; Desktop e claude.ai vedono solo le skill caricate dalle Settings come zip con la cartella della skill al livello superiore. Su claude.ai, conferma anche che l'esecuzione di codice sia abilitata e che l'admin del workspace non abbia disabilitato le skill del tutto.

Installare troppe skill rompe i trigger?

Non direttamente. Cinquanta skill costano qualche migliaio di token di metadati, che è poco. Il rischio vero è la sovrapposizione: più description installi, più è probabile che due reclamino lo stesso territorio, e allora a volte vince quella sbagliata (controllo 6). Installa per necessità e pota le skill che non si attivano mai.

La mia skill ieri si attivava e oggi no. È normale?

Ogni tanto, sì. Il matching è guidato dal modello, non da una regex, quindi una description borderline si attiverà su una formulazione e ne mancherà una quasi identica. Se una skill è instabile invece che morta, trattala come una description debole: aggiungi al campo description le frasi esatte che sono state mancate, riavvia e ritesta. Le skill affidabili si attivano su ogni formulazione ragionevole, ed è per questo che testiamo con cinque, non con una.