Come testiamo le Claude Skills: il protocollo

Tutto il sito è nato da uno skill che non faceva niente. Fine 2025, uno skill di produttività girava su X con qualche migliaio di stelle alle spalle. Lo abbiamo installato, riavviato Claude Code, digitato esattamente il caso d'uso descritto nel README, e abbiamo guardato Claude rispondere come se lo skill non esistesse. Controllata la directory: file presenti, frontmatter valido. Provata una formulazione diversa. Niente. Lo skill non si è mai attivato in quaranta minuti, e niente sulla pagina del repo lo avrebbe fatto sospettare. Le stelle misurano quanto un README sia entusiasmante. Non dicono nulla su se la cartella sotto funzioni davvero.

Quella sera ci ha lasciato una domanda che non riuscivamo a scrollarci di dosso: se uno skill con così tanta attenzione può essere morto in partenza, come sarà il resto dell'ecosistema? Così abbiamo iniziato a installare skill su una macchina pulita e ad annotare cosa succedeva. La risposta, documentata nei nostri dati sui fallimenti, è che circa metà degli skill della community fallisce prima ancora di essere utile a qualcuno. Questo post è l'altra faccia di quella scoperta: il protocollo esatto dietro ogni verdetto su SkillProof, spiegato con abbastanza dettaglio da poterlo applicare sul tuo skill prima di pubblicarlo.

Il protocollo, passo per passo

Un test completo richiede tra 45 minuti e diversi giorni, a seconda della categoria. Uno skill per documenti si dimostra in una sola sessione; uno skill di weekly-review deve sopravvivere a una settimana vera. In entrambi i casi i passaggi sono gli stessi, e l'ordine conta, perché ognuno fa da filtro per il successivo. Non ha senso valutare l'output di uno skill che non si attiva mai.

Step 0: un ambiente pulito

Ogni test parte da un profilo macchina con directory skill vuota e impostazioni di default di Claude Code. Sembra una formalità finché non ti salva la prima volta. Gli skill interagiscono tra loro: uno può sembrare funzionare perché un altro skill sulla macchina sta silenziosamente facendo il lavoro pesante. Lo abbiamo imparato testando uno skill per proposte su una macchina dove era già installato lo skill docx. L'output sembrava ottimo. Su un profilo pulito, metà del valore è sparito, perché era lo skill per documenti a produrre da sempre il .docx rifinito.

Step 1: installazione seguendo le istruzioni dell'autore

Apriamo il README del repo e lo seguiamo alla lettera. Non "capiamo noi come installarlo". Facciamo esattamente quello che ha scritto l'autore, refusi compresi, perché è esattamente quello che farà ogni utente vero. Se i comandi producono effettivamente ~/.claude/skills/name/name/SKILL.md, una directory di troppo in profondità, quella è un'installazione fallita, anche se chiunque conosca il formato potrebbe sistemarla in dieci secondi. Potremmo sistemarla anche noi. Il punto è che il nuovo arrivato che segue le istruzioni alle 23 non può farlo, e concluderà che gli skill di Claude sono rotti invece che semplicemente un percorso sbagliato.

Tutto quello che il README non menziona conta a suo sfavore: dipendenze non dichiarate, istruzioni scritte per una versione di Claude Code di due release fa. Annotiamo il tempo dal clone allo skill funzionante, e se abbiamo dovuto uscire dal README per arrivarci.

Step 2: la batteria di trigger

Uno skill installato che non si attiva mai è decorazione. Quindi prima di qualsiasi task reale eseguiamo una batteria di cinque prompt: tre formulazioni che dovrebbero attivarlo, due che non dovrebbero.

I tre prompt positivi sono deliberatamente variati. Per uno skill per documenti Word: "trasforma questi appunti in un report che posso mandare come .docx", poi "scrivimi questo contratto come file Word", poi qualcosa di più obliquo come "mi serve questo formattato bene per la revisione legale". Il primo è l'esempio stesso del README. Il secondo usa un vocabolario diverso per la stessa intenzione. Il terzo non nomina mai il formato del file, il che verifica se la description copre il compito e non solo le parole chiave.

I due prompt negativi verificano l'overtriggering, il fallimento di cui nessuno parla. Uno skill per documenti che si attiva quando chiedi "riassumi questo documento" (testo incollato, nessun file coinvolto) sta iniettando istruzioni in conversazioni dove non c'entrano, e la paghi in termini di contesto e di output strani. Uno skill che si attiva su tutto è peggio di uno che non si attiva mai; almeno quello morto è facile da diagnosticare.

