Installare Mods in Claude Code: scope, reload e aggiornamenti

Per installare Mods in Claude Code devi trattarli come plugin: identificare una fonte, leggere cosa aggiungono, scegliere uno scope e verificare quale codice è attivo nella sessione. Non basta copiare un comando trovato online. La procedura ufficiale distingue installazione, abilitazione e caricamento, che possono richiedere verifiche separate. Install and manage plugins.

Questa guida, verificata il 9 ottobre 2026, riguarda plugin già esistenti. Per capire prima se il prodotto serve, leggi cosa sono i Mods di Claude; per scrivere codice nuovo, segui il percorso del primo mod TypeScript. Qui il risultato atteso è più concreto: sapere da dove viene la personalizzazione, dove vale e come riconoscere un aggiornamento applicato.

Cosa controllare prima di installare un mod?

Parti dall’identità del plugin: nome, autore, repository o marketplace, versione e funzione promessa. Poi leggi i componenti. Un pacchetto può contenere più del solo indicatore che interessa: server, istruzioni, agenti e reazioni agli eventi. L’installazione rende disponibile una confezione; non prova che ogni componente sia necessario al tuo lavoro.

I plugin possono eseguire codice con i privilegi dell’utente. La review della provenienza deve quindi comprendere ciò che il codice legge, modifica o avvia. Un nome familiare e una descrizione breve non sono una verifica sufficiente. La documentazione sulla sicurezza dei plugin chiarisce il confine di fiducia; la guida a AI e sicurezza dei dati lo colloca nel contesto aziendale.

Annota anche la versione di Claude Code e la superficie che utilizzerai. Per le guide operative ai Mods, il requisito conservativo è 2.1.287 o successiva; una funzione aggiuntiva può richiedere una release più recente. Un plugin che disegna nel terminale non va valutato soltanto da un’interfaccia che non rende quel componente. Guida ufficiale di creazione.

Marketplace e plugin: quali nomi servono davvero?

Il nome a destra di @ identifica il marketplace, quello a sinistra il plugin. Una fonte custom deve essere registrata attraverso il percorso previsto prima di installarne i pacchetti. Se qualcuno invia soltanto un comando, chiedi al documento del progetto di riportare anche l’origine: evita che due colleghi usino pacchetti diversi con descrizioni simili.

Questo è un esempio di sintassi con placeholder, non un plugin esistente da eseguire:

claude plugin install nome-mod@nome-marketplace --scope user

Sostituisci entrambi i nomi solo dopo aver esaminato la fonte e scelto lo scope. Nella sessione interattiva il pannello /plugin consente di consultare i dettagli; il percorso da shell è distinto. La reference dei comandi plugin è il riferimento per la sintassi della versione disponibile.

Per una prova iniziale conviene identificare un solo plugin e una sola funzione da osservare. Installare un’intera raccolta rende più difficile capire quale componente produce un messaggio o occupa la UI. Se vuoi iniziare da una demo identificata, Token Weather ha un obiettivo leggibile: mostrare l’occupazione del contesto, con limiti dichiarati.

Quale scope scegliere fra user, project e local?

La scelta riguarda l’abilitazione, non una classificazione di qualità. User serve quando quella personalizzazione è parte del tuo ambiente abituale. Project registra una scelta condivisa nel repository. Local permette una scelta personale limitata a quel repository. La documentazione specifica i rispettivi file di configurazione e distingue abilitazione condivisa da installazione sulle macchine dei collaboratori. Install scope.

La domanda decisiva è chi dovrebbe ricevere la scelta. Un collega non deve scoprire un nuovo controllo mentre sta risolvendo una consegna urgente. Una configurazione project merita una nota breve: funzione, fonte, versione attesa e percorso di attivazione. Se è ancora un esperimento, lo scope local mantiene chiara la responsabilità della prova.

Una policy del team può stabilire ulteriori vincoli. In quel caso non serve tentare scope diversi per aggirare un rifiuto: bisogna leggere il motivo e confrontarlo con la distribuzione approvata. La guida a Mods per team e sicurezza spiega perché «abilitato dai settings gestiti» e «mod dell’organizzazione» non sono sinonimi automatici.

