Quando trasformare un workflow in un plugin di Claude Code

La cartella funziona nel primo progetto. Un collega la copia nel secondo, cambia un percorso e l'hook smette di partire. Nel terzo progetto circolano già due versioni della stessa Skill e nessuno sa quale abbia superato la prova.

È il momento in cui una personalizzazione locale può diventare un plugin di Claude Code. Non perché il nome suoni più tecnico, ma perché ora esistono un comportamento da mantenere, più persone che lo usano e una versione da riconoscere.

La documentazione ufficiale sui plugin separa bene i due casi. La cartella .claude/ è adatta a configurazioni personali, prove rapide e regole legate a un solo progetto. Un plugin serve quando Skill, agenti, hook o server MCP devono viaggiare insieme tra progetti o persone.

Il secondo copia e incolla è il segnale

Un solo uso non basta. Potresti avere una procedura utile solo a quel repository, oppure un esperimento che cambierà domani. Il segnale arriva quando la stessa configurazione viene copiata una seconda volta e la copia crea lavoro di manutenzione.

Prima di creare il pacchetto, confronta le due istanze. Quali file sono identici? Quali valori dipendono dal progetto? Quali comandi funzionano solo sulla tua macchina? La parte comune può entrare nel plugin. Percorsi, credenziali e scelte locali devono restarne fuori.

Questa separazione impedisce al pacchetto di diventare una fotografia del primo ambiente. Un plugin riusabile contiene il contratto comune. Il progetto fornisce i dati e le impostazioni che cambiano.

Quando lasciare la configurazione standalone

La configurazione standalone resta la scelta giusta quando il comportamento vale in un solo progetto, lo usa una sola persona o non ha ancora superato una prova ripetibile. È anche il posto adatto per sperimentare senza promettere stabilità a nessuno.

Tre esempi:

• una Skill richiama una procedura interna che esiste soltanto nel repository corrente;

• un hook usa uno script con percorsi locali non ancora parametrizzati;

• un subagent è in prova e cambia responsabilità dopo ogni incarico.

Trasformarli subito in plugin aggiunge un livello di distribuzione a qualcosa che non è ancora stabile. Il costo compare al primo aggiornamento: devi spiegare la versione, evitare doppioni e capire chi ha ricevuto la modifica.

Il test in quattro domande

Prima del packaging, rispondi a quattro domande con una prova, non con un'intenzione.

Quattro risposte positive non garantiscono che il plugin funzioni ovunque. Dicono soltanto che vale la pena costruire un pacchetto e sottoporlo a una prova vera.

Scrivi il contratto del plugin

Un manifest descrive identità e versione, ma il contratto operativo deve dire qualcosa in più. Annota almeno:

Problema: quale lavoro ripetuto risolve.
Trigger: quando una Skill o un hook deve partire.
Input: file, argomenti e configurazioni necessari.
Output: che cosa produce e dove lo lascia.
Effetti: comandi, rete o servizi che può raggiungere.
Dipendenze: programmi e variabili richiesti.
Prova: caso valido, caso di errore e risultato atteso.
Rimozione: come disattivarlo senza perdere dati.

Il contratto evita che il README diventi un catalogo dei file. Chi installa deve capire cosa entra, cosa esce e dove il workflow si ferma. La SOP di un workflow AI offre la stessa struttura per una procedura: input, passaggi, controlli e stop.

Metti ogni componente nella root corretta

Claude Code carica i componenti da posizioni previste nella root del plugin. Le Skill vivono sotto skills/, gli agenti sotto agents/, gli hook in hooks/ e la configurazione MCP nel file dedicato. La cartella .claude-plugin/ ospita il manifest, non tutti gli altri componenti.

Questa distinzione sembra piccola, ma evita un guasto difficile da leggere: il plugin viene riconosciuto, mentre una parte interna non compare. Prima della prova confronta la struttura con la guida corrente di Anthropic, poi elenca i componenti che ti aspetti di vedere.

Le Skill installate da un plugin usano un namespace. È una proprietà utile: due pacchetti possono avere una Skill chiamata review senza fingere che siano la stessa procedura. Nel test usa sempre il nome completo, così sai quale versione stai invocando.

Prova il pacchetto senza installarlo

Il flag --plugin-dir permette di caricare una directory locale per una sessione. Usalo su una copia di prova, con input sintetici e senza accessi esterni non necessari. Il primo obiettivo è verificare il caricamento, non completare subito un lavoro importante.

Controlla i componenti uno per volta:

1. la Skill compare e accetta l'input previsto;

2. l'agent ha gli strumenti dichiarati e restituisce il formato concordato;

3. l'hook parte solo sull'evento scelto e lascia un esito leggibile;

4. il server MCP espone soltanto i tool previsti per il test;

5. la rimozione del plugin toglie davvero quei componenti dalla sessione successiva.

Dopo una modifica, /reload-plugins ricarica il pacchetto. Non usare il reload come prova finale: apri anche una sessione nuova. Una sessione lunga può conservare contesto che nasconde una dipendenza mancante.

Distribuisci per gradi

La prima distribuzione va a una persona, non a tutto il team. Dai al collega il contratto, il caso di prova e la versione. Non spiegare a voce i passaggi mancanti. Se il test riesce solo dopo una telefonata, la documentazione non è ancora parte del pacchetto.

La scala può avere quattro gradini:

1. caricamento locale da directory controllata;

2. prova di un collega su un progetto non critico;

3. installazione condivisa per un piccolo gruppo;

4. catalogo interno con owner, versione e procedura di aggiornamento.

Un marketplace è un catalogo, non un'approvazione automatica. La guida all'installazione dei plugin distingue infatti l'aggiunta del marketplace dall'installazione del singolo pacchetto. Conserva quella decisione: sapere dove trovare un plugin non significa aver deciso di eseguirlo.

Gestisci versione, dipendenze e ritorno

Ogni rilascio deve rispondere a tre domande: cosa cambia, quale prova è passata e come si torna alla versione precedente. Un numero di versione senza queste informazioni identifica il file, ma non riduce il rischio.

Blocca le dipendenze che possono cambiare il comportamento. Se un hook richiede un eseguibile, specifica la versione supportata o almeno il controllo con cui ne verifichi la presenza. Se un server MCP dipende da un'autenticazione, documenta lo scope richiesto senza mettere il segreto nel plugin.

Applica una sola variazione per rilascio quando puoi. La procedura di controllo delle modifiche aiuta a legare baseline, variazione, prova e ripristino. Se cambi insieme Skill, hook e collegamento esterno, un errore non ti dirà quale pezzo si è rotto.

Misura se il pacchetto ha tolto lavoro

Conta casi concreti: copie manuali evitate, installazioni riuscite senza assistenza, errori di versione e rollback eseguiti. Non serve inventare una percentuale di produttività.

Se ogni progetto richiede molte eccezioni, il nucleo comune è troppo largo. Se le persone continuano a copiare i file invece di installare il plugin, il percorso di adozione costa più del vantaggio. Se nessuno sa quale versione è attiva, manca una ricevuta visibile.

Un plugin ha senso quando riduce le differenze accidentali senza nascondere le differenze necessarie.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi partire da un workflow che usi davvero, separare il nucleo dalle impostazioni locali e portarlo fino alla prova con un'altra persona. Il risultato utile non è avere un pacchetto da mostrare. È poterlo installare, verificare e rimuovere senza una spiegazione fuori dal processo.