Cinque su cinque è un risultato pulito. Sotto quella soglia, annotiamo quali formulazioni hanno fallito; lo schema è di solito diagnostico. Uno skill che si attiva solo con la formulazione esatta del README ha una description scritta come uno slogan invece che come una specifica di trigger.

Step 3: il baseline run

Questo è il cuore del test e il motivo per cui il protocollo esiste. Prendiamo un task reale dal dominio dello skill e lo eseguiamo due volte: una con lo skill installato, una sul modello nudo con lo stesso identico prompt. Poi confrontiamo.

Il confronto è l'unica domanda che conta: l'output con lo skill è chiaramente migliore di quello che Claude produce comunque? Claude è già bravo in un sacco di cose. Uno skill di "miglioramento della scrittura" che compete contro un modello che scrive già bene deve dimostrare un delta, e la maggior parte non ci riesce. Quando abbiamo testato frontend-design, abbiamo eseguito lo stesso brief per una landing page in entrambi i modi. La versione con lo skill aveva una vera type scale e una palette intenzionale; il baseline aveva quel look a gradiente neon che tutti riconoscono. Quel delta ha guadagnato un 10. Quando i due output sono difficili da distinguere, lo skill non ha ragione di esistere, per quanto piacevole sia il suo README.

Gli input reali contano quanto il confronto. Un foglio di calcolo con intestazioni malformate, una cartella di fatture dove un terzo dei file sono scansioni. Le performance su dati demo sono marketing; noi testiamo la versione "martedì pomeriggio" del lavoro, perché è quella che gli affiderai davvero.

Step 4: il controllo incrociato della documentazione

Per ultimo, leggiamo l'intero SKILL.md e tutto ciò a cui rimanda, poi confrontiamo le affermazioni con quello che abbiamo osservato. Il README promette capacità che lo skill non ha? Dichiara le sue dipendenze? C'è qualcosa sepolto a metà file che sembra meno una guida al task e più una prompt injection, o una chiamata di rete che la documentazione non menziona mai?

Questo step segnala forse uno skill su dieci, ma quelli che intercetta sono i più importanti. Uno skill è testo iniettato nel contesto del tuo modello. Leggere ogni riga prima di fidarsi è il minimo, e trattiamo quella lettura come parte del prodotto.

I quattro punteggi, e perché l'output conta doppio

Ogni skill testato riceve quattro numeri, descritti nella nostra pagina di metodologia. La versione breve, con cosa separa un 5 da un 2:

Installa senza intoppi (su 5). Un 5 significa che un nuovo arrivato che segue il README ottiene uno skill funzionante su un setup pulito senza deviazioni. Un 2 significa che alla fine l'abbiamo fatto funzionare grazie a conoscenze che il README non contiene: correggendo percorsi, leggendo il sorgente. Lo skill può essere eccellente; la porta d'accesso è rotta.

Si attiva in modo affidabile (su 5). Un 5 è cinque su cinque nella batteria: tutte e tre le formulazioni positive si attivano, entrambe le negative restano silenziose. Un 2 si attiva solo con la formulazione presa pari pari dal proprio README, oppure si attiva su lavori non correlati, o entrambe le cose. Causa comune in entrambe le direzioni: un campo description scritto per impressionare gli umani invece che per informare il modello.

Output vs. baseline (su 10). Un 9 o un 10 significa che il risultato con lo skill è inequivocabilmente migliore su un task reale, il tipo di differenza che noteresti anche senza una scheda di valutazione. Un 4 significa che abbiamo dovuto strizzare gli occhi. Un 2 significa che il baseline run era altrettanto buono o migliore, cosa che succede più spesso di quanto gli autori vorrebbero credere.

Documentazione e onestà (su 5). Un 5 significa che il README corrisponde alla realtà: affermazioni accurate, dipendenze dichiarate, niente di non rivelato. Un 2 significa promesse che lo skill non può mantenere o comportamenti che la documentazione non menziona mai.

L'output è valutato su 10 mentre tutto il resto è su 5, e quella ponderazione è deliberata: la qualità dell'output vale quanto tutti gli altri criteri messi insieme. I problemi di installazione hanno soluzioni alternative. I problemi di trigger si possono sistemare modificando un solo campo description. Ma uno skill il cui output non batte il baseline è impossibile da sistemare in un modo che conti davvero. Gli altri punteggi misurano se puoi raggiungere il valore. Il punteggio dell'output misura se quel valore esiste.

Due test dal registro: un 24 e un 17

I numeri dicono di più con i test allegati. Eccone uno per ciascun estremo della gamma pubblicata.

