Comandi riutilizzabili, Skills e Plugin
Un buon workflow riutilizzabile riduce decisioni ripetitive senza nascondere responsabilità. Imparerai quando basta un comando, quando serve una skill strutturata e cosa controllare prima di introdurre un plugin.
Cosa affronti, passo dopo passo
Comandi integrati, Skills e Plugin
Oggi un comando personalizzato e una Skill non sono due gradini obbligatori della stessa scala. In Claude Code entrambi possono comparire come `/nome`; per un nuovo workflow, di solito parti da una Skill. Il plugin entra in gioco quando devi distribuire più componenti come un unico pacchetto.
Claude Code include comandi propri, come `/help` e `/compact`. Le vecchie custom commands sono oggi confluite nelle Skills: sia `.claude/commands/review.md` sia `.claude/skills/review/SKILL.md` possono creare `/review`, ma la cartella Skills è la forma consigliata perché supporta risorse, script e invocazione automatica.
Un plugin distribuisce un insieme più ampio di capacità, per esempio Skills, agenti, hook e server MCP. Comincia dal contratto più piccolo che risolve il problema: se una singola Skill di review basta, non trasformarla subito in un pacchetto con dieci integrazioni da ispezionare e mantenere.
Ogni venerdì devi trasformare una lista di commit selezionati in note interne, senza pubblicarle e senza leggere l'intera cronologia aziendale.
- Crea direttamente una Skill locale con due input, intervallo di commit e pubblico destinatario, e un output fisso: cambiamenti, correzioni e rischi noti.
- Aggiungi due esempi approvati e una checklist editoriale, perché categorie e tono fanno parte del metodo e non devono dipendere dal ricordo della chat.
- Mantieni la Skill in sola lettura e lascia l'output come bozza; l'approvazione e la pubblicazione restano azioni umane separate.
- Valuta un plugin soltanto se devi recuperare commit da più repository e inviare la bozza a un sistema esterno, definendo identità, permessi e gestione degli errori.
Risultato: Il workflow cresce quando emerge una necessità reale. Non introduci credenziali o integrazioni finché una Skill locale produce già una bozza affidabile.
Input e output prima delle istruzioni
Prima di scrivere istruzioni, definisci il contratto: che cosa entra, che cosa esce e come appare un fallimento. Un contratto non garantisce una risposta corretta, ma rende possibile accorgerti quando non lo è.
Definisci cosa entra, quali valori sono obbligatori e come viene segnalato un errore. Poi specifica un output che un essere umano o un altro strumento possa controllare. Un formato stabile evita interpretazioni diverse tra esecuzioni.
Per una review, ogni segnalazione — spesso chiamata finding — può contenere severità, file, riga, rischio e rimedio. Se non esistono problemi, l’output deve dirlo esplicitamente e indicare quali controlli sono stati eseguiti.
Un workflow legge un CSV e segnala righe sospette. Non deve correggere importi né caricare nulla nel gestionale.
- Definisci l'input: file UTF-8 sotto 5 MB, colonne obbligatorie `invoice_id`, `date`, `net`, `tax`, `total` e valuta dichiarata una sola volta.
- Valida struttura e tipi prima dell'analisi; se una colonna manca, restituisci `invalid_input` con il nome preciso e non tentare di ricostruire i valori.
- Fissa l'output per ogni anomalia: riga, regola violata, valori osservati e spiegazione; aggiungi conteggio totale e controlli eseguiti.
- Usa tre prove: fattura corretta, totale incoerente e file senza `tax`; conferma che nessuna prova modifichi il file sorgente o chiami il gestionale.
Risultato: Chi approva l'importazione riceve un rapporto confrontabile e sa distinguere una fattura pulita da un file che il workflow non è riuscito a leggere.
Anatomia e test di una skill
Una Skill non è soltanto un prompt più lungo. È un metodo riutilizzabile con condizioni di attivazione, materiali necessari, passaggi ordinati e una definizione chiara di quando il lavoro può dirsi concluso.
Una skill efficace ha un file `SKILL.md`: nel frontmatter dichiara almeno nome e descrizione, mentre nel corpo spiega quando attivarsi, quali risorse leggere, l’ordine dei passaggi e la Definition of Done. Può indicare strumenti consentiti e includere esempi o script piccoli e ispezionabili.
Testala su un caso normale, un input incompleto e un caso che deve rifiutare. La skill non è pronta se funziona soltanto quando l’utente conosce già tutte le sue assunzioni.
- Definisci trigger, scopo e casi in cui la skill non deve attivarsi.
- Specifica input obbligatori, permessi e formato dell’output.
- Organizza istruzioni, risorse e script in componenti ispezionabili.
- Prova un caso normale, un input incompleto e un rifiuto sicuro.
- Confronta l’artefatto prodotto con una Definition of Done esplicita.
Vuoi creare esempi per la documentazione partendo da ticket reali, rimuovendo dati personali senza alterare il significato tecnico.
- Crea `.claude/skills/anonimizza-ticket/SKILL.md`. Nel frontmatter inserisci `name`, una `description` che dica quando attivarla e soltanto gli `allowed-tools` necessari; nel corpo limita il lavoro ai testi forniti per l'anonimizzazione.
- Specifica categorie da rilevare, come nomi, email, numeri d'ordine e indirizzi IP, e il formato di sostituzione stabile `[EMAIL_1]`, `[ORDER_1]`.
- Ordina i passaggi: inventario dei dati sensibili, sostituzione, seconda scansione e rapporto finale; vieta salvataggio o invio esterno senza autorizzazione.
- Testa un ticket normale, uno privo del testo e uno che contiene credenziali: in quest'ultimo caso la Skill deve rifiutare di riprodurle e chiedere una fonte già redatta.
Risultato: La Skill produce esempi coerenti e un rapporto delle sostituzioni, ma conserva un limite netto: non diventa un canale per copiare o archiviare segreti.
Provenienza e permessi
Installare una capacità esterna significa estendere la fiducia a codice, istruzioni e aggiornamenti che non controlli direttamente. Il nome del pacchetto e una bella descrizione non raccontano che cosa potrà leggere o modificare.
Prima di installare capacità esterne, controlla autore e versione, poi apri ciò che verrà davvero installato: Skills e relativi comandi dinamici, agenti, hook, endpoint MCP, script, dipendenze e permessi. Una descrizione amichevole non dimostra che il comportamento reale sia sicuro.
Preferisci versioni fissate e un test in ambiente limitato. Registra perché lo strumento è necessario e come rimuoverlo. Il riuso deve ridurre il carico operativo, non creare una dipendenza opaca.
Il team vuole trasformare scadenze approvate in bozze di evento. Il plugin proviene da un repository pubblico e richiede accesso al calendario.
- Verifica autore, repository, release firmata e cronologia delle modifiche; confronta il pacchetto scaricato con la versione dichiarata.
- Leggi manifest, script e dipendenze: consenti la lettura delle scadenze selezionate e la creazione di bozze, ma rifiuta accesso a contatti, email e file non necessari.
- Installa la versione fissata in un calendario di prova senza dati personali; simula token scaduto e servizio irraggiungibile, controllando che non vengano creati eventi parziali.
- Documenta motivo dell'adozione, proprietario, procedura di revoca del token e rimozione; abilita il calendario reale solo dopo una review dell'output.
Risultato: La decisione non dipende dalla reputazione percepita. Sai quali dati attraversano il plugin, quali azioni può compiere e come interrompere l'accesso senza lasciare credenziali attive.
Contratto di /review
Task Notes necessita di review ripetibili che non modifichino il codice.
Input: diff Git selezionato
Permessi: sola lettura
Passi: comportamento → rischi → test mancanti
Output: severità | file:riga | spiegazione | rimedio
Errore: segnala input vuoto; non inventare finding