Come verificare che il mod sia attivo nella sessione?

Dopo l’installazione leggi il riepilogo. La presenza nell’elenco dei plugin prova che il pacchetto è registrato; la funzione richiesta prova qualcosa di diverso. Controlla nome, versione, scope e stato, poi osserva il comportamento che ti aspettavi. Se il plugin aggiunge un comando, verifica quel comando; se aggiunge un indicatore, verifica la superficie prevista.

Se hai installato o aggiornato da shell mentre una sessione era già aperta, non dedurre che il runtime sia cambiato. Applica il reload indicato dal prodotto oppure avvia una nuova sessione. /reload-plugins appartiene al prompt di Claude Code, non alla shell del sistema operativo. Distinguere questi ingressi evita errori banali che sembrano problemi del mod.

Il controllo deve essere una prova piccola e innocua. Un indicatore può essere verificato con un dato sintetico o un’attività di lettura. Un plugin che autorizza o modifica operazioni richiede invece una prova isolata e casi negativi già definiti. Non usare una procedura pericolosa come scorciatoia per vedere se «parte». Il caricamento è una verifica, l’affidabilità del comportamento è un’altra.

Quando usare una directory locale per una sola sessione?

Per un plugin locale già esaminato, il percorso di sviluppo consente di caricare la directory senza trasformarla subito in installazione permanente. La sintassi documentata è:

claude --plugin-dir ./mod-esaminato

Il nome della directory è un esempio locale. Prima del caricamento controlla che contenga proprio il pacchetto previsto e che i file siano stati letti. Il comando avvia codice: non diventa innocuo solo perché la directory è vicina al progetto. La guida ufficiale spiega il ciclo di caricamento e reload per questa modalità.

Questa opzione è utile per distinguere un difetto del plugin da un problema della distribuzione. Se la directory di sviluppo mostra la funzione corretta e la copia installata resta vecchia, il problema potrebbe essere nel versionamento o nel percorso di aggiornamento. Non modificare la cache installata per «far tornare» il risultato: perderesti la relazione fra versione dichiarata e contenuto effettivo.

Se la personalizzazione nasce da una richiesta a Claude nella sessione, approvazione e cartella di sviluppo seguono un percorso proprio. Non considerare quella cartella una distribuzione definitiva per il team. Prima di condividerla servono versione, README, test e una fonte stabile. Il tutorial del primo mod approfondisce proprio questo passaggio.

Come aggiornare senza restare con la copia vecchia?

Distingui tre stati: versione pubblicata nella fonte, versione installata sulla macchina e versione caricata nella sessione. Una segnalazione «disponibile un aggiornamento» riguarda il primo confronto; un’installazione riuscita riguarda il secondo; la funzione osservata riguarda il terzo. Per una diagnosi pulita devi poter nominare tutti e tre.

La documentazione indica aggiornamenti automatici predefiniti per molti marketplace ufficiali e quelli aggiunti da claude.ai, mentre community, terze parti e sviluppo locale hanno impostazioni diverse. Non esiste un unico comando documentato per aggiornare contemporaneamente tutti i plugin installati. Controlla la configurazione del marketplace reale e la procedura di aggiornamento.

Per un plugin custom incrementa la versione quando distribuisci una modifica, come richiede il modello di cache descritto dalla guida di creazione. Nel README registra cosa cambia e quale versione di Claude Code hai verificato. «Ho aggiornato i file» non basta se i colleghi continuano a installare la stessa versione nominale. Questa disciplina è piccola ma evita diagnosi lunghe su copie apparentemente identiche.

La funzione resta vecchia: quale confronto fare?

Confronta nome del plugin, marketplace, versione pubblicata, versione installata, scope e percorso caricato. Leggi poi il riepilogo della sessione e verifica se il reload è stato applicato. Se il plugin custom ha nuovi file ma la stessa versione, correggi la distribuzione prima di intervenire sulla cache. Registra infine un comportamento riconoscibile della versione nuova.

Un prerequisito mancante significa installazione fallita?