Systematic-debugging, dalla collezione Superpowers di Jesse Vincent, ha ottenuto 24 su 25: installazione 5, trigger 5, output 9, documentazione 5. L'installazione consiste in due comandi di plugin che hanno funzionato esattamente come scritto, e la batteria di trigger ha fatto cinque su cinque. Il baseline run è la parte di cui parliamo ancora in conversazione: gli abbiamo dato una race condition che il Claude baseline aveva già "risolto" tre volte, ogni fix un tentativo a caso che spostava il sintomo altrove. Con lo skill caricato, Claude ha smesso di tirare a indovinare. Ha formulato un'ipotesi, scritto un test per verificarla, visto il test fallire, e seguito quel loop finché non ha trovato la vera causa alla radice. La documentazione promette un processo di debug disciplinato ed è esattamente quello che abbiamo visto accadere. È un punto fermo della nostra pagina coding da allora.

Proposal-builder, uno skill della community, ha ottenuto 17: installazione 3, trigger 4, output 7, documentazione 3. Il primo run è stato un fallimento in senso letterale. Appena installato, su un profilo pulito, non riusciva a mantenere quello che il suo README promette: l'output .docx rifinito dipende silenziosamente dall'avere installato lo skill docx, e la formattazione brandizzata dipende da un template per proposte che il README menziona a malapena. Segui le istruzioni alla lettera, come farebbe un nuovo utente, e ottieni un muro di markdown dove dovrebbe esserci una proposta. Una volta installato lo skill complementare e impostato un template, ha assemblato una proposta brandizzata genuinamente utile a partire da note di chiamata e prezzi. La capacità è reale. Il percorso per raggiungerla non è nel README, e i punteggi dicono esattamente questo, fin nei passaggi mancanti descritti nelle note del test.

Quel divario è quello che il conteggio delle stelle non può vedere. Entrambi i repo sembrano competenti dall'esterno. Uno funziona nel momento in cui segui le sue stesse istruzioni. L'altro funziona solo se sai già cosa ha dimenticato di dirti.

Cosa significa un verdetto

I punteggi confluiscono in uno di tre verdetti. Quello di mezzo confonde le persone, quindi cerchiamo di essere precisi.

Pass significa che lo skill si è installato seguendo le istruzioni dell'autore, si è attivato correttamente, e ha battuto il baseline senza skill su un task reale. Dei 73 skill nel catalogo, 35 portano questo verdetto.

Works with setup significa che lo skill offre valore reale, ma non appena installato. Serve uno skill complementare o un passaggio di configurazione prima, e la scheda dice quale. Dieci skill si trovano qui, e il verdetto non è un eufemismo per "fallito". Alcuni skill richiedono configurazione per design: uno skill per le linee guida di brand è pensato per essere inutile finché non inserisci la tua palette e la tua voce, e uno skill per la revisione delle pipeline non può revisionare una pipeline che non vede. Il verdetto esiste per farti sapere cosa compra un'onesta mezz'ora di configurazione prima che tu la spenda.

In test queue significa che abbiamo elencato lo skill perché sembra promettente ma non abbiamo finito di testarlo. Non è implicato nessun verdetto in un senso o nell'altro; 28 skill sono in attesa. Anche gli skill che falliscono il test in modo netto non vengono cancellati in silenzio: le note del test dicono cosa abbiamo eseguito e cosa si è rotto, perché un fallimento documentato è più utile per te di un vuoto nel catalogo.

Ritestare, perché Claude continua a cambiare

Un verdetto è una fotografia, e il terreno sotto si muove. Gli skill poggiano su un modello, e i modelli vengono aggiornati. Una description che si attivava in modo affidabile in una release di Claude Code può iniziare a fallire nella successiva, perché l'attivazione dipende da come il modello legge le description, e quella lettura cambia. Il drift non è un'ipotesi teorica; abbiamo visto uno skill affidabile iniziare a ignorare una delle sue tre formulazioni positive dopo una release, senza che nemmeno un carattere dello skill fosse cambiato.

Quindi ogni scheda porta una data di test e la versione di Claude Code, e le release principali rimettono l'intera lista dei pass in coda per il retest, partendo dagli skill più installati. Quando un verdetto cambia, la scheda cambia. Una data di test datata è il tuo segnale per soppesare il verdetto di conseguenza; è il costo onesto del testare contro una piattaforma in movimento.

Cosa non testiamo, e dove il metodo è debole

Un protocollo che non puoi criticare è un protocollo che nessuno ha descritto onestamente. I limiti noti:

