L’8 aprile 2026 ho cancellato tredici skill in un pomeriggio. Ne avevo più di trenta fra terminale e desktop, con ridondanze pesanti, e il registro delle decisioni del mio Twin lo dice con quelle parole (voce del 2026-04-08).
1. Perché un prompt non basta
Il problema non era l’ordine. Era che ogni volta ripartivo da capo, e il risultato seguiva l’umore della giornata.
L’ordine però c’entrava poco: il punto era che ogni volta riscrivevo a memoria le stesse istruzioni, dimenticavo metà dei vincoli, e la qualità finiva per dipendere da come mi ero alzato. Un prompt funziona benissimo il giorno in cui lo scrivi, perché quel giorno hai in testa tutto il contesto, e molto peggio tre settimane dopo, quando non lo trovi più e lo rifai a memoria.
Oggi sul mio computer ci sono 29 cartelle di skill: 17 scritte da me, 3 adattate da un repo esterno e 9 di terze parti. Tutte e 17 le mie portano un numero di versione nella scheda anagrafica in cima al file, il front-matter, e una tabella che ne segna la storia, il changelog, per 70 righe in tutto (conteggio del 15 settembre 2026, con la stessa regola di riconoscimento del mio script di audit). Il giorno prima non era così: due esistevano e basta, senza versione né storia, e il capitolo 7 racconta come le ho scoperte.
2. Che cos’è una skill, in concreto
La delusione è parte del punto: dentro non c’è niente di magico. C’è però una riga che un prompt non può avere, e la skill del mio design system ce l’ha scritta contro sé stessa.
È un file Markdown, e la delusione è tutta lì. Un front-matter in cima (nome, trigger, versione, autore, data dell’ultima modifica) e sotto il corpo: filosofia, perimetro, passi operativi, la sezione che dice con quali altre skill interagisce e la tabella di versione e manutenzione. È lo stesso schema che Anthropic descrive per le Agent Skills: metadati sempre caricati, istruzioni caricate solo quando la skill si attiva, risorse caricate solo se servono davvero.
Chi lavora con ChatGPT ha la stessa cosa nelle istruzioni personalizzate, nei GPT e nei Progetti; chi usa Gemini nei Gem. Cambia il nome, non il principio: una procedura scritta che il modello carica quando serve.
La differenza con un prompt sta tutta lì dentro: un prompt dice cosa vuoi, una skill mette per iscritto anche quando non si applica. La skill del mio design system, per dire, ha una riga di changelog che ammette una cosa scomoda: il sito era già a 0,86 mentre la skill teneva ancora scritto 0,78 (skills/nick-brand-ui/SKILL.md, changelog v2.6 del 20 agosto 2026). Un prompt non può contenere una frase così, perché non ha un ieri.
3. Il momento in cui si attiva
Il pezzo più importante del sistema non è una procedura ma un promemoria: e nessuno lo guarda finché non manca.
Una skill che devi ricordarti di invocare è una skill morta, e per settimane sono stato io il collo di bottiglia della mia stessa AI, il punto in cui tutto doveva passare per la mia memoria. Per questo il pezzo più utile del sistema non è una skill: è un hook, un pezzo di codice che Claude Code registra nelle impostazioni (settings.json) per girare a ogni prompt e proporre le skill quando riconosce il caso, restando muto sul resto. Sono 150 righe di bash con 15 pattern bilingui, che coprono 10 delle mie skill (conteggio del 14 settembre 2026: invariato dal 10, salvo che oggi copre design-agency al posto di ux-ui-pro).
Non impone niente: legge la domanda, riconosce che parla di valutazione di una startup o di unit economics o di un lavoro visivo, e suggerisce le skill che si applicano, perché il riconoscimento è euristico. La decisione resta al modello, e in ultima istanza a me.
La riga migliore di tutto il sistema
Falsi positivi accettabili (es. “decido se andiamo a cena”) → Nick ignora. Falsi negativi sono il problema vero: skill manuale dimenticata = morta.
Sono le righe 101-102 di hooks/skill-router.sh, citate senza cambiare una virgola. Meglio un suggerimento di troppo che il silenzio proprio nel giorno in cui servirebbe.
E una regola sta sopra a tutte: se scatta problem-framing, la skill che mi obbliga a inquadrare il problema prima di risolverlo, quella va invocata per prima, perché un framework di dominio applicato a un problema mal posto produce lavoro elegante sulla domanda sbagliata (stesso file, riga 140).
4. Le skill si citano
Due nomi raccolgono quasi un terzo di tutti i collegamenti, e non è successo per caso: c’è un commit fatto apposta per crearli.
Prese una per una sono procedure; messe insieme diventano un grafo, e il grafo si conta: 77 citazioni da una skill all’altra e 22 coppie che si citano a vicenda, estratte dalla sezione di interazione di ogni file con la stessa regola automatica di lettura che usa il controllo numero 5 del mio auditor (estrazione del 15 settembre 2026; il file con il grafo resta nel repo privato, come spiego nel capitolo 9).
I numeri di versione dipinti sui nodi sono quelli letti nei file il 14 settembre 2026.
I due centri sono problem-framing e critical-quality, il controllo di qualità: dieci skill citano il primo, tredici il secondo. Sono i due varchi da cui passano 23 citazioni su 77, poco meno di un terzo, uno prima (che problema stiamo davvero risolvendo) e uno dopo (questi numeri reggono). Le altre destinazioni scendono in fretta: nick-brand-voice a sette, professional-trader, startup-evaluator e vademecum a cinque ciascuna, design-agency a quattro, poi llm-council, content e nick-brand-ui a tre. Le mie skill guardano anche fuori dal proprio perimetro: sette citazioni verso skill di terzi, dataviz, design-taste-frontend, docx, pdf, pptx, ui-ux-pro-max e webapp-testing, quando serve una competenza che dentro casa non ho scritto.
La reciprocità non è successa da sola. C’è un commit, un salvataggio datato di una modifica al codice, fatto apposta per crearla: si intitola cross-ref bidirezionali e nomina le tre skill collegate in quel giro (repo di configurazione, commit a49904a). È il tipo di lavoro che nessuno vede e che tiene su tutto il resto.
5. Le skill si testano
Una procedura senza casi di prova è un’opinione scritta bene. Tre ce l’hanno, e proprio la meglio scritta è quella che non ho mai rigirato.
Questa è la parte in cui uno stack di procedure smette di essere una collezione di appunti. Tre skill hanno una suite di casi di prova, scritta come si scriverebbe per il codice.
La più seria è quella di problem-framing: 17 casi scritti contro la versione 1.3 della skill, datati 16 giugno 2026 (oggi la skill è alla 1.5 e la suite non è stata rigirata), con la soglia scritta dentro il file, 14 su 17 devono passare perché la skill si consideri operativa (skills/problem-framing/evals/cases.yaml, riga 358). I casi vengono da situazioni vere, astratte quel tanto che basta a poterle scrivere, e per questo la suite resta fuori dai file scaricabili: qui trovi solo la struttura. La seconda è quella di vademecum, 10 casi datati 17 luglio 2026 (skills/vademecum/evals/cases.yaml, righe 11-13); la terza è di professional-trader, una baseline del 2 luglio 2026, 10 su 10 a livello di design.
Onestà: la suite più seria è anche l’unica senza un esito registrato, e il vademecum ha il difetto opposto, otto casi su dieci validati e nessuna soglia scritta (commit dc17fe4).
6. La skill che controlla le skill
Il numero che ripetevo era sbagliato, e me ne sono accorto solo rifacendo il conto per scriverlo qui.
La risposta si chiama skill-auditor, e la sua filosofia sta in una riga.
Una skill che non è verificata è una skill che prima o poi romperà qualcosa. La domanda non è se, ma quando.
(skills/skill-auditor/SKILL.md, righe 23-24). È la stessa domanda che mi faccio quando leggo il marketing intorno agli AI agent: conta cosa fa davvero un sistema, non cosa dice di fare.
I controlli documentati sono dieci, ognuno con la sua scheda. Altri tre stanno nello script e nel documento compaiono solo in due righe di changelog e in una riga di prossima iterazione: tredici in tutto. Sette girano da soli dentro uno script Python (skills/skill-auditor/scripts/audit.py, 455 righe) che non scrive niente su disco.
| Come girano | Quanti | Che cosa guardano |
|---|---|---|
| Da soli, a ogni giro | 7 | front-matter, coerenza fra versione e titolo, sezioni minime, integrità del changelog, riferimenti incrociati, perdita di contenuto fra due versioni, sovrapposizione dei trigger |
| Solo se li chiamo | 2 | lo scostamento dalle versioni originali delle skill non mie |
| A mano | 4 | restano a carico mio |
Tredici controlli definiti, sette automatici nel giro standard (audit.py, conteggio delle funzioni check_). Nel catalogo che mi ero scritto il 4 settembre 2026 li avevo messi come 13 automatici, e non era vero.
E mette per iscritto il proprio perimetro: non opera per nome su docx, pdf, pptx e xlsx, che hanno convenzioni diverse. Questa riga conta: è il motivo per cui nel prossimo capitolo il conto è sulle mie 17 e non sulle 29 cartelle.
7. Il controllo, e cosa trova nelle mie
Il controllo non serve a fare bella figura: serve a sapere dove il sistema è più debole. E il punto in cui passa senza accorgersi di niente è più istruttivo di quello in cui ferma.
Il 14 settembre 2026 alle 15:31 ho fatto girare l’auditor sulle mie 17 skill, in sola lettura (sulle altre dodici cartelle del computer, di terzi o adattate, il conto non ha senso: v. la nota metodologica).
| Le mie 17 skill, alle 15:31 | Quante |
|---|---|
| Operative | 12 |
| Pronta con caveat | 1 |
| Fermate dal controllo | 4 |
Le quattro erano il design system, la skill di pubblicazione, quella di inglese e quella della nota spese. Tre mancavano di una sezione o di un numero di versione (una, quella di inglese, aveva un carattere di troppo in testa al file e il controllo si fermava alla prima riga); nessuna delle quattro era rotta nell’uso. Ma è la quarta la storia interessante.
Il buco che si è spostato
Alle 15:31 il file del design system dichiarava la versione 2.13; il changelog aveva dieci righe, ma non quella della 2.10: un commit del 4 settembre, la deroga del monogramma NG, aveva alzato il numero senza scrivere la riga. Il 10 settembre il buco stava in fondo alla tabella; il 14 stava in mezzo, con tre righe nuove sopra. Il mio Check 4 lo promuoveva comunque: conta le righe, non la continuità, ed è il punto di tutto il capitolo, una regola vale quanto il suo controllo.
L’errore che l’auditor trovava davvero è più istruttivo: le interazioni con le altre skill c’erano, ma sotto un titolo mio, Rapporto con le altre skill, e la procedura si chiama Procedura, non Step. Fermata per il nome di due capitoli, la prova che chi ha scritto la convenzione è il primo a non seguirla. Un ultimo dettaglio, fermo da due mesi: lo script stampava in ogni report auditor skill-auditor v1.1, mentre la skill che lo contiene portava scritto 1.2. Il controllore aveva esattamente il difetto che va cercando negli altri.
La sera stessa
Le ho sistemate in serata, una per una, dieci minuti l’una: il carattere di troppo nel file di inglese, versione e storia alle due che non le avevano, le sezioni mancanti alla skill di pubblicazione, la riga 2.10 recuperata dal commit che l’aveva saltata. E ho sistemato il controllore: adesso riconosce Procedura e Workflow come nomi di una sezione operativa (fermava due skill per il titolo, non per la sostanza) e stampa la versione giusta. Seconda esecuzione alle 22:11: 17 su 17. La prova non è il numero finale, è che ogni riga di changelog scritta quella sera porta la data del 14 settembre 2026: il sistema racconta da solo la giornata in cui è stato corretto.
8. Cosa non funziona ancora
I difetti che si vedono sono quelli piccoli. Quello grosso è che il sistema non sa dire quante volte è servito davvero.
Dei tredici controlli quattro restano a mano e altri due girano solo se li chiamo: dipendono da me e dalla mia memoria. Il buco della 2.10, invece, oggi lo vedrebbe: il 15 settembre ho insegnato al Check 4 a contare la continuità delle versioni (una riga deve seguire la precedente, o aprire un numero nuovo), e provandolo su una copia del file senza la riga 2.10 si ferma e dice quale manca. Un difetto in meno, trovato scrivendo questa pagina. Una suite di prova su tre non ha un esito registrato, e le due che ce l’hanno non hanno una soglia. La latenza del router, dichiarata sotto i 30 millisecondi, è un commento nel codice e non una misura (hooks/skill-router.sh, riga 12).
Il buco più grosso sta altrove: il sistema non tiene traccia di sé stesso. So che l’hook è registrato, non quante volte una skill proposta è stata davvero invocata. La frase che vorrei poter dire, che la qualità non dipende più da come formulo la domanda, oggi non ha un numero che la misuri: resta una tesi appoggiata a un sistema, non un risultato misurato, e la scrivo così finché non lo è. Vale la stessa prudenza sulla sincronizzazione: nei due ambienti, terminale e app, c’è lo stesso nucleo di skill, non lo stesso stack sincronizzato.
9. Cosa scarichi
Due file, e dentro non c’è una riga delle mie procedure: il calco, non il contenuto.
Nessuna delle mie skill esce da qui per intero, e nemmeno una riga di quelle con dati personali. Quello che si scarica sono due file.
La mappa dello stack, in SVG: i nodi sono le skill col loro numero di versione, gli archi le 77 citazioni, tratto pieno per le 22 coppie reciproche e tratteggio per le quattro skill mie che il controllo ha fermato alle 15:31.
Lo scheletro di un SKILL.md vuoto: i nomi delle sezioni e i campi del front-matter, con un commento che spiega a cosa serve ciascuno. È il calco, non il contenuto.
Restano nel repo privato tre cose che ho pensato di allegare e poi no: il file JSON del grafo (elenca skill per skill cosa cita cosa, cioè la mappa del mio modo di lavorare più in dettaglio di quanto voglia renderlo pubblico), i report dell’auditor (i motivi di ogni verdetto riportano pezzi delle descrizioni delle skill, e in due compaiono nomi di società e di procedure interne) e audit.py, che è codice mio che gira sul mio stack. I numeri del caso escono da quei file: li ho scritti qui perché si possano confrontare con la mappa, non perché si possano rifare a casa.
Fonti: conteggi e citazioni misurati il 15 settembre 2026 sulla cartella skills/ e sull’hook skill-router.sh; verdetti dalle esecuzioni di audit.py del 14 settembre (15:31 e 22:11) e del 15 (11:18); l’origine dello stack dal registro delle decisioni del Twin, voce dell’8 aprile 2026.
Come è stata costruita
Nessuno di questi numeri è stimato: escono da quattro passaggi che chiunque abbia una cartella di skill può rifare.
Il conteggio delle cartelle
Le 29 cartelle con un file SKILL.md, contate il 15 settembre 2026 con le stesse regole di riconoscimento dello script di audit: così il testo e il controllo contano allo stesso modo.
Il grafo, con la regola del controllo numero 5
Le citazioni sono estratte dalla sezione INTERAZIONE CON ALTRE SKILL di ogni file, con lo stesso metro del controllo numero 5. Il risultato sta in un file JSON che resta nel repo privato (capitolo 9): la mappa lo disegna, il testo lo cita.
L’auditor, in sola lettura
audit.py è girato tre volte, il 14 settembre 2026 alle 15:31 e alle 22:11 e il 15 alle 11:18, su tutte e 29 le cartelle: non scrive niente su disco e non ha modificato nulla di ciò che stava misurando.
La mappa, disegnata a mano
Un algoritmo di disposizione su 29 nodi produce sovrapposizioni illeggibili: le posizioni sono scritte una per una in uno script Python che legge il JSON e produce insieme SVG e immagine nelle due lingue.
Quello che la macchina non ha deciso
L’AI ha fatto i conteggi, l’estrazione del grafo e il codice del disegno. Il numero da mettere in prima riga l’ho scelto io, e il capitolo 7 è la prova che non l’ho addolcito: alle 15:31 quattro delle mie non passavano il controllo, e una di loro era quella che governa il modo in cui questa pagina è impaginata.
Quattro misure, un giorno solo, e nessun numero stimato: se lo stack cambia, non si aggiorna una cifra a mano, si rigira lo script.
Nota metodologica
Tutte le fonti sono file su un computer, non ricordi. Qui c’è come sono state lette, e i punti in cui i numeri dicono meno di quanto sembri.
Che cosa è stato contato
La cartella skills/, in un repo git privato, letta il 15 settembre 2026. Una skill è una cartella con un file SKILL.md: sono 29. Le skill adattate e quelle di terze parti si riconoscono perché portano scritto un autore, una licenza o un’origine diversi dai miei.
Che cosa è stato eseguito
Un solo comando, audit.py --all, in sola lettura, su tutte e 29 le cartelle, eseguito tre volte: il 14 settembre alle 15:31 e, dopo le correzioni, alle 22:11; il 15 alle 11:18 con il Check 4 nuovo. Il rapporto chiude con un verdetto fra OPERATIVA, PRONTO CON CAVEAT e BLOCCANTI: i verdetti citati nel testo sono quelli, non una mia sintesi. Sul totale dei 29, alle 15:31 uscivano 12 operative, 2 con caveat e 15 BLOCCANTI, ma il 15 non è un numero del mio stack: la skill dell’auditor dichiara di non operare su docx, pdf, pptx e xlsx, e lo script --all quel perimetro non lo applica, così undici dei quindici sono skill di terzi o adattate da un repo esterno che la mia convenzione non l’hanno mai avuta. Il conto che vale è sulle 17 mie: 12, 1 e 4 alle 15:31; 17, 0 e 0 alle 22:11 e ancora il 15. Le altre 12 cartelle danno lo stesso risultato nelle tre esecuzioni.
Dove i numeri dicono meno di quanto sembri
Due avvertenze. La prima è che un verdetto BLOCCANTI non parla di funzionamento ma di convenzione: dice che a un file manca una sezione, una versione o una riga di changelog, non che la skill non lavora. La seconda è che non esiste un registro degli inneschi: so quando l’hook è registrato per girare, non quante volte una skill proposta è stata poi invocata davvero.
Cinque giorni, non uno
Questo caso è la fotografia del 10 settembre 2026, riscritta il 14 sullo stesso metro: nel mezzo design-agency è nata, le tre skill di QA adattate sono entrate e due changelog sono saliti di versione, con le cartelle e le citazioni cresciute di conseguenza (i numeri sono nei capitoli sopra). La sera del 14, dopo le correzioni del capitolo 7, le citazioni sono passate da 67 a 77 e le coppie reciproche da 19 a 22: quattro skill che prima non dichiaravano con chi lavorano ora lo scrivono. Il 15, il giorno in cui questa pagina esce, l’auditor è alla 1.4 e conta la continuità. Il metodo, invece, non è cambiato: si rigira lo stesso comando e si riconta. È la dimostrazione più semplice della tesi di questo caso: se il changelog è vivo, il conto di oggi non è quello di quattro giorni fa, e chi scrive una skill invece di un prompt lo sa perché lo vede scritto, non perché se lo ricorda.
Non è un metodo che consiglio a nessuno, non è un prodotto e non è consulenza. È la descrizione di come tengo in ordine gli strumenti che uso io, su un computer mio, con i difetti che il controllo trova ancora dentro. Chi volesse copiarlo farebbe bene a partire dalla parte noiosa, cioè dal controllo, non dalle procedure.
In chiusura
Un sistema di regole non ti rende bravo, ti rende misurabile.
La prova non è che oggi le mie 17 skill siano a posto: è che il 14 settembre alle 15:31 quattro non lo erano, e l’ho scoperto perché avevo scritto il controllo prima di averne bisogno. Per gli altri casi di come lavoro con l’AI, l’indice è qui. Se vuoi parlarne, scrivimi.