Non sempre. Un plugin può essere presente e avere un componente che richiede configurazione aggiuntiva, per esempio un servizio incluso nel pacchetto. Leggi il riepilogo e distingui il pacchetto registrato dal componente pronto all’uso. Non ripetere l’installazione per correggere credenziali o opzioni che devono essere configurate separatamente.

Nella scheda del team indica quindi prerequisiti e criterio di completamento. Se la funzione è un indicatore locale, il criterio riguarda il dato e la superficie. Se dipende da un servizio, comprende anche accesso e risposta autorizzata. Una verifica coerente con quella dipendenza evita di chiamare «rotto» un pacchetto correttamente installato ma non ancora configurato. La documentazione ufficiale del plugin deve restare collegata alla scheda, così chi arriva dopo trova il requisito della versione giusta.

Due esempi ipotetici di installazione in una PMI

Esempio ipotetico: uno studio software di Torino prova un indicatore personale. Una sviluppatrice vuole osservare il contesto mentre lavora su un repository didattico. Esamina la demo, verifica la superficie terminale e sceglie una prova limitata. Nel diario annota origine, versione e comportamento atteso. Nessun altro collega riceve automaticamente una nuova scelta durante l’esperimento.

Il giorno dopo vuole usarla in due progetti. Prima di scegliere user scope verifica che l’indicatore non occupi una banda già usata da un’altra personalizzazione. Se emerge un conflitto, decide quale informazione tenere visibile. La scelta riguarda l’esperienza di lavoro, non una promessa di riduzione dei consumi. Condivide poi la procedura solo se il team desidera adottarla.

Esempio ipotetico: una PMI di Padova distribuisce un comando interno approvato. Il responsabile prepara un pacchetto con versione e README, lo rende disponibile dalla fonte del team e definisce i prerequisiti. Il progetto registra l’abilitazione condivisa, ma ciascuna macchina deve ricevere il pacchetto attraverso il percorso previsto. Il controllo di avvenuta adozione confronta elenco dei plugin e funzione effettiva.

Quando cambia il comando, il responsabile pubblica una versione nuova e comunica il comportamento che la identifica. Un collega vede ancora il risultato precedente: prima di toccare i file confrontano origine, versione installata e sessione aperta. Il caso si risolve sulla distribuzione o sul reload, invece di moltiplicare copie manuali non riconoscibili.

Quali errori fanno perdere tempo durante il setup?

Il primo è copiare i placeholder come se fossero nomi reali. Il secondo è confondere un comando del prompt con uno della shell. Il terzo è condividere uno scope project senza indicare ai collaboratori origine e installazione. Il quarto è valutare una UI dalla superficie sbagliata. Il quinto è chiamare «aggiornato» un plugin solo perché i file della directory di sviluppo sono nuovi.

Per ogni errore la correzione parte da una prova concreta. Nome reale del marketplace, ingresso corretto del comando, elenco dei plugin, superficie documentata e versione del manifest sono dati controllabili. Se il caricamento resta assente, passa alla diagnosi del mod che non funziona, conservando il messaggio di errore invece di ripetere installazioni alla cieca.

Come rendere il setup ripetibile per chi arriva dopo?

Prepara una scheda breve con funzione, origine, versione, scope, prerequisiti e criterio di verifica. Inserisci anche il percorso per disattivare il componente e il nome del responsabile. La scheda non deve duplicare tutta la documentazione ufficiale: deve collegare il plugin al bisogno del team e rendere chiaro quando il setup è davvero concluso.

Dopo un cambiamento verifica soltanto ciò che quel cambiamento può aver alterato. Se modifichi la versione, controlla distribuzione e reload. Se modifichi la UI, controlla le superfici interessate. Se cambia il comportamento, aggiorna anche i test del mod. Una checklist mirata resta leggibile e permette a un nuovo collega di riprodurre il risultato.

Se il team deve rendere questa procedura parte di un ambiente di sviluppo condiviso, una software house può preparare pacchetto, distribuzione e verifiche coerenti con il repository. Il quadro di Claude Code e la policy aziendale d’uso AI aiutano a decidere quali personalizzazioni rendere abituali.