I task di esempio non possono coprire ogni uso. Eseguiamo uno o due task reali per skill, scelti per essere rappresentativi, e uno skill che brilla sul nostro foglio di calcolo da 40.000 righe potrebbe comunque inciampare sul tuo da 400.000. Il verdetto è una prova, mai una garanzia.

Il punteggio della documentazione si appoggia al giudizio di un singolo tester. Leggere un SKILL.md per valutarne l'onestà è più vicino all'editing che alla misurazione, e due lettori attenti possono soppesare diversamente la stessa frase vaga. Pubblichiamo le note del test in parte proprio perché tu possa verificarci.

Non testiamo su scala né su orizzonti lunghi. Una macchina pulita, giorni e non mesi. Il degrado lento e i workflow che coinvolgono più skill contemporaneamente sono al momento fuori dalla portata del metodo.

La revisione di sicurezza è una lettura, non un audit. Controlliamo chiamate di rete non dichiarate e istruzioni dalla forma di injection, ma un malintenzionato determinato potrebbe far passare qualcosa attraverso una lettura manuale. Considera il nostro punteggio di documentazione come un filtro, e mantieni la guardia alta per qualsiasi cosa tocchi le credenziali.

E anche il baseline si muove. "Batte Claude nudo" significa Claude nudo alla data del test; mentre il modello di base migliora, alcuni skill che oggi passano vedranno il loro delta ridursi verso zero. Un altro motivo per cui il retest non è opzionale.

Applicare il protocollo al tuo skill

Se stai per pubblicare uno skill, una versione condensata di questo richiede circa un'ora e ti mette avanti a metà dell'ecosistema.

1. Profilo pulito. Directory skill vuota, impostazioni di default. La tua macchina di tutti i giorni nasconde i tuoi bug.
2. Installa solo dal tuo README. Meglio ancora: consegna il README a qualcuno che non ha mai visto il repo e osserva. Ogni domanda che fa è una frase mancante.
3. Esegui la batteria dei cinque prompt. Tre formulazioni che dovrebbero attivarlo, inclusa una che non usa mai le tue keyword, più due prompt adiacenti che non dovrebbero attivarlo. Correggi i fallimenti riscrivendo il campo description, non aggiungendo avvertenze al README.
4. Fai il confronto con il baseline. Stesso task, con e senza il tuo skill. Se non riesci a distinguere gli output, ripensa a cosa serve lo skill prima di pubblicarlo.
5. Rileggi il tuo SKILL.md da scettico. Ogni affermazione che non puoi dimostrare, tagliala. Ogni dipendenza, dichiarala.
6. Fai il lint del formato. Gli errori di frontmatter sono la categoria di fallimento più prevenibile che vediamo, e un validatore li intercetta in pochi secondi.

FAQ

Quanto tempo serve per testare uno skill di Claude?

Il self-test condensato richiede circa un'ora. Il nostro protocollo completo va dai 45 minuti per uno skill semplice per documenti fino a una settimana per skill il cui valore emerge solo nel tempo, come gli skill di weekly-review. La batteria di trigger richiede minuti; il confronto con il baseline è dove vanno le ore.

Posso testare uno skill senza una seconda macchina?

Sì. Serve un profilo pulito, non hardware pulito. Punta Claude Code su una directory skill vuota (o sposta la tua da parte) e ottieni l'isolamento che conta: nessun altro skill in competizione per i trigger, nessuno che copre silenziosamente quello sotto test.

Qual è il motivo più comune per cui gli skill falliscono il test?

Un output che non batte il baseline, in circa il 35% dei fallimenti, con le installazioni rotte subito dietro al 30%. I fallimenti di installazione fanno più male perché sono i più economici da prevenire: l'autore non ha mai seguito il proprio README su una macchina che non era la sua.

Come faccio a far testare e elencare il mio skill su SkillProof?

Invialo qui con il link al repo. Entra nella coda di discovery, viene selezionato per trazione e adeguatezza alla categoria, poi passa attraverso il protocollo descritto in questa pagina. Esegui prima il self-test e le tue probabilità di ottenere un verdetto pass aumentano, perché intercetterai gli stessi difetti che intercetteremmo noi.

Il protocollo non è geniale. È una macchina pulita, un README preso alla lettera, cinque prompt, un confronto onesto. Quello che lo fa funzionare è che nessun altro nella filiera fa nemmeno questo: gli autori testano sulla propria macchina, e le stelle misurano l'entusiasmo. Il divario tra queste due cose è dove viveva quello skill di produttività morto di fine 2025. Continuiamo a colmarlo, un'installazione alla volta.