Plugins reference

Riferimento tecnico completo per il sistema di plugin di Claude Code, inclusi schemi, comandi CLI e specifiche dei componenti.

Un plugin è una directory autonoma di componenti che estende Claude Code con funzionalità personalizzate. I componenti del plugin includono skills, agents, hooks, server MCP, server LSP e monitor.

Riferimento dei componenti del plugin

Skills

I plugin aggiungono skills a Claude Code, creando scorciatoie /name che tu o Claude potete invocare.

Posizione: directory skills/ o commands/ nella radice del plugin, oppure un singolo file SKILL.md nella radice del plugin

Formato file: Gli skills sono directory con SKILL.md; i commands sono semplici file markdown

Struttura skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opzionale)
│   └── scripts/ (opzionale)
└── code-reviewer/
    └── SKILL.md

Gli skills e i commands vengono rilevati automaticamente quando il plugin viene installato.

Se un plugin non ha una directory skills/ e nessun campo manifest skills, un SKILL.md nella radice del plugin viene caricato come un singolo skill. Impostare il campo frontmatter name per controllare il nome di invocazione dello skill. Senza di esso, Claude Code ricade al nome della directory di installazione. Per un plugin copiato nella cache, quel nome è una stringa di versione che cambia ad ogni aggiornamento. Per i plugin che forniscono più di uno skill, utilizzare il layout della directory skills/ mostrato sopra.

Negli skills e nei commands del plugin, i campi frontmatter booleani come disable-model-invocation accettano yes, no, on, off, 1 e 0 in qualsiasi caso di lettera, oltre a true e false. Prima della v2.1.218, Claude Code riconosceva solo true e false.

Per i dettagli completi, vedere Skills.

Agents

I plugin possono fornire subagent specializzati per compiti specifici che Claude può invocare automaticamente quando appropriato.

Posizione: directory agents/ nella radice del plugin

Formato file: File markdown che descrivono le capacità dell'agent

Struttura agent:

---
name: agent-name
description: In cosa si specializza questo agent e quando Claude dovrebbe invocarlo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt di sistema dettagliato per l'agent che descrive il suo ruolo, competenza e comportamento.

Gli agent del plugin supportano i campi frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd e isolation. L'unico valore isolation valido è "worktree".

Per motivi di sicurezza, gli agent forniti dal plugin non supportano hooks, mcpServers o permissionMode.

Claude Code carica un agent del plugin anche quando il suo frontmatter non ha name o non viene analizzato:

Nessun name: Claude Code nomina l'agent in base al file, quindi agents/reviewer.md in un plugin denominato my-plugin viene caricato come my-plugin:reviewer
Frontmatter che non viene analizzato: Claude Code nomina l'agent in base al file, utilizza Agent from my-plugin plugin come sua descrizione e ignora ogni campo nel file

Al contrario, Claude Code salta un file di progetto, utente o agent gestito il cui frontmatter non ha name o non viene analizzato.

Per trovare i file nella directory agents/ predefinita di un plugin il cui frontmatter non viene analizzato, eseguire claude plugin validate. Il percorso che passi dipende dal fatto che il plugin abbia un manifest, e entrambi gli esempi utilizzano ./my-plugin come directory del plugin:

Un plugin con un manifest: claude plugin validate ./my-plugin
Un plugin senza un manifest: claude plugin validate ./my-plugin/agents. Richiede Claude Code v2.1.233 o successivo.

Gli agent vengono visualizzati nella typeahead @-mention con il loro nome con scope, come my-plugin:code-reviewer, una volta che il plugin è abilitato.

Per i dettagli completi, vedere Subagent.

Hooks

I plugin possono fornire gestori di eventi che rispondono automaticamente agli eventi di Claude Code.

Posizione: hooks/hooks.json nella radice del plugin, oppure inline in plugin.json

Formato: Configurazione JSON con matcher di eventi e azioni

hooks/hooks.json può contenere una chiave $schema di livello superiore che nomina un URL JSON Schema per l'autocompletamento dell'editor e la convalida. Claude Code ignora la chiave al momento del caricamento.

Configurazione hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Gli hook del plugin rispondono agli stessi eventi del ciclo di vita degli hook definiti dall'utente:

Evento	Quando si attiva
`SessionStart`	Quando una sessione inizia o riprende
`Setup`	Quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità `-p`. Per la preparazione una tantum in CI o script
`UserPromptSubmit`	Quando invii un prompt, prima che Claude lo elabori
`UserPromptExpansion`	Quando un comando digitato dall'utente si espande in un prompt, prima che raggiunga Claude. Può bloccare l'espansione
`PreToolUse`	Prima che una chiamata a uno strumento si esegua. Può bloccarla
`PermissionRequest`	Quando una chiamata a uno strumento necessita di una decisione di autorizzazione
`PermissionDenied`	Quando la modalità automatica nega una chiamata a uno strumento, inclusi i rifiuti senza un verdetto del classificatore. Utilizza JSON `hookSpecificOutput.retry: true` per indicare al modello che può riprovare la chiamata allo strumento negata. Claude Code ignora `retry` quando il classificatore non ha prodotto alcun verdetto
`PostToolUse`	Dopo che una chiamata a uno strumento ha successo
`PostToolUseFailure`	Dopo che una chiamata a uno strumento fallisce
`PostToolBatch`	Dopo che un intero batch di chiamate a strumenti paralleli si risolve, prima della prossima chiamata al modello
`Notification`	Quando Claude Code invia una notifica
`MessageDisplay`	Mentre il testo del messaggio dell'assistente viene visualizzato
`SubagentStart`	Quando un subagente viene generato
`SubagentStop`	Quando un subagente termina
`TaskCreated`	Quando un'attività viene creata tramite `TaskCreate`
`TaskCompleted`	Quando un'attività viene contrassegnata come completata
`Stop`	Quando Claude finisce di rispondere
`StopFailure`	Quando il turno termina a causa di un errore API
`TeammateIdle`	Quando un compagno di squadra di un team di agenti sta per diventare inattivo
`InstructionsLoaded`	Quando un file CLAUDE.md o `.claude/rules/*.md` viene caricato nel contesto. Si attiva all'inizio della sessione e quando i file vengono caricati in modo pigro durante una sessione
`ConfigChange`	Quando un file di configurazione cambia durante una sessione
`CwdChanged`	Quando la directory di lavoro cambia, ad esempio quando Claude esegue un comando `cd`. Utile per la gestione reattiva dell'ambiente con strumenti come direnv
`DirectoryAdded`	Quando una directory di lavoro viene aggiunta a metà sessione tramite `/add-dir` o la richiesta di controllo SDK `register_repo_root`
`FileChanged`	Quando un file osservato cambia su disco. Il campo `matcher` specifica quali nomi di file osservare
`WorktreeCreate`	Quando un worktree viene creato tramite `--worktree`, `isolation: "worktree"`, o per una sessione in background. Sostituisce il comportamento git predefinito
`WorktreeRemove`	Quando un worktree viene rimosso all'uscita della sessione, quando un subagente termina, o quando elimini una sessione in background
`PreCompact`	Prima della compattazione del contesto
`PostCompact`	Dopo che la compattazione del contesto è completata
`PreModelSwitch`	Prima che Claude Code applichi un cambio di modello che hai richiesto tu o un client. Può bloccare il cambio
`PostModelSwitch`	Dopo che il modello della sessione cambia, inclusi i cambiamenti che Claude Code effettua autonomamente, come il ripristino del modello quando riprendi una sessione
`Elicitation`	Quando un server MCP richiede input dell'utente durante una chiamata a uno strumento
`ElicitationResult`	Dopo che un utente risponde a un'elicitazione MCP, prima che la risposta venga inviata al server
`SessionEnd`	Quando una sessione termina

Tipi di hook:

command: eseguire comandi shell o script
http: inviare l'evento JSON come richiesta POST a un URL
mcp_tool: chiamare uno strumento su un server MCP configurato
prompt: valutare un prompt con un LLM (utilizza il placeholder $ARGUMENTS per il contesto)
agent: eseguire un verificatore agentico con strumenti per compiti di verifica complessi

Gli hook che puntano al server MCP bundled del plugin devono utilizzare i suoi nomi con scope. I matcher di strumenti e i campi if prendono il nome dello strumento con scope mcp__plugin_<plugin-name>_<server-name>__<tool>, e il campo server di un hook mcp_tool prende plugin:<plugin-name>:<server-name>. Un matcher scritto contro la chiave del server nuda non si attiva mai. Vedere Match MCP tools e Plugin-provided MCP servers.

MCP servers

I plugin possono raggruppare server Model Context Protocol (MCP) per connettere Claude Code con strumenti e servizi esterni.

Posizione: .mcp.json nella radice del plugin, oppure inline in plugin.json

Formato: Configurazione standard del server MCP

Configurazione del server MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Comportamento di integrazione:

I server MCP del plugin si avviano automaticamente quando il plugin è abilitato
I server vengono visualizzati come strumenti MCP standard nel toolkit di Claude
I server del plugin possono essere configurati indipendentemente dai server MCP dell'utente
Se esegui /reload-plugins a metà sessione, Claude Code mantiene le connessioni live dei server la cui configurazione è invariata

LSP servers

I plugin possono fornire server Language Server Protocol (LSP) per dare a Claude intelligenza del codice in tempo reale mentre lavori sulla tua codebase.

Posizione: .lsp.json nella radice del plugin, oppure inline in plugin.json

Formato: Configurazione JSON che mappa i nomi dei server di linguaggio alle loro configurazioni

Formato file .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Inline in plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Campi obbligatori:

Field	Description
`command`	Il binario LSP da eseguire (deve essere in PATH)
`extensionToLanguage`	Mappa le estensioni di file agli identificatori di linguaggio

Campi opzionali:

Field	Description
`args`	Argomenti della riga di comando per il server LSP
`transport`	Trasporto di comunicazione: `stdio` (predefinito) o `socket`. Claude Code accetta `socket` ma esegue ogni server su stdio, quindi le regole del protocollo stdout si applicano a tutti i server
`env`	Variabili di ambiente da impostare all'avvio del server
`initializationOptions`	Opzioni passate al server durante l'inizializzazione
`settings`	Impostazioni passate tramite `workspace/didChangeConfiguration`
`workspaceFolder`	Percorso della cartella di lavoro per il server
`startupTimeout`	Tempo massimo di attesa per l'avvio del server (millisecondi)
`shutdownTimeout`	Tempo massimo di attesa per l'arresto graduale (millisecondi). Quando il timeout scade, Claude Code termina il processo del server. Se non impostato, non si applica alcun timeout
`restartOnCrash`	Se riavviare il server dopo un crash. Predefinito su `true`. Impostare su `false` per lasciare un server bloccato fermo invece di riavviarlo
`maxRestarts`	Numero massimo di tentativi di riavvio prima di rinunciare
`diagnostics`	Se inserire la diagnostica nel contesto di Claude dopo le modifiche (predefinito `true`). Impostare su `false` per mantenere la navigazione del codice ma sopprimere l'iniezione automatica della diagnostica.

restartOnCrash e shutdownTimeout richiedono Claude Code v2.1.205 o successivo. Prima della v2.1.205, lo schema di configurazione accettava entrambe le opzioni ma l'impostazione di una di esse causava a Claude Code di saltare completamente quel server LSP all'avvio, con il motivo visibile solo nell'output di claude --debug.

Più server per la stessa estensione: quando più di un server LSP abilitato dichiara la stessa estensione di file in extensionToLanguage, indipendentemente dal fatto che i server provengano da un plugin o da plugin diversi, il primo server registrato gestisce i file con quell'estensione e gli altri non si avviano mai. L'interfaccia /plugin mostra un avviso che nomina il plugin il cui server è attivo.

Server che non riescono a inizializzare: Claude Code salta un server la cui configurazione non è valida, ad esempio uno che manca command o extensionToLanguage, e gli altri server configurati si avviano comunque. Eseguire claude --debug per vedere perché un server è stato saltato.

Un server saltato non rivendica le sue estensioni di file, quindi un altro server valido che dichiara la stessa estensione, dallo stesso plugin o da un plugin diverso, gestisce comunque quei file.

Invia l'output del log a stderr, non a stdout: Claude Code legge lo stdout di un server solo come messaggi di protocollo e accetta intestazioni di messaggi fino a 64 KiB e un corpo di messaggio fino a 32 MiB. Claude Code disconnette un server che supera uno dei due limiti o scrive output non-protocollo a stdout, e conta la disconnessione come un crash per restartOnCrash e maxRestarts. Quando esegui con --debug, Claude Code scrive un errore che nomina la causa nel log di debug.

Plugin LSP disponibili:

Plugin	Language server	Install command
`pyright-lsp`	Pyright (Python)	`pip install pyright` o `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-analyzer-lsp`	rust-analyzer	Vedi rust-analyzer installation

Installa il server di linguaggio per primo, quindi installa il plugin dal marketplace.

Monitors

I plugin possono dichiarare monitor in background che Claude Code avvia automaticamente quando il plugin è attivo. Ogni monitor esegue un comando shell per la durata della sessione e fornisce ogni riga stdout a Claude come notifica, in modo che Claude possa reagire alle voci di log, ai cambiamenti di stato o agli eventi sondati senza essere chiesto di avviare il watch stesso.

I monitor del plugin utilizzano lo stesso meccanismo dello strumento Monitor e condividono i suoi vincoli di disponibilità. Vengono eseguiti solo in sessioni CLI interattive, vengono eseguiti senza sandbox allo stesso livello di fiducia degli hook e vengono saltati su host dove lo strumento Monitor non è disponibile.

Posizione: monitors/monitors.json nella radice del plugin, oppure inline in plugin.json

Formato: Array JSON di voci di monitor

Il seguente monitors/monitors.json osserva un endpoint di stato di distribuzione e un log di errore locale:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Per dichiarare monitor inline, impostare experimental.monitors in plugin.json sullo stesso array. Per caricare da un percorso non predefinito, impostare experimental.monitors su una stringa di percorso relativo come "./config/monitors.json". I monitor sono un componente sperimentale.

Campi obbligatori:

Field	Description
`name`	Identificatore univoco all'interno del plugin. Previene processi duplicati quando il plugin si ricarica o uno skill viene invocato di nuovo
`command`	Comando shell eseguito come processo in background persistente nella directory di lavoro della sessione
`description`	Breve riepilogo di ciò che viene osservato. Mostrato nel pannello attività e nei riepiloghi delle notifiche

Campi opzionali:

Field	Description
`when`	Controlla quando il monitor si avvia. `"always"` lo avvia all'avvio della sessione e al ricaricamento del plugin, ed è il predefinito. `"on-skill-invoke:<skill-name>"` lo avvia la prima volta che lo skill denominato in questo plugin viene inviato

Il valore command supporta le sostituzioni di percorso ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} e ${CLAUDE_PROJECT_DIR}, più qualsiasi ${ENV_VAR} dall'ambiente. Prefisso il comando con cd "${CLAUDE_PLUGIN_ROOT}" && se lo script deve essere eseguito dalla directory del plugin stesso.

Un command di monitor non può fare riferimento ai valori ${user_config.*}. Il comando viene eseguito attraverso una shell, quindi Claude Code rifiuta il monitor con un errore invece di sostituire il valore. I processi di monitor non ricevono variabili di ambiente CLAUDE_PLUGIN_OPTION_<KEY>, quindi fai in modo che lo script di monitor legga il valore da un file di configurazione che possiede.

Se disabiliti un plugin a metà sessione, Claude Code non interrompe i monitor che sono già in esecuzione; si fermano quando la sessione termina.

Themes

I plugin possono fornire temi di colore che vengono visualizzati in /theme insieme ai preset integrati e ai temi locali dell'utente. Un tema è un file JSON in themes/ con un preset base e una mappa sparsa overrides di token di colore. I temi sono un componente sperimentale.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Quando un utente seleziona un tema del plugin, Claude Code salva custom:<plugin-name>:<slug> nella sua configurazione. I temi del plugin sono di sola lettura: quando un utente preme Ctrl+E su uno in /theme, Claude Code lo copia in ~/.claude/themes/ in modo che possano modificare la copia.

Ambiti di installazione dei plugin

Quando installi un plugin, scegli un ambito che determina dove il plugin è disponibile e chi altro può utilizzarlo:

Ambito	File di configurazione	Caso d'uso
`user`	`~/.claude/settings.json`	Plugin personali disponibili in tutti i progetti (predefinito)
`project`	`.claude/settings.json`	Plugin del team condivisi tramite controllo versione
`local`	`.claude/settings.local.json`	Plugin specifici del progetto, ignorati da git quando Claude Code salva un'impostazione in esso
`managed`	Managed settings	Plugin gestiti (sola lettura, solo aggiornamento)

I plugin utilizzano lo stesso sistema di ambiti di altre configurazioni di Claude Code. Per le istruzioni di installazione e i flag di ambito, vedi Install plugins. Per una spiegazione completa degli ambiti, vedi Configuration scopes.

Plugin della directory skills

Qualsiasi cartella sotto una directory skills che contiene un manifest .claude-plugin/plugin.json viene caricata come plugin denominato <name>@skills-dir nella sessione successiva, senza marketplace e senza passaggio di installazione. Creane uno con plugin init. A differenza di un'installazione marketplace copiata, il plugin viene scoperto sul posto piuttosto che copiato nella cache dei plugin.

Un albero di directory skills supporta tre cose distinte:

Quello che hai	Che cosa è
`<skills-dir>/foo/SKILL.md` senza manifest	Una semplice skill denominata `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	Un plugin `foo@skills-dir`, che può raggruppare le proprie skills, agenti, hooks e altro
`<plugin>/skills/bar/SKILL.md`	Una skill `bar` inclusa in un plugin

Scegli da dove il plugin viene caricato

Directory skills	Ambito	Carica
`~/.claude/skills/`	personale	In ogni progetto, poiché la posizione è solo tua
`<cwd>/.claude/skills/`	progetto	Solo dopo che accetti la finestra di dialogo di trust per quella cartella

Un plugin con ambito progetto viene archiviato nel repository e raggiunge ogni collaboratore che lo clona. Poiché quel contenuto proviene dal repository piuttosto che da te, viene caricato solo dopo lo stesso gate di trust che governa le regole di autorizzazione del progetto in .claude/settings.json, quindi fidarsi di una cartella padre o eseguire con -p non è sufficiente, e i componenti che eseguono codice sono ulteriormente limitati:

I server MCP che dichiara passano attraverso la stessa approvazione per server di un .mcp.json del progetto
I server LSP si avviano solo dopo che hai fiducia nell'area di lavoro
I monitor in background non vengono caricati

I plugin con ambito personale non hanno nessuna di queste restrizioni.

Modifica, ricarica e disabilita un plugin della directory skills

Le modifiche che apporti al SKILL.md di una skill hanno effetto immediato nella sessione corrente. Le modifiche agli altri componenti del plugin, come hooks/, .mcp.json, agents/ e output-styles/, non lo fanno. Esegui /reload-plugins o riavvia Claude Code per caricarli. Vedi Live change detection.

Per smettere di caricare un plugin della directory skills, elimina la sua cartella o disabilitalo per nome. Non c'è un passaggio uninstall perché nulla è stato installato da un marketplace.

claude plugin disable my-tool@skills-dir

Plugin sincronizzati da claude.ai

Claude Code carica i plugin abilitati per il vostro account claude.ai, inclusi i plugin che la vostra organizzazione attiva per i suoi membri, insieme ai plugin che installate dai marketplace. Li scarica in ~/.claude/plugins/synced/ e carica ciascuno come <name>@synced, senza marketplace e senza record di installazione. Un plugin sincronizzato viene eseguito con la stessa fiducia di un plugin marketplace che avete installato: le sue skills, gli agenti, gli hooks, i server MCP e i server LSP si caricano tutti.

Il luogo in cui Claude Code sincronizza questi plugin dipende dalla sessione:

In Cowork e sessioni cloud, Claude Code li scarica nell'ambiente della sessione stessa quando la sessione inizia. Prima della v2.1.239, Claude Code caricava questi plugin come <name>@inline, l'identità che i plugin --plugin-dir utilizzano.
Nelle sessioni di terminale in cui vi accedete con il vostro account claude.ai, Claude Code controlla il vostro account una volta ogni volta che si avvia, quindi scarica i plugin nuovi e aggiornati e rimuove quelli che voi o la vostra organizzazione avete disabilitato, il tutto in background. La sincronizzazione nelle sessioni di terminale richiede Claude Code v2.1.273 o successivo.

Il controllo di avvio viene eseguito in background, quindi può terminare dopo che la vostra sessione è iniziata. Quando aggiunge, aggiorna o rimuove un plugin sincronizzato in una sessione interattiva, Claude Code mostra Plugins changed. Run /reload-plugins to activate. Eseguite /reload-plugins per caricare la modifica in quella sessione, oppure lasciatela per la prossima volta che avviate Claude Code. Se abilitate un plugin su claude.ai mentre una sessione è in esecuzione, Claude Code lo scarica la prossima volta che si avvia.

La sincronizzazione dei plugin nelle sessioni di terminale viene eseguita nelle stesse condizioni di accesso delle skills sincronizzate da claude.ai. Richiede anche un accesso che conceda a Claude Code l'accesso ai plugin del vostro account.

Un accesso da una versione precedente di Claude Code acquisisce l'accesso ai plugin la prossima volta che Claude Code rinnova quell'accesso in background, entro poche ore, o subito se eseguite di nuovo /login. La sincronizzazione dei plugin inizia la prossima volta che avviate Claude Code dopo di ciò.

claude plugin list mostra i plugin sincronizzati sotto un'intestazione Synced from claude.ai, e la scheda Installed di /plugin li elenca con synced come loro fonte. Gestite un plugin sincronizzato tramite l'ID <name>@synced che claude plugin list stampa:

Disabilitarne uno: eseguite claude plugin disable <name>@synced, oppure disabilitatelo dalla scheda Installed di /plugin. Claude Code salva la scelta come "<name>@synced": false nel vostro enabledPlugins a livello di utente. Per riabilitare il plugin, eseguite claude plugin enable <name>@synced.
Mantenerlo fuori ovunque: disabilitate il plugin per il vostro account claude.ai. Per mantenerlo fuori da un progetto in ogni ambiente, impostate "<name>@synced": false sotto enabledPlugins nel .claude/settings.json committato di quel progetto.
Gestite il plugin stesso su claude.ai: claude plugin install, update e uninstall non si applicano a un plugin sincronizzato. Claude Code scarica gli aggiornamenti di un plugin alla prossima sincronizzazione. Per rimuoverne uno, disabilitate il plugin per il vostro account claude.ai, e Claude Code lo rimuove alla prossima sincronizzazione.
Interrompere la sincronizzazione su una macchina: impostate syncClaudeAiPlugins a false nelle vostre impostazioni utente. Claude Code smette di scaricare, e la prossima volta che si avvia sposta i plugin che ha già sincronizzato in ~/.claude/plugins/.trash/ e non li carica più. La vostra organizzazione può impostare la stessa chiave nelle impostazioni gestite, oppure disabilitare Skills su claude.ai, il che interrompe anche la sincronizzazione dei plugin.

Non potete disabilitare un plugin che la vostra organizzazione contrassegna come obbligatorio su claude.ai. Claude Code lo carica anche se lo avete disabilitato in precedenza, e claude plugin disable rifiuta con Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it. In claude plugin list, questi plugin sono contrassegnati required by your org.

Quando un plugin abilitato da qualsiasi altra fonte corrisponde al nome di un plugin sincronizzato, Claude Code carica quel plugin e segnala la copia sincronizzata come non caricata. Le altre fonti includono installazioni da marketplace, plugin skills-directory, plugin --plugin-dir e plugin integrati in Claude Code. Per utilizzare la copia da claude.ai, disabilitate la vostra copia. Prima della v2.1.239, Claude Code caricava la copia sincronizzata al posto di un'installazione da marketplace con lo stesso nome.

Schema del manifest del plugin

Il file .claude-plugin/plugin.json definisce i metadati e la configurazione del plugin.

Il manifest è facoltativo. Se omesso, Claude Code scopre automaticamente i componenti nelle posizioni predefinite e deriva il nome del plugin dal nome della directory. Utilizzare un manifest quando è necessario fornire metadati o percorsi di componenti personalizzati.

Schema completo

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Campi obbligatori

Se si include un manifest, name è l'unico campo obbligatorio.

Campo	Tipo	Descrizione	Esempio
`name`	string	Identificatore univoco in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionali. Quando una voce del marketplace elenca il plugin con un nome diverso, il nome della voce del marketplace è quello utilizzato da `enabledPlugins` e `/plugin`	`"deployment-tools"`

Questo nome viene utilizzato per lo spazio dei nomi dei componenti. Ad esempio, nell'interfaccia utente, l'agente agent-creator per il plugin con nome plugin-dev apparirà come plugin-dev:agent-creator.

Campi non riconosciuti

Claude Code ignora i campi di primo livello che non riconosce. È possibile mantenere i metadati da un altro ecosistema in plugin.json e il plugin si carica comunque. Questo rende pratico mantenere un unico manifest che funziona sia come manifest di VS Code o Cursor, come package.json npm, o come manifest di bundle MCPB/DXT.

claude plugin validate segnala i campi non riconosciuti come avvisi, non come errori. Se un campo è uno o due caratteri diverso da uno riconosciuto, l'avviso suggerisce il nome probabilmente inteso. Un plugin con solo avvisi di campi non riconosciuti passa comunque la convalida e si carica al runtime.

Il modo in cui Claude Code gestisce un campo riconosciuto il cui valore ha il tipo sbagliato dipende dal campo:

La maggior parte dei campi: il plugin non si carica. Ad esempio, un valore keywords che è una stringa invece di un array è un errore di caricamento, e claude plugin validate lo segnala come tale.
experimental e metadata: Claude Code ignora un valore non-oggetto, e claude plugin validate segnala un avviso.

Passare --strict per trattare gli avvisi come errori. Utilizzarlo in CI per rilevare un nome di campo scritto male o un campo rimasto da un manifest di un altro strumento prima della pubblicazione, anche se il plugin si caricherà al runtime.

claude plugin validate ./my-plugin --strict

Campi di metadati

Campo	Tipo	Descrizione	Esempio
`$schema`	string	URL dello schema JSON per l'autocompletamento e la convalida dell'editor. Claude Code ignora questo campo al momento del caricamento.	`"https://json.schemastore.org/claude-code-plugin-manifest.json"`
`displayName`	string	Nome leggibile mostrato nel selettore `/plugin` e in altre superfici dell'interfaccia utente. Per un plugin installato dal marketplace, un `displayName` sulla voce del marketplace ha la precedenza su questo valore. Quando nessun nome di visualizzazione è impostato in nessuno dei due posti, gli utenti vedono `name`. A differenza di `name`, può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per lo spazio dei nomi o la ricerca.	`"Deployment Tools"`
`version`	string	Facoltativo. Versione semantica. L'impostazione di questa opzione fissa il plugin a quella stringa di versione, quindi gli utenti ricevono aggiornamenti solo quando la si incrementa, ad eccezione di una `command` source o un plugin caricato in place; vedere Gestione delle versioni. Se impostato anche nella voce del marketplace, `plugin.json` vince. Se omesso, la versione proviene dalla prossima fonte in Gestione delle versioni.	`"2.1.0"`
`description`	string	Breve spiegazione dello scopo del plugin	`"Deployment automation tools"`
`author`	object	Informazioni sull'autore	`{"name": "Dev Team", "email": "dev@company.com"}`
`homepage`	string	URL della documentazione	`"https://docs.example.com"`
`repository`	string	URL del codice sorgente	`"https://github.com/user/plugin"`
`license`	string	Identificatore della licenza	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Tag di scoperta	`["deployment", "ci-cd"]`
`metadata`	object	Oggetto in formato libero per i propri dati, come campi di diritto o catalogo. Claude Code non lo legge, quindi i valori non influiscono mai sul comportamento del plugin. Claude Code ignora un valore non-oggetto, e `claude plugin validate` lo segnala come avviso. Prima della v2.1.222, Claude Code trattava la chiave come un campo non riconosciuto.	`{"catalogId": "cat-123"}`
`defaultEnabled`	boolean	Se il plugin inizia in uno stato abilitato quando l'utente non ne ha impostato uno. Predefinito a `true`. Vedere Abilitazione predefinita.	`false`

Abilitazione predefinita

Impostare defaultEnabled: false in plugin.json per distribuire un plugin che si installa disabilitato. L'utente lo attiva con claude plugin enable <plugin> o l'interfaccia /plugin. Utilizzare questa opzione per i plugin che aggiungono costi o ambito a cui un utente dovrebbe acconsentire esplicitamente, come uno che si connette a un servizio esterno.

defaultEnabled è il fallback quando nient'altro ha deciso lo stato del plugin. L'impostazione dell'utente e un requisito di dipendenza hanno la precedenza su di esso:

L'impostazione dell'utente: una voce per il plugin in enabledPlugins in qualsiasi ambito di impostazioni. Una volta scritta, persiste tra gli aggiornamenti e le reinstallazioni del plugin, quindi modificare defaultEnabled in una versione successiva non capovolge un utente esistente.
Un requisito di dipendenza: quando un plugin è richiesto da un altro che è attivo, Claude Code scrive true per esso al momento dell'installazione o dell'abilitazione. Questo gli dà un'impostazione esplicita, quindi il suo valore predefinito non si applica più. Vedere Abilitare o disabilitare un plugin con dipendenze.

Lo stesso campo può apparire nella voce del marketplace di un plugin, dove ha la precedenza sul valore in plugin.json. Vedere Campi plugin facoltativi.

Campi del percorso del componente

Campo	Tipo	Descrizione	Esempio
`skills`	string\|array	Directory di skill personalizzate contenenti `<name>/SKILL.md`. Si aggiunge alla scansione predefinita `skills/`. Vedere Regole di comportamento del percorso per l'eccezione della radice del marketplace	`"./custom/skills/"`
`commands`	string\|array	File di skill `.md` flat personalizzati o directory (sostituisce il valore predefinito `commands/`)	`"./custom/cmd.md"` o `["./cmd1.md"]`
`agents`	string\|array	File di agenti personalizzati (sostituisce il valore predefinito `agents/`)	`"./custom/agents/reviewer.md"`
`workflows`	string\|array	File di script workflow personalizzati o directory (sostituisce il valore predefinito `workflows/`)	`"./custom/workflows/"`
`hooks`	string\|array\|object	Percorsi di configurazione hook o configurazione inline	`"./my-extra-hooks.json"`
`mcpServers`	string\|array\|object	Percorsi di configurazione MCP o configurazione inline	`"./my-extra-mcp-config.json"`
`outputStyles`	string\|array	File/directory di stili di output personalizzati (sostituisce il valore predefinito `output-styles/`)	`"./styles/"`
`lspServers`	string\|array\|object	Configurazioni Language Server Protocol per l'intelligenza del codice (vai a definizione, trova riferimenti, ecc.)	`"./.lsp.json"`
`experimental.themes`	string\|array	File/directory di temi colore (sostituisce il valore predefinito `themes/`). Vedere Temi	`"./themes/"`
`experimental.monitors`	string\|array	Configurazioni di Monitor in background che si avviano automaticamente quando il plugin è attivo. Vedere Monitor	`"./monitors.json"`
`experimental.evals`	string\|array	Directory sotto la radice del plugin che contiene i casi di eval del plugin, quando non è la directory predefinita `evals/`. `claude plugin eval --eval-dir` la sostituisce	`"quality/evals"`
`userConfig`	object	Valori configurabili dall'utente richiesti al momento dell'abilitazione. Vedere Configurazione utente
`channels`	array	Dichiarazioni di canale per l'iniezione di messaggi (stile Telegram, Slack, Discord). Vedere Canali
`dependencies`	array	Altri plugin richiesti da questo plugin, facoltativamente con vincoli di versione semver. Vedere Vincolare le versioni delle dipendenze del plugin	`[{ "name": "secrets-vault", "version": "~2.1.0" }]`

Componenti sperimentali

I componenti sotto la chiave experimental, themes e monitors, hanno uno schema di manifest che potrebbe cambiare tra le versioni mentre si stabilizzano. Dove li si dichiara è una migrazione separata: il livello superiore funziona ancora, claude plugin validate avverte, e una versione futura richiederà experimental.*.

Configurazione utente

Il campo userConfig dichiara i valori per i quali Claude Code richiede all'utente quando il plugin è abilitato. Utilizzare questa opzione invece di richiedere agli utenti di modificare manualmente settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Le chiavi devono essere identificatori validi. Ogni opzione supporta questi campi:

Campo	Obbligatorio	Descrizione
`type`	Sì	Uno di `string`, `number`, `boolean`, `directory`, o `file`
`title`	Sì	Etichetta mostrata nella finestra di dialogo di configurazione
`description`	Sì	Testo di aiuto mostrato sotto il campo
`sensitive`	No	Se `true`, maschera l'input e memorizza il valore nell'archiviazione sicura invece di `settings.json`
`required`	No	Se `true`, la convalida fallisce quando il campo è vuoto
`default`	No	Valore utilizzato quando l'utente non fornisce nulla
`options`	No	Per il tipo `string`, i valori che il campo accetta, mostrati in `/config` come un selettore su di essi. Richiede Claude Code v2.1.271 o successivo
`multiple`	No	Per il tipo `string`, consenti un array di stringhe
`min` / `max`	No	Limiti per il tipo `number`

Ad eccezione dei campi sensitive e degli elenchi multiple, ogni campo di ogni plugin abilitato appare anche come una riga nel pannello /config. Le righe richiedono Claude Code v2.1.269 o successivo.

Ogni valore è disponibile per la sostituzione come ${user_config.KEY} nelle configurazioni del server MCP e LSP e nei comandi hook. I valori non sensibili possono anche essere sostituiti nel contenuto di skill e agenti. Tutti i valori vengono esportati ai processi hook come variabili di ambiente CLAUDE_PLUGIN_OPTION_<KEY>, dove <KEY> è la chiave dell'opzione in maiuscolo.

I campi che vengono eseguiti in una shell rifiutano ${user_config.*}: sostituire un valore configurato in un comando shell consentirebbe alla shell di eseguire qualsiasi cosa contenga quel valore, quindi il componente fallisce con un errore invece. Ogni campo rifiutato ha un modo alternativo per passare il valore:

Campo rifiutato	Come passare il valore
Comandi hook in forma shell	Utilizzare forma exec con `args`, o leggere `CLAUDE_PLUGIN_OPTION_<KEY>` dall'ambiente del hook
Comandi Monitor	Leggere il valore da un file di configurazione nello script
MCP `headersHelper`	Leggere il valore da un file di configurazione nello script

Prima della v2.1.207, questi campi sostituivano i valori ${user_config.KEY}; aggiornare i plugin che si basavano su questo.

I valori non sensibili vengono memorizzati sotto la chiave pluginConfigs nel file settings.json dell'utente come pluginConfigs[<plugin-id>].options.

Su macOS, Claude Code memorizza i valori sensibili nel Portachiavi di macOS, ricadendo su ~/.claude/.credentials.json quando il Portachiavi rifiuta la scrittura. Su piattaforme senza un portachiavi supportato, li memorizza in ~/.claude/.credentials.json. L'archiviazione del Portachiavi è condivisa con i token OAuth e ha un limite totale approssimativo di 2 KB, quindi mantenere i valori sensibili piccoli.

Claude Code legge tutti i valori pluginConfigs da solo tre fonti di impostazioni:

Impostazioni utente: ~/.claude/settings.json, il file in cui la richiesta al momento dell'abilitazione scrive
--settings: il flag CLI o le impostazioni inline SDK
Impostazioni gestite: politica controllata dall'organizzazione

Quando più di una fonte imposta la stessa chiave, le impostazioni gestite hanno la precedenza, quindi --settings, quindi le impostazioni utente. L'unica fonte che è possibile rimuovere da questo elenco è le impostazioni utente: passare --setting-sources senza user e Claude Code le salta. Le impostazioni gestite e --settings rimangono qualsiasi cosa si passi. L'opzione settingSources dell'SDK imposta lo stesso elenco.

Le voci nel file .claude/settings.json o .claude/settings.local.json di un progetto vengono ignorate. Entrambi i file si trovano nell'area di lavoro, quindi un repository clonato potrebbe fornire valori lì, e quei valori fluirebbero nei comandi hook del plugin, nelle configurazioni del server MCP, nei comandi LSP e nei comandi monitor. Prima della v2.1.207, queste voci venivano lette. La restrizione è specifica per pluginConfigs: enabledPlugins onora ancora le impostazioni del progetto e locali.

Canali

Il campo channels consente a un plugin di dichiarare uno o più canali di messaggi che iniettano contenuto nella conversazione. Ogni canale si associa a un server MCP fornito dal plugin.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Il campo server è obbligatorio e deve corrispondere a una chiave in mcpServers del plugin. L'opzionale userConfig per canale utilizza lo stesso schema del campo di primo livello, consentendo al plugin di richiedere token bot o ID proprietario quando il plugin è abilitato.

Regole di comportamento del percorso

Se un percorso personalizzato sostituisce o estende la directory predefinita del plugin dipende dal campo:

Sostituisce il valore predefinito: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Ad esempio, quando il manifest specifica commands, la directory predefinita commands/ non viene scansionata. Per mantenere il valore predefinito e aggiungerne altri, elencarli esplicitamente: "commands": ["./commands/", "./extras/"]
Si aggiunge al valore predefinito: skills. La directory predefinita skills/ viene sempre scansionata, e le directory elencate in skills vengono caricate insieme ad essa. Eccezione: per una voce del marketplace la cui source si risolve nella radice del marketplace, dichiarare sottodirectory specifiche sostituisce la scansione predefinita skills/
Regole di merge proprie: hooks, server MCP, e server LSP. Vedere ogni sezione per come più fonti si combinano

Quando un plugin ha sia una cartella predefinita che la chiave manifest corrispondente, Claude Code avverte sulla cartella ignorata in claude plugin list e nella vista dei dettagli /plugin. Il plugin si carica comunque utilizzando i percorsi del manifest. Claude Code non avverte quando la chiave manifest punta nella cartella predefinita, ad esempio "commands": ["./commands/deploy.md"], perché quel percorso nomina la cartella esplicitamente.

Per tutti i campi del percorso:

Tutti i percorsi devono essere relativi alla radice del plugin e iniziare con ./, tranne che il campo skills accetta anche "."
- Sia "." che "./" denotano la radice del plugin stesso
- Prima della v2.1.221, "." falliva la convalida del manifest e il plugin non si caricava, quindi utilizzare "./" per supportare versioni precedenti
I componenti da percorsi personalizzati utilizzano le stesse regole di denominazione e spazio dei nomi
Più percorsi possono essere specificati come array
Un percorso di skill può puntare a una directory che contiene direttamente un SKILL.md, ad esempio "skills": ["."] per la radice del plugin
- Claude Code prende il nome di invocazione della skill dal campo frontmatter name in SKILL.md, quindi il nome rimane stabile indipendentemente da come viene denominata la directory di installazione
- Se name non è impostato nel frontmatter, Claude Code ritorna al nome della directory di base

Un plugin che ha un SKILL.md alla sua radice, nessuna sottodirectory skills/, e nessun campo manifest skills viene caricato automaticamente come plugin a skill singola. Non è necessario impostare "skills": ["./"] in plugin.json per questo layout.

Esempi di percorso:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variabili di ambiente

Claude Code fornisce tre variabili per fare riferimento ai percorsi:

Variabile	Si risolve in	Utilizzarla per
`${CLAUDE_PLUGIN_ROOT}`	Percorso assoluto della directory di installazione del plugin	Script, binari e file di configurazione forniti con il plugin
`${CLAUDE_PLUGIN_DATA}`	Directory persistente che sopravvive agli aggiornamenti del plugin, creata al primo riferimento	Dipendenze installate come `node_modules` o ambienti virtuali Python, codice generato e cache
`${CLAUDE_PROJECT_DIR}`	La radice del progetto	Script e file di configurazione locali del progetto

Tutti e tre vengono esportati come variabili di ambiente ai processi hook e ai sottoprocessi del server MCP e LSP. Non sono presenti nell'ambiente dei comandi che Claude esegue attraverso lo strumento Bash, nella sessione principale o in un subagent. Nel contenuto del plugin, scrivere il placeholder invece, e Claude Code sostituisce il percorso inline quando carica il contenuto. Quali campi sostituiscono inline dipende dal componente del plugin:

Componente del plugin	Campi dove i placeholder si risolvono
Contenuto di skill e agenti	Ovunque appaia il placeholder
Comandi hook e monitor	Ovunque appaia il placeholder
Server MCP `stdio`	`command`, `args`, `env`
Server MCP `http`, `sse`, `ws`	`url`, `headers`, `headersHelper`
Server LSP	`command`, `args`, `env`, `workspaceFolder`

Nei comandi hook, utilizzare forma exec con args in modo che ogni percorso venga passato come un argomento senza virgolette. Negli hook in forma shell e nei comandi monitor, racchiudere le variabili tra virgolette doppie, come in "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Questo hook in forma shell esegue uno script fornito con un plugin:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Per un plugin copiato, ${CLAUDE_PLUGIN_ROOT} cambia quando il plugin si aggiorna. La directory della versione precedente rimane su disco per un periodo di grazia dopo un aggiornamento, ma trattarla come effimera e non scrivere stato lì. Per un plugin caricato in place da un marketplace di directory locale, la variabile punta alla directory sorgente stabile. Vedere plugin caching per quali plugin vengono copiati e per la semantica di pulizia.

Quando un plugin copiato si aggiorna a metà sessione, i comandi hook, i monitor, i server MCP e i server LSP continuano a utilizzare il percorso della versione precedente. Eseguire /reload-plugins per passare i hook, i server MCP e i server LSP al nuovo percorso; i monitor richiedono un riavvio della sessione. In una sessione senza un terminale interattivo, il ricaricamento lascia i server MCP del plugin sul percorso precedente fino alla sessione successiva.

Per un plugin con una command source, Claude Code può ricaricare il plugin stesso.

I server MCP possono anche chiamare la richiesta roots/list per leggere le directory di lavoro della sessione al runtime. Vedere cosa restituisce roots/list e quando Claude Code notifica al server i cambiamenti.

Directory di dati persistenti

La directory ${CLAUDE_PLUGIN_DATA} si risolve in ~/.claude/plugins/data/{id}/, dove {id} è l'identificatore del plugin con caratteri al di fuori di a-z, A-Z, 0-9, _, e - sostituiti da -. Per un plugin installato come formatter@my-marketplace, la directory è ~/.claude/plugins/data/formatter-my-marketplace/.

Un uso comune è installare le dipendenze del linguaggio una volta e riutilizzarle tra sessioni e aggiornamenti del plugin. Utilizzarla per le dipendenze Python, le dipendenze bloccate con Yarn o pnpm, e i pacchetti i cui script del ciclo di vita devono essere eseguiti. Per un plugin installato dal marketplace, potrebbe non essere necessario affatto: Claude Code installa automaticamente le dipendenze del pacchetto Node.js idonee quando memorizza il plugin nella cache.

Poiché la directory di dati sopravvive a qualsiasi singola versione del plugin, un controllo per l'esistenza della directory da solo non può rilevare quando un aggiornamento cambia il manifest delle dipendenze del plugin. Il modello consigliato confronta il manifest fornito con una copia nella directory di dati e reinstalla quando differiscono.

Questo hook SessionStart installa node_modules alla prima esecuzione e di nuovo ogni volta che un aggiornamento del plugin include un package.json modificato:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Il diff esce con codice diverso da zero quando la copia memorizzata è mancante o differisce da quella fornita, coprendo sia la prima esecuzione che gli aggiornamenti che cambiano le dipendenze. Se npm install fallisce, il trailing rm rimuove il manifest copiato in modo che la sessione successiva riprovi.

Gli script forniti in ${CLAUDE_PLUGIN_ROOT} possono quindi essere eseguiti contro il node_modules persistente:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

La directory di dati viene eliminata automaticamente quando si disinstalla il plugin dall'ultimo ambito in cui è installato. L'interfaccia /plugin mostra la dimensione della directory e richiede conferma prima di eliminare. La CLI elimina per impostazione predefinita; passare --keep-data per preservarla.

Caching dei plugin e risoluzione dei file

I plugin vengono specificati in uno di tre modi:

Tramite claude --plugin-dir o claude --plugin-url, per la durata di una sessione.
Tramite un marketplace, installato per sessioni future.
Tramite il vostro account claude.ai, sincronizzato in ~/.claude/plugins/synced/.

Per motivi di sicurezza e verifica, Claude Code copia i plugin del marketplace nella cache dei plugin locale dell'utente (~/.claude/plugins/cache), a meno che il plugin non si carichi sul posto. Una command source in link mode si carica sul posto tramite link nella voce della cache. Una relative path source in un marketplace aggiunto da una directory locale si carica sul posto dalla cartella del marketplace.

Per un plugin caricato sul posto da un marketplace di directory locale, le vostre modifiche alla directory di origine hanno effetto all'avvio della sessione successiva o /reload-plugins. Non avete bisogno di un bump di versione. I processi hook del plugin e i server MCP e LSP ricevono un CLAUDE_PLUGIN_ROOT che punta alla directory di origine. Claude Code non installa le dipendenze dei pacchetti Node.js del plugin nella directory di origine. Installatele lì voi stessi, o da un hook nella directory dei dati persistenti.

Per i plugin copiati, ogni versione installata è una directory separata nella cache, raggruppata per marketplace e plugin e denominata per la versione risolta, con la propria copia dei file del plugin e delle dipendenze dei pacchetti Node.js. Una dipendenza risolta da un release tag ottiene un nome di directory con un suffisso commit-SHA.

Quando aggiornate o disinstallate un plugin, Claude Code contrassegna la directory della versione precedente come orfana e la rimuove in una scansione in background approssimativamente 14 giorni dopo. Il periodo di grazia consente alle sessioni di Claude Code concorrenti che hanno già caricato la versione precedente di continuare a funzionare senza errori. Claude Code esegue la scansione solo mentre è installato almeno un plugin; dopo aver disinstallato l'ultimo plugin, le directory orfane rimangono su disco fino a quando non installate di nuovo un plugin.

Claude Code rimuove una cartella di plugin o marketplace dalla cache solo quando non contiene più alcuna directory o symlink. Se create un symlink di uno sviluppo locale nella cache come voce di versione di un plugin, Claude Code non contrassegna mai il link come orfano e non lo rimuove mai né le cartelle che lo contengono. Claude Code inoltre non scrive mai i suoi file di tracciamento delle versioni all'interno del checkout collegato.

Gli strumenti Glob e Grep di Claude saltano le directory delle versioni orfane durante le ricerche, quindi i risultati dei file non includono codice di plugin obsoleto.

Dipendenze dei pacchetti Node.js

Quando Claude Code copia un plugin nella cache, installa anche le dipendenze dei pacchetti Node.js del plugin lì, in modo che gli hook e i server MCP del plugin possano caricarli. Questa sezione copre i pacchetti npm e Bun che un plugin dichiara nel suo package.json. Per i plugin che dipendono da altri plugin, vedere versioni delle dipendenze dei plugin.

Claude Code esegue l'installazione all'interno della directory della versione copiata ogni volta che ne crea una: quando installate un plugin, quando Claude Code aggiorna un plugin a una nuova versione, e all'inizio della sessione quando un plugin abilitato non è ancora memorizzato nella cache, ad esempio su una nuova macchina. L'installazione viene eseguita solo quando la directory root del plugin contiene sia un package.json che un lockfile supportato:

Lockfile	Comando
`bun.lock` o `bun.lockb`	`bun install --frozen-lockfile --ignore-scripts`
`npm-shrinkwrap.json` o `package-lock.json`	`npm ci --ignore-scripts`

Se un plugin contiene più di uno di questi lockfile, Claude Code utilizza la prima corrispondenza, controllando in ordine: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json.

Claude Code salta l'installazione in due casi, ognuno con la propria soluzione:

Se il vostro plugin contiene solo un yarn.lock o pnpm-lock.yaml, sostituiscilo con un lockfile npm.
Se un bunfig.toml si trova accanto al lockfile bun, rimuovete il bunfig.toml, o sostituite il lockfile bun con un lockfile npm.

Fornite un lockfile npm per la portata più ampia. Claude Code esegue il gestore di pacchetti del lockfile corrispondente dal PATH dell'utente e non esegue il fallback all'altro lockfile se manca. Per un plugin distribuito tramite una fonte npm, utilizzate npm-shrinkwrap.json; npm esclude package-lock.json dai pacchetti pubblicati.

Claude Code vincola questa installazione di dipendenze in modo che nessun codice dal plugin o dai suoi pacchetti venga eseguito durante essa, e limita quanto tempo può durare:

Risoluzione congelata: Bun e npm installano esattamente ciò che il lockfile fissa, e falliscono piuttosto che ri-risolvere le versioni quando package.json e il lockfile non concordano.
Nessuno script del ciclo di vita: --ignore-scripts impedisce l'esecuzione degli script preinstall, install e postinstall, in modo che le dipendenze che compilano moduli nativi in questi script scarichino ma non compilino durante questa installazione.
Timeout di 60 secondi: Claude Code interrompe un'installazione che dura più a lungo e la tratta come non riuscita.

Claude Code recupera un plugin da fonte npm prima di questa installazione di dipendenze, e nessuno degli script di installazione del pacchetto stesso viene eseguito durante il recupero. Vedere pacchetti npm.

Un'installazione non riuscita o saltata non blocca mai il plugin. Quando l'installazione fallisce, o Claude Code salta un lockfile yarn o pnpm o un bunfig.toml, registra il motivo come avviso nell'output di debug. Un plugin con un package.json e nessun lockfile viene saltato senza una voce di log. Un'installazione scaduta può lasciare un albero node_modules parziale nella copia memorizzata nella cache.

Non potete disattivare l'installazione automatica; nessuna impostazione o variabile di ambiente la disabilita. In reti ristrette, vedere i requisiti di accesso alla rete per gli host da consentire.

Per le dipendenze che l'installazione automatica non può fornire, come pacchetti che necessitano dei loro script del ciclo di vita per compilare, dipendenze Python, o un plugin bloccato con Yarn o pnpm, installatele da un hook nella directory dei dati persistenti.

Limitazioni dell'attraversamento dei percorsi

Claude Code non consente a un plugin di fare riferimento a file al di fuori della sua stessa directory. Rifiuta un percorso di componente che si risolve al di fuori della root del plugin, indipendentemente dal fatto che il percorso sia dichiarato in plugin.json o in una voce del marketplace. Ciò copre un percorso che punta al di fuori del plugin come scritto, come ../shared-utils, e un symlink che porta al di fuori del plugin, ad eccezione dei link all'interno di un marketplace.

Su macOS e Linux, Claude Code rifiuta anche un percorso di componente che contiene una barra rovesciata in qualsiasi punto, anche quando il percorso rimane all'interno del plugin. I componenti dichiarati con percorsi con barra rovesciata quindi si caricano solo su Windows. Scrivete i percorsi dei componenti con barre oblique, come ./commands/deploy.md.

Quando Claude Code rifiuta un percorso, segnala un errore path escapes plugin directory e carica il plugin senza quel componente.

Claude Code inoltre non copia i file al di fuori della directory del plugin nella cache quando installa il plugin, quindi quando uno script all'interno di un plugin copiato legge un percorso sopra la root del plugin, non trova nemmeno quei file.

Se il vostro plugin ha bisogno di condividere file con altre parti dello stesso marketplace, potete creare link simbolici all'interno della directory del vostro plugin. Il modo in cui un symlink viene gestito quando il plugin viene copiato nella cache dipende da dove si risolve il suo target:

All'interno della directory del plugin: il symlink viene preservato come symlink relativo nella cache, in modo che continui a risolvere il target copiato in fase di esecuzione.
Altrove all'interno dello stesso marketplace: il symlink viene dereferenziato. Il contenuto del target viene copiato nella cache al suo posto. Ciò consente alla directory skills/ di un meta-plugin di collegarsi alle skill definite da altri plugin nel marketplace.
Al di fuori del marketplace: il symlink viene saltato per motivi di sicurezza. Ciò impedisce ai plugin di estrarre file host arbitrari come percorsi di sistema nella cache.

Per i plugin installati con --plugin-dir, da un percorso locale, o da una command source in copy mode, solo i symlink che si risolvono all'interno della directory del plugin stesso vengono preservati. Tutti gli altri vengono saltati.

Il seguente comando crea un link dall'interno di un plugin del marketplace a una skill condivisa definita da un plugin sibling. Su Windows, utilizzate mklink /D da un Command Prompt elevato o abilitate Developer Mode:

ln -s ../../shared-plugin/skills/foo ./skills/foo

Struttura della directory dei plugin

Layout standard dei plugin

Un plugin completo segue questa struttura:

enterprise-plugin/
├── .claude-plugin/           # Directory dei metadati (opzionale)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills come file .md flat
│   ├── status.md
│   └── logs.md
├── agents/                   # Definizioni dei subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Script dei workflow
│   └── release-audit.js
├── output-styles/            # Definizioni dello stile di output
│   └── terse.md
├── themes/                   # Definizioni dei temi colore
│   └── dracula.json
├── monitors/                 # Configurazioni dei monitor in background
│   └── monitors.json
├── hooks/                    # Configurazioni degli hook
│   ├── hooks.json           # Configurazione principale degli hook
│   └── security-hooks.json  # Hook aggiuntivi
├── bin/                      # Eseguibili del plugin aggiunti a PATH
│   └── my-tool               # Invocabile come comando bare in Bash tool
├── settings.json            # Impostazioni predefinite per il plugin
├── .mcp.json                # Definizioni dei server MCP
├── .lsp.json                # Configurazioni dei server LSP
├── scripts/                 # Script degli hook e script di utilità
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # File di licenza
└── CHANGELOG.md             # Cronologia delle versioni

Un file CLAUDE.md nella radice del plugin non viene caricato come contesto del progetto. I plugin contribuiscono al contesto attraverso skills, agents e hooks piuttosto che tramite CLAUDE.md. Per fornire istruzioni che si carichino nel contesto di Claude, inseritele in una skill.

Riferimento delle posizioni dei file

Componente	Posizione predefinita	Scopo
Manifest	`.claude-plugin/plugin.json`	Metadati e configurazione del plugin (opzionale)
Skills	`skills/`	Skills con struttura `<name>/SKILL.md`
Commands	`commands/`	Skills come file Markdown flat. Utilizzare `skills/` per i nuovi plugin
Agents	`agents/`	File Markdown dei subagent
Workflows	`workflows/`	File script dei Workflow
Output styles	`output-styles/`	Definizioni dello stile di output
Themes	`themes/`	Definizioni dei temi colore
Hooks	`hooks/hooks.json`	Configurazione degli hook
Server MCP	`.mcp.json`	Definizioni dei server MCP
Server LSP	`.lsp.json`	Configurazioni dei language server
Monitors	`monitors/monitors.json`	Configurazioni dei monitor in background
Eseguibili	`bin/`	Eseguibili aggiunti al `PATH` del Bash tool e invocabili come comandi bare mentre il plugin è abilitato. Non è possibile includere questa directory in un plugin che distribuite attraverso le impostazioni dell'organizzazione claude.ai
Impostazioni	`settings.json`	Configurazione predefinita applicata quando il plugin è abilitato. Sono supportate solo le chiavi `agent` e `subagentStatusLine`

Riferimento dei comandi CLI

Claude Code fornisce comandi CLI per la gestione non interattiva dei plugin, utile per scripting e automazione.

plugin init

Crea lo scaffolding di un nuovo plugin in ~/.claude/skills/<name>/. Nella prossima sessione di Claude Code si carica automaticamente come <name>@skills-dir e appare in /plugin e claude plugin list senza alcun passaggio di installazione.

Vedi Skills-directory plugins per i requisiti di ambito e fiducia.

claude plugin init <name> [options]

Il comando accetta questi argomenti:

<name>: Nome del plugin. Diventa lo spazio dei nomi della skill e il nome della directory sotto ~/.claude/skills/, quindi non può contenere spazi o separatori di percorso.

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`--description <text>`	Descrizione del manifest
`--author <name>`	Nome dell'autore	`git config user.name`
`--author-email <email>`	Email dell'autore	`git config user.email`
`--with <components...>`	Crea anche lo scaffolding delle cartelle dei componenti. Valori validi: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel`
`-f, --force`	Sovrascrivi un `.claude-plugin/` esistente nel target
`-h, --help`	Visualizza la guida per il comando

claude plugin new è un alias per questo comando.

Ogni valore --with aggiunge un file di avvio per quel componente, pronto per essere modificato:

Componente	Cosa crea lo scaffolding
`skills`	Una skill aggiuntiva con spazio dei nomi `<name>:example` insieme a quella predefinita
`agents`	Una definizione di subagent in `agents/`
`hooks`	Un `hooks/hooks.json` con un gestore di eventi di esempio
`mcp`	Un `.mcp.json` con esempi di server HTTP e stdio
`lsp`	Un esempio di language-server `.lsp.json`
`output-style`	Un `output-styles/<name>.md` che si applica automaticamente mentre il plugin è abilitato
`channel`	Un channel basato su MCP: un server stdio (`server.ts`), il suo `.mcp.json` e un `package.json`

Il plugin creato con lo scaffolding utilizza la fonte @skills-dir piuttosto che un marketplace. Gli amministratori possono bloccare questa fonte con strictKnownMarketplaces o aggiungendo {"source": "skills-dir"} a blockedMarketplaces nelle impostazioni gestite. Quando bloccato, plugin init fallisce prima di scrivere.

Questi esempi mostrano invocazioni comuni:

# Crea lo scaffolding di un plugin minimo
claude plugin init my-helper

# Crea lo scaffolding con cartelle skill e hook
claude plugin init my-helper --with skills hooks

# Sovrascrivi uno scaffolding esistente
claude plugin init my-helper --force

plugin install

Installa un plugin dai marketplace disponibili.

claude plugin install <plugin> [options]

Il comando accetta questi argomenti:

<plugin>: Nome del plugin o plugin-name@marketplace-name per un marketplace specifico

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-s, --scope <scope>`	Ambito di installazione: `user`, `project` o `local`	`user`
`--config <key=value>`	Imposta un'opzione `userConfig` dichiarata nel manifest del plugin. Ripeti il flag per impostare più opzioni
`-y, --yes`	Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una `command` source, o l'`headersHelper` che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY, a meno che non passi `--accept-command`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale
`--accept-command <sha256>`	Accetta il comando dichiarato dal marketplace il cui `sha256` una precedente esecuzione `--json` ha segnalato in `shownCommand`, al posto di `-y`. L'accettazione conta esattamente per quel comando, plugin e catalogo del marketplace. Se uno qualsiasi di essi è cambiato da quando il comando è stato visualizzato, incluso attraverso l'aggiornamento del marketplace della stessa esecuzione, Claude Code non accetta il digest e mostra di nuovo il comando. Non può essere combinato con `-y`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale. Richiede Claude Code v2.1.271 o successivo
`--json`	Stampa il risultato come un oggetto JSON sulla ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi Formato del risultato JSON. Richiede Claude Code v2.1.268 o successivo
`-h, --help`	Visualizza la guida per il comando

L'ambito determina quale file di impostazioni il plugin installato viene aggiunto. Ad esempio, --scope project scrive in enabledPlugins in .claude/settings.json, rendendo il plugin disponibile a chiunque cloni il repository del progetto.

Con --json, l'ultima riga di stdout è un oggetto JSON. Analizza solo quella riga, perché Claude Code stampa qualsiasi comando che il marketplace dichiara prima di essa. Tre campi sono sempre presenti:

command: il sottocomando che è stato eseguito, come install
outcome: ok o failed
message: una descrizione leggibile del risultato

Altri campi, come pluginId, scope e failureCode, appaiono solo quando applicabili. L'opzione --json su plugin uninstall, plugin update, plugin enable e plugin disable stampa lo stesso oggetto con i campi propri di quel sottocomando. Un errore di utilizzo, come uno --scope non valido, non stampa alcuna riga di risultato ed esce con 1 con il motivo su stderr.

Quando un'esecuzione visualizza un comando dichiarato dal marketplace e non lo esegue, il risultato failed porta anche un oggetto shownCommand i cui campi includono il comando come visualizzato, il plugin a cui appartiene e lo sha256 del comando. Per accettare esattamente quel comando, esegui di nuovo con quello sha256 come --accept-command. Richiede Claude Code v2.1.271 o successivo.

Se shownCommand.acceptCommandMatched è false, il digest che hai passato non corrisponde al comando ora visualizzato. Mostra quel comando a una persona prima di passare il suo sha256.

Questi esempi mostrano invocazioni comuni:

# Installa nell'ambito utente (predefinito)
claude plugin install formatter@my-marketplace

# Installa nell'ambito progetto (condiviso con il team)
claude plugin install formatter@my-marketplace --scope project

# Installa nell'ambito locale (non condiviso con il team)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Rimuovi un plugin installato.

claude plugin uninstall <plugin> [options]

Il comando accetta questi argomenti:

<plugin>: Nome del plugin o plugin-name@marketplace-name

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-s, --scope <scope>`	Disinstalla dall'ambito: `user`, `project` o `local`	`user`
`--keep-data`	Preserva la persistent data directory del plugin
`--prune`	Rimuovi anche le dipendenze auto-installate che nessun altro plugin richiede. Vedi plugin prune
`-y, --yes`	Salta il prompt di conferma `--prune`. Obbligatorio quando stdin o stdout non è un TTY
`--json`	Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello stesso formato di `plugin install --json`. Non può essere combinato con `--prune`. Richiede Claude Code v2.1.268 o successivo
`-h, --help`	Visualizza la guida per il comando

claude plugin remove e claude plugin rm sono alias per questo comando.

Per impostazione predefinita, la disinstallazione dall'ultimo ambito rimanente elimina anche la directory ${CLAUDE_PLUGIN_DATA} del plugin. Usa --keep-data per preservarla, ad esempio quando reinstalli dopo aver testato una nuova versione.

plugin prune

Rimuovi le dipendenze dei plugin auto-installate che non sono più richieste da alcun plugin installato. Le dipendenze che Claude Code ha inserito per soddisfare il campo dependencies di un altro plugin vengono rimosse; i plugin che hai installato direttamente non vengono mai toccati.

claude plugin prune [options]

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-s, --scope <scope>`	Prune all'ambito: `user`, `project` o `local`	`user`
`--dry-run`	Elenca cosa verrebbe rimosso senza rimuovere nulla
`-y, --yes`	Salta il prompt di conferma. Obbligatorio quando stdin o stdout non è un TTY
`-h, --help`	Visualizza la guida per il comando

claude plugin autoremove è un alias per questo comando.

Il comando elenca le dipendenze orfane e chiede conferma prima di rimuoverle. Per rimuovere un plugin e pulire le sue dipendenze in un unico passaggio, esegui claude plugin uninstall <plugin> --prune.

plugin enable

Abilita un plugin disabilitato. Quando il target è installato da un marketplace e dichiara dependencies, Claude Code li abilita transitivamente nello stesso ambito. Il comando fallisce nelle condizioni che Enable or disable a plugin with dependencies elenca.

claude plugin enable <plugin> [options]

Il comando accetta questi argomenti:

<plugin>: Nome del plugin, plugin-name@marketplace-name o plugin-name@synced per un plugin sincronizzato da claude.ai

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-s, --scope <scope>`	Ambito da abilitare: `user`, `project` o `local`. Quando omesso, Claude Code rileva l'ambito in cui il plugin è installato	Auto-detect
`--json`	Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello stesso formato di `plugin install --json`. Richiede Claude Code v2.1.268 o successivo
`-h, --help`	Visualizza la guida per il comando

plugin disable

Disabilita un plugin senza disinstallarlo.

Quando il target è installato da un marketplace, il comando fallisce se un altro plugin abilitato dipende da esso. Il messaggio di errore include un comando concatenato che disabilita prima ogni dipendente.

Per un synced plugin che la tua organizzazione richiede, il comando fallisce e non salva nulla.

claude plugin disable [plugin] [options]

Il comando accetta questi argomenti:

[plugin]: Nome del plugin, plugin-name@marketplace-name o plugin-name@synced per un plugin sincronizzato da claude.ai. Facoltativo quando si usa --all

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-a, --all`	Disabilita tutti i plugin abilitati. Non può essere combinato con `--scope`
`-s, --scope <scope>`	Ambito da disabilitare: `user`, `project` o `local`. Quando omesso, Claude Code rileva l'ambito in cui il plugin è installato	Auto-detect
`--json`	Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello stesso formato di `plugin install --json`. Richiede Claude Code v2.1.268 o successivo
`-h, --help`	Visualizza la guida per il comando

plugin update

Aggiorna un plugin all'ultima versione.

claude plugin update <plugin> [options]

Il comando accetta questi argomenti:

<plugin>: Nome del plugin o plugin-name@marketplace-name

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-s, --scope <scope>`	Ambito da aggiornare: `user`, `project`, `local` o `managed`	`user`
`-y, --yes`	Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una `command` source, o l'`headersHelper` che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY, a meno che non passi `--accept-command`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale
`--accept-command <sha256>`	Accetta il comando dichiarato dal marketplace il cui `sha256` una precedente esecuzione `--json` ha segnalato in `shownCommand`, al posto di `-y`. L'accettazione conta esattamente per quel comando, plugin e catalogo del marketplace. Se uno qualsiasi di essi è cambiato da quando il comando è stato visualizzato, incluso attraverso l'aggiornamento del marketplace della stessa esecuzione, Claude Code non accetta il digest e mostra di nuovo il comando. Non può essere combinato con `-y`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale. Richiede Claude Code v2.1.271 o successivo
`--json`	Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello stesso formato di `plugin install --json`. Richiede Claude Code v2.1.268 o successivo
`-h, --help`	Visualizza la guida per il comando

plugin list

Elenca i plugin installati con la loro versione, il marketplace di origine e lo stato di abilitazione.

claude plugin list [options]

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`--json`	Output come JSON. Una riga di plugin con problemi di caricamento o avvisi di authoring porta array di stringhe `errors` o `notes`. Su Claude Code v2.1.268 o successivo, array paralleli `errorDetails` e `noteDetails` forniscono il `type` diagnostico di ogni voce e i nomi a cui si riferisce, come il plugin, il marketplace, il server o il file
`--available`	Includi i plugin disponibili dai marketplace. Richiede `--json`
`-h, --help`	Visualizza la guida per il comando

All'interno di una sessione interattiva, /plugin list stampa un elenco simile inline, ma copre solo i plugin installati dal marketplace:

I plugin caricati dalle directory delle skill appaiono nell'interfaccia /plugin e in claude plugin list, ma non nell'output inline /plugin list.
I plugin sincronizzati da claude.ai appaiono in claude plugin list su Claude Code v2.1.239 o successivo e nell'interfaccia /plugin, ma non nell'output inline /plugin list.
I plugin caricati per la sessione con --plugin-dir o --plugin-url appaiono nell'interfaccia /plugin e in claude plugin list solo quando lo stesso flag precede il sottocomando, come in claude --plugin-dir <dir> plugin list. Solo il nome del flag identifica la loro posizione, quindi un semplice claude plugin list non può trovarli, a differenza dei plugin sincronizzati e dei plugin della directory delle skill, le cui directory fisse Claude Code scansiona.

Il modulo interattivo accetta --enabled o --disabled per mostrare solo i plugin in quello stato, e ls come abbreviazione per list.

plugin details

Mostra l'inventario dei componenti di un plugin e il costo del token previsto. L'output elenca tutti i componenti che il plugin contribuisce, raggruppati come Skills, Agents, Hooks, server MCP e server LSP, insieme a una stima di quanti token aggiunge a ogni sessione. Il gruppo Skills include sia le voci skills/ che commands/.

claude plugin details <name>

Il comando accetta questi argomenti:

<name>: Nome del plugin o plugin-name@marketplace-name

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`-h, --help`	Visualizza la guida per il comando

L'output mostra due cifre di costo per ogni componente:

Always-on: token aggiunti a ogni sessione dal testo dell'elenco del plugin, come descrizioni delle skill, descrizioni degli agent e nomi dei comandi, indipendentemente dal fatto che un componente si attivi.
On-invoke: token che un componente costa quando si attiva. Mostrato per componente, non come totale del plugin, perché una sessione tipica invoca solo un sottoinsieme di componenti.

Questo esempio mostra come appare l'output per un plugin con due skill:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Il totale always-on viene calcolato tramite l'API count_tokens per il tuo modello attivo. I numeri per componente sono proporzionalmente scalati da quel totale. Se l'API non è raggiungibile, il comando ricade su una stima basata su caratteri.

plugin validate

Controlla un plugin o un marketplace per errori di sintassi e schema prima della pubblicazione.

Il comando esce con 0 quando la convalida passa, 1 quando fallisce e 2 quando l'esecuzione della convalida stessa fallisce, ad esempio quando il percorso che passi non è leggibile.

claude plugin validate <path> [options]

Il comando accetta questi argomenti:

<path>: Percorso a una directory di plugin o una directory di marketplace. Vedi Validate a plugin or a directory without a manifest per quali file una esecuzione di plugin copre.

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`--strict`	Tratta gli avvisi come errori ed esce con 1 su di essi. Usa in CI per catturare problemi che il runtime tollera, come unrecognized fields
`--json`	Output il rapporto di convalida come un oggetto JSON con gli stessi codici di uscita. Richiede Claude Code v2.1.259 o successivo
`-h, --help`	Visualizza la guida per il comando

Con --json, Claude Code scrive il rapporto su stdout come un oggetto JSON con questi campi di livello superiore:

success: lo stesso verdetto che il codice di uscita fornisce
strict: se l'esecuzione ha trattato gli avvisi come errori
target: il percorso risolto che Claude Code ha convalidato
manifest: il risultato del manifest stesso, o null per un'esecuzione senza manifest
contents: risultati per file, ognuno nominando il suo file e portando array errors, warnings e notes

All'uscita 2, il comando non scrive nulla su stdout; il messaggio di errore va su stderr.

All'interno di una sessione interattiva, /plugin validate <path> esegue gli stessi controlli inline.

plugin eval

Esegui i eval cases di un plugin e segnala i risultati valutati. Richiede Claude Code v2.1.269 o successivo. Ogni caso è un prompt più grader; Claude Code lo esegue più volte in una sessione isolata con solo il plugin target caricato, e per impostazione predefinita anche senza il plugin in modo che il rapporto mostri la differenza. Vedi Test plugins with evals per il formato del caso, i grader, i risultati e l'utilizzo in CI.

claude plugin eval [target] [options]

Il target facoltativo è una directory di plugin, un singolo file prompt.md o case.yaml, un plugin installato come name o name@marketplace, o name@skills-dir, e predefinito è la directory corrente. Mettilo prima di --tag, --allow-tools e --json.

Questa tabella elenca le opzioni che la maggior parte delle esecuzioni utilizza. Esegui claude plugin eval --help per l'insieme completo, inclusi --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp e --verbose.

Opzione	Descrizione	Predefinito
`--runs <n>`	Esecuzioni per caso per braccio	Ogni `runs` del caso, altrimenti 3
`-j, --concurrency <n>`	Sessioni di agent da eseguire contemporaneamente, da 1 a 8. Condividono il tuo limite di velocità	`1`
`--model <model>`	Modello per l'agent in test	Ogni `model` del caso, altrimenti `ANTHROPIC_MODEL` se impostato, altrimenti il predefinito di Claude Code
`--judge-model <model>`	Modello per i grader `llm` e `baseline`	Un modello piccolo e veloce
`--ablation <mode>`	`none` o `with-without`. Vedi Compare against a no-plugin baseline	`with-without` quando un plugin si risolve, altrimenti `none`
`--threshold <0..1>`	Esci con 1 se un caso qualsiasi punteggia al di sotto di questo	`1.0`
`--max-cost-usd <usd>`	Interrompi prima della prossima esecuzione una volta che la spesa raggiunge questo, esci con 2 e segnala risultati parziali	Nessun limite
`--allow-tools <tools...>`	Concedi strumenti oltre l'insieme di sola lettura, come `Bash`, `Write`, `Edit` o `"mcp__plugin_<plugin>_<server>__*"`. Vedi Grant tools
`--scaffold`	Esegui lo `scaffold_script` di ogni caso	Off
`--trust-plugin`	Salta il prompt di fiducia della prima esecuzione, per CI. Vedi What a run can access	Off
`--mocks <mode>`	`record` o `off`. Vedi Mock MCP servers	`record`
`--eval-dir <dir>`	Directory sotto il plugin che contiene i casi	Il `experimental.evals` del manifest, altrimenti `evals`
`--json [path]`	Stampa il result document su stdout, o scrivilo in un percorso `.json`
`--no-publish`	Mantieni il rapporto HTML locale
`-h, --help`	Visualizza la guida per il comando

Il comando esce con 0 quando ogni caso soddisfa la soglia, 1 su un caso fallito, un errore di caricamento o una directory di plugin non attendibile, 2 su un'esecuzione parziale, 130 quando interrotto e 143 quando terminato. Vedi Run evals in CI.

plugin eval init

Crea una suite di eval per il plugin nella directory corrente. Richiede Claude Code v2.1.269 o successivo. In un terminale questo avvia un'intervista di authoring che legge il plugin, propone casi e grader, li pilota e scrive i file. Con --bare, o senza un terminale, scrive invece un modello di singolo caso vuoto. Esegui da dentro una sessione interattiva di Claude Code, stampa le istruzioni dell'intervista per quella sessione da seguire piuttosto che scrivere un modello. Vedi Create your first eval suite.

claude plugin eval init [name] [options]

Il name facoltativo è un nome di caso: l'intervista non ne ha bisogno, mentre --bare e il percorso del modello senza terminale lo richiedono. Accetta queste opzioni:

Opzione	Descrizione	Predefinito
`--bare`	Scrivi un `prompt.md` vuoto e `graders/criteria.md` per `<name>` invece di eseguire l'intervista
`-i, --interactive`	Richiedi l'intervista. Fallisce senza un terminale invece di scrivere un modello
`--eval-dir <dir>`	Directory sotto la directory corrente in cui scrivere i casi	Il `experimental.evals` del manifest, altrimenti `evals`
`-h, --help`	Visualizza la guida per il comando

plugin tag

Crea un tag git di rilascio per un plugin. Per impostazione predefinita il comando etichetta il plugin nella directory corrente; passa un percorso per etichettare un plugin altrove. Vedi Tag plugin releases.

claude plugin tag [path] [options]

Il comando accetta questi argomenti:

[path]: Percorso alla directory del plugin. Predefinito è la directory corrente.

Il comando accetta queste opzioni:

Opzione	Descrizione	Predefinito
`--push`	Spinge il tag al remote dopo averlo creato
`--dry-run`	Stampa cosa verrebbe etichettato senza creare il tag
`-f, --force`	Crea il tag anche se l'albero di lavoro è sporco o il tag esiste già
`-m, --message <msg>`	Messaggio di annotazione del tag. Usa `%s` come segnaposto per la versione
`--remote <name>`	Remote a cui spingere con `--push`	`origin`
`-h, --help`	Visualizza la guida per il comando

Strumenti di debug e sviluppo

Comandi di debug

Utilizzare claude --debug per visualizzare i dettagli del caricamento dei plugin:

Questo mostra:

Quali plugin vengono caricati
Eventuali errori nei manifest dei plugin
Registrazione di skill, agent e hook
Inizializzazione del server MCP

Problemi comuni

Problema	Causa	Soluzione
Plugin non caricato	`plugin.json` non valido	Eseguire `claude plugin validate ./my-plugin` o `/plugin validate ./my-plugin`, dove `./my-plugin` è la directory del plugin, per controllare `plugin.json`, `hooks/hooks.json` e il frontmatter delle skill, degli agent e dei comandi nelle directory predefinite del plugin per errori di sintassi e schema. Vedere Validate a plugin or a directory without a manifest per informazioni su cosa copre un'esecuzione
Skill non visualizzate	Struttura di directory errata	Assicurarsi che `skills/` o `commands/` sia nella radice del plugin, non dentro `.claude-plugin/`
Hook non attivati	Script non eseguibile	Eseguire `chmod +x script.sh`
Server MCP non funziona	`${CLAUDE_PLUGIN_ROOT}` mancante	Utilizzare la variabile per tutti i percorsi dei plugin
Errori di percorso	Percorsi assoluti utilizzati	Rendere i percorsi relativi, iniziando con `./`; vedere Path behavior rules, che coprono l'eccezione `"."` del campo `skills`
LSP `Executable not found in $PATH`	Language server non installato	Installare il binario (ad es., `npm install -g typescript-language-server typescript`)

Messaggi di errore di esempio

Errori di convalida del manifest:

Invalid JSON syntax: Unexpected token } in JSON at position 142: controllare la presenza di virgole mancanti, virgole extra o stringhe non quotate
Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: un campo obbligatorio è mancante
Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: errore di sintassi JSON. Prima della versione 2.1.246, Claude Code produceva anche questo errore per un plugin.json salvato come UTF-8 con un byte order mark (BOM) iniziale, anche quando il JSON era altrimenti valido.

Errori di caricamento del plugin:

Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: il percorso del comando esiste ma non contiene file di comando validi
Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: il percorso source in marketplace.json punta a una directory inesistente
Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: rimuovere le definizioni di componenti duplicate o rimuovere strict: false nella voce del marketplace

Risoluzione dei problemi degli hook

Script hook non in esecuzione:

Verificare che lo script sia eseguibile: chmod +x ./scripts/your-script.sh
Verificare la riga shebang: La prima riga deve essere #!/bin/bash o #!/usr/bin/env bash
Verificare che il percorso utilizzi ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
Testare lo script manualmente: ./scripts/your-script.sh

Hook non attivato su eventi previsti:

Verificare che il nome dell'evento sia corretto (sensibile alle maiuscole): PostToolUse, non postToolUse
Verificare che il pattern del matcher corrisponda ai vostri strumenti: "matcher": "Write|Edit" per le operazioni su file
Confermare che il tipo di hook sia valido: command, http, mcp_tool, prompt o agent

Risoluzione dei problemi del server MCP

Server non avviato:

Verificare che il comando esista e sia eseguibile
Verificare che tutti i percorsi utilizzino la variabile ${CLAUDE_PLUGIN_ROOT}
Controllare i log del server MCP: claude --debug mostra gli errori di inizializzazione
Testare il server manualmente al di fuori di Claude Code

Strumenti del server non visualizzati:

Assicurarsi che il server sia configurato correttamente in .mcp.json o plugin.json
Verificare che il server implementi correttamente il protocollo MCP
Controllare i timeout di connessione nell'output di debug

Errori di struttura della directory

Sintomi: Il plugin viene caricato ma i componenti (skill, agent, hook) sono mancanti.

Struttura corretta: I componenti devono essere nella radice del plugin, non dentro .claude-plugin/. Solo plugin.json appartiene a .claude-plugin/.

Elenco di controllo del debug:

Eseguire claude --debug e cercare i messaggi "loading plugin"
Verificare che ogni directory di componenti sia elencata nell'output di debug
Verificare che i permessi dei file consentano la lettura dei file del plugin

Riferimento di distribuzione e versioning

Gestione delle versioni

Claude Code utilizza la versione del plugin come chiave di cache che determina se un aggiornamento è disponibile. Quando esegui /plugin update o l'aggiornamento automatico si attiva, Claude Code calcola la versione corrente e salta l'aggiornamento se corrisponde a quella già installata. Un plugin caricato in place da un marketplace di directory locale carica i suoi file sorgente correnti all'inizio di ogni sessione, indipendentemente da ciò che dice la sua stringa di versione.

Per ogni tipo di sorgente eccetto command, Claude Code risolve la versione dal primo di questi che è impostato:

Il campo version nel plugin.json del plugin
Il campo version nella voce del plugin nel marketplace in marketplace.json
Lo SHA del commit git della sorgente del plugin, per le sorgenti github, url, git-subdir e relative-path in un marketplace ospitato su git
Il digest SHA-256, per le sorgenti archive: il pin sha256 nella voce del marketplace, o il digest del file scaricato quando non imposti alcun pin. Claude Code lo accorcia ai primi 12 caratteri
unknown, per le sorgenti npm o le directory locali quando né la directory del plugin né il suo marketplace è un repository git. Claude Code non prende la versione da un repository che racchiude il percorso di installazione, come un ~/.claude gestito da git

Per una sorgente command, Claude Code deriva sempre la versione da ciò che il comando ha prodotto: un hash di contenuto di 12 caratteri da solo, o aggiunto alla versione plugin.json come <version>-<hash> quando uno è impostato. Claude Code ignora il campo version della voce del marketplace per le sorgenti command. Un comando il cui output con hash cambia produce quindi una nuova versione, anche quando la stringa di versione creata rimane la stessa. In link mode, l'hash copre il percorso reale della directory stampata e le sue voci di primo livello piuttosto che i contenuti dei file.

Per questi tipi di sorgente, questo ti dà tre modi per versioning di un plugin:

Approccio	Come	Comportamento dell'aggiornamento	Migliore per
Versione esplicita	Imposta `"version": "2.1.0"` in `plugin.json`	Gli utenti ricevono aggiornamenti solo quando aumenti questo campo. Spingere nuovi commit senza aumentarlo non ha effetto, e `/plugin update` segnala "already at the latest version". Per un plugin caricato in place, il nuovo contenuto si carica comunque.	Plugin pubblicati con cicli di rilascio stabili
Versione Commit-SHA	Ometti `version` sia da `plugin.json` che dalla voce del marketplace	Gli utenti ricevono aggiornamenti ogni volta che il commit risolto della sorgente cambia	Plugin interni o di team in sviluppo attivo
Versione Digest	Utilizza una sorgente `archive` e ometti `version` sia da `plugin.json` che dalla voce del marketplace	Con un pin `sha256`, gli utenti ricevono aggiornamenti quando cambi il pin. Senza uno, gli utenti ricevono aggiornamenti ogni volta che i byte del file zip ospitato cambiano	Plugin pubblicati come file zip su un server statico o repository di artefatti

Se utilizzi versioni esplicite, segui il semantic versioning (MAJOR.MINOR.PATCH): aumenta MAJOR per i cambiamenti che rompono la compatibilità, MINOR per le nuove funzionalità, PATCH per le correzioni di bug. Documenta i cambiamenti in un CHANGELOG.md.

Vedi anche

Plugin - Tutorial e utilizzo pratico
Marketplace dei plugin - Creazione e gestione dei marketplace
Skills - Dettagli dello sviluppo delle skill
Subagents - Configurazione e capacità dell'agent
Hooks - Gestione degli eventi e automazione
MCP - Integrazione di strumenti esterni
Impostazioni - Opzioni di configurazione per i plugin

plugins-reference.md +73 −33

40 40

41Gli skills e i commands vengono rilevati automaticamente quando il plugin viene installato.41Gli skills e i commands vengono rilevati automaticamente quando il plugin viene installato.

42 42

43Se un plugin non ha una directory `skills/` e nessun campo manifest `skills`, un `SKILL.md` nella radice del plugin viene caricato come un singolo skill. Impostare il campo frontmatter `name` per controllare il nome di invocazione dello skill. Senza di esso, Claude Code ricade al nome della directory di installazione, che per i plugin installati dal marketplace è una stringa di versione che cambia ad ogni aggiornamento. Per i plugin che forniscono più di uno skill, utilizzare il layout della directory `skills/` mostrato sopra.43Se un plugin non ha una directory `skills/` e nessun campo manifest `skills`, un `SKILL.md` nella radice del plugin viene caricato come un singolo skill. Impostare il campo frontmatter `name` per controllare il nome di invocazione dello skill. Senza di esso, Claude Code ricade al nome della directory di installazione. Per un plugin [copiato nella cache](#plugin-caching-and-file-resolution), quel nome è una stringa di versione che cambia ad ogni aggiornamento. Per i plugin che forniscono più di uno skill, utilizzare il layout della directory `skills/` mostrato sopra.

44 44

45Negli skills e nei commands del plugin, i campi frontmatter booleani come `disable-model-invocation` accettano `yes`, `no`, `on`, `off`, `1` e `0` in qualsiasi caso di lettera, oltre a `true` e `false`. Prima della v2.1.218, Claude Code riconosceva solo `true` e `false`.45Negli skills e nei commands del plugin, i campi frontmatter booleani come `disable-model-invocation` accettano `yes`, `no`, `on`, `off`, `1` e `0` in qualsiasi caso di lettera, oltre a `true` e `false`. Prima della v2.1.218, Claude Code riconosceva solo `true` e `false`.

46 46

71Prompt di sistema dettagliato per l'agent che descrive il suo ruolo, competenza e comportamento.71Prompt di sistema dettagliato per l'agent che descrive il suo ruolo, competenza e comportamento.

72```72```

73 73

74Gli agent del plugin supportano i campi frontmatter `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background` e `isolation`. L'unico valore `isolation` valido è `"worktree"`. Per motivi di sicurezza, `hooks`, `mcpServers` e `permissionMode` non sono supportati per gli agent forniti dal plugin.74Gli agent del plugin supportano i campi frontmatter `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, [`omitClaudeMd`](/docs/it/sub-agents#supported-frontmatter-fields) e `isolation`. L'unico valore `isolation` valido è `"worktree"`.

76Per motivi di sicurezza, gli agent forniti dal plugin non supportano `hooks`, `mcpServers` o `permissionMode`.

75 77

76Claude Code carica un agent del plugin anche quando il suo frontmatter non ha `name` o non viene analizzato:78Claude Code carica un agent del plugin anche quando il suo frontmatter non ha `name` o non viene analizzato:

77 79

99 101

100**Formato**: Configurazione JSON con matcher di eventi e azioni102**Formato**: Configurazione JSON con matcher di eventi e azioni

101 103

104`hooks/hooks.json` può contenere una chiave `$schema` di livello superiore che nomina un URL JSON Schema per l'autocompletamento dell'editor e la convalida. Claude Code ignora la chiave al momento del caricamento.

105

102**Configurazione hook**:106**Configurazione hook**:

103 107

104```json theme={null}108```json theme={null}

440 Plugin sincronizzati da claude.ai444 Plugin sincronizzati da claude.ai

441</h2>445</h2>

442 446

443In [Cowork](https://claude.com/product/cowork) e [sessioni cloud](/docs/it/cloud-environments#what-carries-over-from-your-setup), Claude Code scarica i plugin abilitati per il vostro account claude.ai in `~/.claude/plugins/synced/` nell'ambiente della sessione stessa e carica ciascuno come `<name>@synced`, senza marketplace e senza record di installazione. Claude Code non li carica nelle sessioni che avviate nel vostro terminale. All'interno di quell'ambiente Cowork o cloud, `claude plugin list` mostra le copie scaricate sotto un'intestazione `Synced from claude.ai`. Prima della v2.1.239, Claude Code caricava questi plugin come `<name>@inline`, l'identità che i plugin `--plugin-dir` utilizzano.447Claude Code carica i plugin abilitati per il vostro account claude.ai, inclusi i plugin che la vostra organizzazione attiva per i suoi membri, insieme ai plugin che installate dai marketplace. Li scarica in `~/.claude/plugins/synced/` e carica ciascuno come `<name>@synced`, senza marketplace e senza record di installazione. Un plugin sincronizzato viene eseguito con la stessa fiducia di un plugin marketplace che avete installato: le sue skills, gli agenti, gli hooks, i server MCP e i server LSP si caricano tutti.

448

449Il luogo in cui Claude Code sincronizza questi plugin dipende dalla sessione:

450

451* In [Cowork](https://claude.com/product/cowork) e [sessioni cloud](/docs/it/cloud-environments#what-carries-over-from-your-setup), Claude Code li scarica nell'ambiente della sessione stessa quando la sessione inizia. Prima della v2.1.239, Claude Code caricava questi plugin come `<name>@inline`, l'identità che i plugin `--plugin-dir` utilizzano.

452* Nelle sessioni di terminale in cui vi accedete con il vostro account claude.ai, Claude Code controlla il vostro account una volta ogni volta che si avvia, quindi scarica i plugin nuovi e aggiornati e rimuove quelli che voi o la vostra organizzazione avete disabilitato, il tutto in background. La sincronizzazione nelle sessioni di terminale richiede Claude Code v2.1.273 o successivo.

453

454Il controllo di avvio viene eseguito in background, quindi può terminare dopo che la vostra sessione è iniziata. Quando aggiunge, aggiorna o rimuove un plugin sincronizzato in una sessione interattiva, Claude Code mostra `Plugins changed. Run /reload-plugins to activate.` Eseguite [`/reload-plugins`](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per caricare la modifica in quella sessione, oppure lasciatela per la prossima volta che avviate Claude Code. Se abilitate un plugin su claude.ai mentre una sessione è in esecuzione, Claude Code lo scarica la prossima volta che si avvia.

444 455

445Gestite un plugin sincronizzato tramite l'ID `<name>@synced` che `claude plugin list` stampa:456La sincronizzazione dei plugin nelle sessioni di terminale viene eseguita nelle stesse condizioni di accesso delle [skills sincronizzate da claude.ai](/docs/it/skills#where-synced-skills-load). Richiede anche un accesso che conceda a Claude Code l'accesso ai plugin del vostro account.

446 457

447* **Disabilitarne uno**: nella sessione sincronizzata, eseguite `claude plugin disable <name>@synced`, oppure chiedete a Claude di eseguirlo. Claude Code salva la scelta come `"<name>@synced": false` nel [`enabledPlugins`](/docs/it/settings-reference#enabledplugins) a livello di utente di quell'ambiente. Per riabilitare il plugin, eseguite `claude plugin enable <name>@synced` nella stessa sessione. Per escludere un plugin da ogni sessione sincronizzata, [disabilitatelo per il vostro account claude.ai](/docs/it/desktop#extend-claude-code). Per escluderlo dalle sessioni sincronizzate di un progetto in ogni ambiente, impostate `"<name>@synced": false` sotto `enabledPlugins` nel `.claude/settings.json` committato del progetto.458Un accesso da una versione precedente di Claude Code acquisisce l'accesso ai plugin la prossima volta che Claude Code rinnova quell'accesso in background, entro poche ore, o subito se eseguite di nuovo `/login`. La sincronizzazione dei plugin inizia la prossima volta che avviate Claude Code dopo di ciò.

448* **Gestite il plugin stesso su claude.ai**: `claude plugin install`, `update` e `uninstall` non si applicano a un plugin sincronizzato. Per rimuoverne uno, disabilitate il plugin per il vostro account claude.ai; la prossima sessione sincronizzata inizierà senza di esso.

449 459

450Quando un plugin abilitato da qualsiasi altra fonte, come un'installazione da marketplace, un plugin [skills-directory](#skills-directory-plugins), o un plugin `--plugin-dir`, corrisponde al nome di un plugin sincronizzato, Claude Code carica quel plugin e segnala la copia sincronizzata come non caricata. Per utilizzare la copia da claude.ai, disabilitate la vostra copia. Prima della v2.1.239, Claude Code caricava la copia sincronizzata al posto di un'installazione da marketplace con lo stesso nome.460`claude plugin list` mostra i plugin sincronizzati sotto un'intestazione `Synced from claude.ai`, e la scheda **Installed** di `/plugin` li elenca con `synced` come loro fonte. Gestite un plugin sincronizzato tramite l'ID `<name>@synced` che `claude plugin list` stampa:

461

462* **Disabilitarne uno**: eseguite `claude plugin disable <name>@synced`, oppure disabilitatelo dalla scheda **Installed** di `/plugin`. Claude Code salva la scelta come `"<name>@synced": false` nel vostro [`enabledPlugins`](/docs/it/settings-reference#enabledplugins) a livello di utente. Per riabilitare il plugin, eseguite `claude plugin enable <name>@synced`.

463* **Mantenerlo fuori ovunque**: [disabilitate il plugin per il vostro account claude.ai](/docs/it/desktop#extend-claude-code). Per mantenerlo fuori da un progetto in ogni ambiente, impostate `"<name>@synced": false` sotto `enabledPlugins` nel `.claude/settings.json` committato di quel progetto.

464* **Gestite il plugin stesso su claude.ai**: `claude plugin install`, `update` e `uninstall` non si applicano a un plugin sincronizzato. Claude Code scarica gli aggiornamenti di un plugin alla prossima sincronizzazione. Per rimuoverne uno, disabilitate il plugin per il vostro account claude.ai, e Claude Code lo rimuove alla prossima sincronizzazione.

465* **Interrompere la sincronizzazione su una macchina**: impostate [`syncClaudeAiPlugins`](/docs/it/settings-reference#syncclaudeaiplugins) a `false` nelle vostre impostazioni utente. Claude Code smette di scaricare, e la prossima volta che si avvia sposta i plugin che ha già sincronizzato in `~/.claude/plugins/.trash/` e non li carica più. La vostra organizzazione può impostare la stessa chiave nelle [impostazioni gestite](/docs/it/managed-settings), oppure disabilitare Skills su claude.ai, il che interrompe anche la sincronizzazione dei plugin.

466

467Non potete disabilitare un plugin che la vostra organizzazione contrassegna come obbligatorio su claude.ai. Claude Code lo carica anche se lo avete disabilitato in precedenza, e `claude plugin disable` rifiuta con `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` In `claude plugin list`, questi plugin sono contrassegnati `required by your org`.

468

469Quando un plugin abilitato da qualsiasi altra fonte corrisponde al nome di un plugin sincronizzato, Claude Code carica quel plugin e segnala la copia sincronizzata come non caricata. Le altre fonti includono installazioni da marketplace, plugin [skills-directory](#skills-directory-plugins), plugin `--plugin-dir` e plugin integrati in Claude Code. Per utilizzare la copia da claude.ai, disabilitate la vostra copia. Prima della v2.1.239, Claude Code caricava la copia sincronizzata al posto di un'installazione da marketplace con lo stesso nome.

451 470

452***471***

453 472

534</h3>553</h3>

535 554

537| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |556| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- |

538| `$schema` | string | URL dello schema JSON per l'autocompletamento e la convalida dell'editor. Claude Code ignora questo campo al momento del caricamento. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |557| `$schema` | string | URL dello schema JSON per l'autocompletamento e la convalida dell'editor. Claude Code ignora questo campo al momento del caricamento. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |

539| `displayName` | string | Nome leggibile mostrato nel selettore `/plugin` e in altre superfici dell'interfaccia utente. Per un plugin installato dal marketplace, un `displayName` sulla [voce del marketplace](/docs/it/plugin-marketplaces#optional-plugin-fields) ha la precedenza su questo valore. Quando nessun nome di visualizzazione è impostato in nessuno dei due posti, gli utenti vedono `name`. A differenza di `name`, può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per lo spazio dei nomi o la ricerca. | `"Deployment Tools"` |558| `displayName` | string | Nome leggibile mostrato nel selettore `/plugin` e in altre superfici dell'interfaccia utente. Per un plugin installato dal marketplace, un `displayName` sulla [voce del marketplace](/docs/it/plugin-marketplaces#optional-plugin-fields) ha la precedenza su questo valore. Quando nessun nome di visualizzazione è impostato in nessuno dei due posti, gli utenti vedono `name`. A differenza di `name`, può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per lo spazio dei nomi o la ricerca. | `"Deployment Tools"` |

540| `version` | string | Facoltativo. Versione semantica. L'impostazione di questa opzione fissa il plugin a quella stringa di versione, quindi gli utenti ricevono aggiornamenti solo quando la si incrementa, ad eccezione di una [`command` source](/docs/it/plugin-marketplaces#command-sources); vedere [Gestione delle versioni](#version-management). Se impostato anche nella voce del marketplace, `plugin.json` vince. Se omesso, la versione proviene dalla prossima fonte in [Gestione delle versioni](#version-management). | `"2.1.0"` |559| `version` | string | Facoltativo. Versione semantica. L'impostazione di questa opzione fissa il plugin a quella stringa di versione, quindi gli utenti ricevono aggiornamenti solo quando la si incrementa, ad eccezione di una [`command` source](/docs/it/plugin-marketplaces#command-sources) o un plugin [caricato in place](#plugin-caching-and-file-resolution); vedere [Gestione delle versioni](#version-management). Se impostato anche nella voce del marketplace, `plugin.json` vince. Se omesso, la versione proviene dalla prossima fonte in [Gestione delle versioni](#version-management). | `"2.1.0"` |

542| `author` | object | Informazioni sull'autore | `{"name": "Dev Team", "email": "dev@company.com"}` |561| `author` | object | Informazioni sull'autore | `{"name": "Dev Team", "email": "dev@company.com"}` |

553 572

554Impostare `defaultEnabled: false` in `plugin.json` per distribuire un plugin che si installa disabilitato. L'utente lo attiva con `claude plugin enable <plugin>` o l'interfaccia `/plugin`. Utilizzare questa opzione per i plugin che aggiungono costi o ambito a cui un utente dovrebbe acconsentire esplicitamente, come uno che si connette a un servizio esterno.573Impostare `defaultEnabled: false` in `plugin.json` per distribuire un plugin che si installa disabilitato. L'utente lo attiva con `claude plugin enable <plugin>` o l'interfaccia `/plugin`. Utilizzare questa opzione per i plugin che aggiungono costi o ambito a cui un utente dovrebbe acconsentire esplicitamente, come uno che si connette a un servizio esterno.

555 574

556`defaultEnabled` è il fallback quando nient'altro ha deciso lo stato del plugin. Due cose hanno la precedenza su di esso:575`defaultEnabled` è il fallback quando nient'altro ha deciso lo stato del plugin. L'impostazione dell'utente e un requisito di dipendenza hanno la precedenza su di esso:

557 576

558* **L'impostazione dell'utente**: una voce per il plugin in `enabledPlugins` in qualsiasi ambito di impostazioni. Una volta scritta, persiste tra gli aggiornamenti e le reinstallazioni del plugin, quindi modificare `defaultEnabled` in una versione successiva non capovolge un utente esistente.577* **L'impostazione dell'utente**: una voce per il plugin in `enabledPlugins` in qualsiasi ambito di impostazioni. Una volta scritta, persiste tra gli aggiornamenti e le reinstallazioni del plugin, quindi modificare `defaultEnabled` in una versione successiva non capovolge un utente esistente.

559* **Un requisito di dipendenza**: quando un plugin è richiesto da un altro che è attivo, Claude Code scrive `true` per esso al momento dell'installazione o dell'abilitazione. Questo gli dà un'impostazione esplicita, quindi il suo valore predefinito non si applica più. Vedere [Abilitare o disabilitare un plugin con dipendenze](/docs/it/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).578* **Un requisito di dipendenza**: quando un plugin è richiesto da un altro che è attivo, Claude Code scrive `true` per esso al momento dell'installazione o dell'abilitazione. Questo gli dà un'impostazione esplicita, quindi il suo valore predefinito non si applica più. Vedere [Abilitare o disabilitare un plugin con dipendenze](/docs/it/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).

579| `experimental.evals` | string\|array | Directory sotto la radice del plugin che contiene i [casi di eval](/docs/it/plugin-evals#use-a-different-eval-directory) del plugin, quando non è la directory predefinita `evals/`. `claude plugin eval --eval-dir` la sostituisce | `"quality/evals"` |598| `experimental.evals` | string\|array | Directory sotto la radice del plugin che contiene i [casi di eval](/docs/it/plugin-evals#use-a-different-eval-directory) del plugin, quando non è la directory predefinita `evals/`. `claude plugin eval --eval-dir` la sostituisce | `"quality/evals"` |

582| `dependencies` | array | Altri plugin richiesti da questo plugin, facoltativamente con vincoli di versione semver. Vedere [Vincolare le versioni delle dipendenze del plugin](/docs/it/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |601| `dependencies` | array | Altri plugin richiesti da questo plugin, facoltativamente con vincoli di versione semver. Vedere [Vincolare le versioni delle dipendenze del plugin](/docs/it/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

583 602

584<h3 id="experimental-components">603<h3 id="experimental-components">

614Le chiavi devono essere identificatori validi. Ogni opzione supporta questi campi:633Le chiavi devono essere identificatori validi. Ogni opzione supporta questi campi:

615 634

617| :------------ | :----------- | :---------------------------------------------------------------------------------------------------- |636| :------------ | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |

618| `type` | Sì | Uno di `string`, `number`, `boolean`, `directory`, o `file` |637| `type` | Sì | Uno di `string`, `number`, `boolean`, `directory`, o `file` |

619| `title` | Sì | Etichetta mostrata nella finestra di dialogo di configurazione |638| `title` | Sì | Etichetta mostrata nella finestra di dialogo di configurazione |

620| `description` | Sì | Testo di aiuto mostrato sotto il campo |639| `description` | Sì | Testo di aiuto mostrato sotto il campo |

621| `sensitive` | No | Se `true`, maschera l'input e memorizza il valore nell'archiviazione sicura invece di `settings.json` |640| `sensitive` | No | Se `true`, maschera l'input e memorizza il valore nell'archiviazione sicura invece di `settings.json` |

622| `required` | No | Se `true`, la convalida fallisce quando il campo è vuoto |641| `required` | No | Se `true`, la convalida fallisce quando il campo è vuoto |

623| `default` | No | Valore utilizzato quando l'utente non fornisce nulla |642| `default` | No | Valore utilizzato quando l'utente non fornisce nulla |

643| `options` | No | Per il tipo `string`, i valori che il campo accetta, mostrati in `/config` come un selettore su di essi. Richiede Claude Code v2.1.271 o successivo |

624| `multiple` | No | Per il tipo `string`, consenti un array di stringhe |644| `multiple` | No | Per il tipo `string`, consenti un array di stringhe |

625| `min` / `max` | No | Limiti per il tipo `number` |645| `min` / `max` | No | Limiti per il tipo `number` |

626 646

647Ad eccezione dei campi `sensitive` e degli elenchi `multiple`, ogni campo di ogni plugin abilitato appare anche come una riga nel pannello `/config`. Le righe richiedono Claude Code v2.1.269 o successivo.

648

627Ogni valore è disponibile per la sostituzione come `${user_config.KEY}` nelle configurazioni del server MCP e LSP e nei comandi hook. I valori non sensibili possono anche essere sostituiti nel contenuto di skill e agenti. Tutti i valori vengono esportati ai processi hook come variabili di ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, dove `<KEY>` è la chiave dell'opzione in maiuscolo.649Ogni valore è disponibile per la sostituzione come `${user_config.KEY}` nelle configurazioni del server MCP e LSP e nei comandi hook. I valori non sensibili possono anche essere sostituiti nel contenuto di skill e agenti. Tutti i valori vengono esportati ai processi hook come variabili di ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, dove `<KEY>` è la chiave dell'opzione in maiuscolo.

628 650

629I campi che vengono eseguiti in una shell rifiutano `${user_config.*}`: sostituire un valore configurato in un comando shell consentirebbe alla shell di eseguire qualsiasi cosa contenga quel valore, quindi il componente fallisce con un [errore](/docs/it/errors#plugin-command-references-user-config) invece. Ogni campo rifiutato ha un modo alternativo per passare il valore:651I campi che vengono eseguiti in una shell rifiutano `${user_config.*}`: sostituire un valore configurato in un comando shell consentirebbe alla shell di eseguire qualsiasi cosa contenga quel valore, quindi il componente fallisce con un [errore](/docs/it/errors#plugin-command-references-user-config) invece. Ogni campo rifiutato ha un modo alternativo per passare il valore:

733| `${CLAUDE_PLUGIN_DATA}` | [Directory persistente](#persistent-data-directory) che sopravvive agli aggiornamenti del plugin, creata al primo riferimento | Dipendenze installate come `node_modules` o ambienti virtuali Python, codice generato e cache |755| `${CLAUDE_PLUGIN_DATA}` | [Directory persistente](#persistent-data-directory) che sopravvive agli aggiornamenti del plugin, creata al primo riferimento | Dipendenze installate come `node_modules` o ambienti virtuali Python, codice generato e cache |

734| `${CLAUDE_PROJECT_DIR}` | La radice del progetto | Script e file di configurazione locali del progetto |756| `${CLAUDE_PROJECT_DIR}` | La radice del progetto | Script e file di configurazione locali del progetto |

735 757

736Tutti e tre vengono esportati come variabili di ambiente ai processi hook e ai sottoprocessi del server MCP e LSP. Quali campi sostituiscono inline dipende dal componente del plugin:758Tutti e tre vengono esportati come variabili di ambiente ai processi hook e ai sottoprocessi del server MCP e LSP. Non sono presenti nell'ambiente dei comandi che Claude esegue attraverso lo strumento Bash, nella sessione principale o in un subagent. Nel contenuto del plugin, scrivere il placeholder invece, e Claude Code sostituisce il percorso inline quando carica il contenuto. Quali campi sostituiscono inline dipende dal componente del plugin:

737 759

738| Componente del plugin | Campi dove i placeholder si risolvono |760| Componente del plugin | Campi dove i placeholder si risolvono |

739| :----------------------------- | :------------------------------------------ |761| :----------------------------- | :------------------------------------------ |

762}784}

763```785```

764 786

765`${CLAUDE_PLUGIN_ROOT}` cambia quando il plugin si aggiorna. La directory della versione precedente rimane su disco per un periodo di grazia dopo un aggiornamento, ma trattarla come effimera e non scrivere stato lì. Vedere [plugin caching](#plugin-caching-and-file-resolution) per la semantica di pulizia.787Per un plugin copiato, `${CLAUDE_PLUGIN_ROOT}` cambia quando il plugin si aggiorna. La directory della versione precedente rimane su disco per un periodo di grazia dopo un aggiornamento, ma trattarla come effimera e non scrivere stato lì. Per un plugin caricato in place da un marketplace di directory locale, la variabile punta alla directory sorgente stabile. Vedere [plugin caching](#plugin-caching-and-file-resolution) per quali plugin vengono copiati e per la semantica di pulizia.

766 788

767Quando un plugin si aggiorna a metà sessione, i comandi hook, i monitor, i server MCP e i server LSP continuano a utilizzare il percorso della versione precedente. Eseguire `/reload-plugins` per passare i hook, i server MCP e i server LSP al nuovo percorso; i monitor richiedono un riavvio della sessione. In una sessione senza un terminale interattivo, il ricaricamento lascia i server MCP del plugin sul percorso precedente fino alla sessione successiva.789Quando un plugin copiato si aggiorna a metà sessione, i comandi hook, i monitor, i server MCP e i server LSP continuano a utilizzare il percorso della versione precedente. Eseguire `/reload-plugins` per passare i hook, i server MCP e i server LSP al nuovo percorso; i monitor richiedono un riavvio della sessione. In una sessione senza un terminale interattivo, il ricaricamento lascia i server MCP del plugin sul percorso precedente fino alla sessione successiva.

768 790

769Per un plugin con una `command` source, Claude Code [può ricaricare il plugin stesso](/docs/it/plugin-marketplaces#when-claude-code-re-runs-the-command).791Per un plugin con una `command` source, Claude Code [può ricaricare il plugin stesso](/docs/it/plugin-marketplaces#when-claude-code-re-runs-the-command).

770 792

825 Caching dei plugin e risoluzione dei file847 Caching dei plugin e risoluzione dei file

826</h2>848</h2>

827 849

828I plugin vengono specificati in uno di due modi:850I plugin vengono specificati in uno di tre modi:

829 851

830* Tramite `claude --plugin-dir` o `claude --plugin-url`, per la durata di una sessione.852* Tramite `claude --plugin-dir` o `claude --plugin-url`, per la durata di una sessione.

831* Tramite un marketplace, installato per sessioni future.853* Tramite un marketplace, installato per sessioni future.

854* Tramite il vostro account claude.ai, [sincronizzato](#synced-plugins) in `~/.claude/plugins/synced/`.

832 855

833Per motivi di sicurezza e verifica, Claude Code copia i plugin del *marketplace* nella **cache dei plugin** locale dell'utente (`~/.claude/plugins/cache`) piuttosto che utilizzarli sul posto, ad eccezione delle [`command` sources in link mode](/docs/it/plugin-marketplaces#copy-mode-and-link-mode), che Claude Code utilizza sul posto tramite link nella voce della cache.856Per motivi di sicurezza e verifica, Claude Code copia i plugin del *marketplace* nella **cache dei plugin** locale dell'utente (`~/.claude/plugins/cache`), a meno che il plugin non si carichi sul posto. Una [`command` source in link mode](/docs/it/plugin-marketplaces#copy-mode-and-link-mode) si carica sul posto tramite link nella voce della cache. Una [relative path source](/docs/it/plugin-marketplaces#relative-paths) in un marketplace aggiunto da una directory locale si carica sul posto dalla cartella del marketplace.

857

858Per un plugin caricato sul posto da un marketplace di directory locale, le vostre modifiche alla directory di origine hanno effetto all'avvio della sessione successiva o `/reload-plugins`. Non avete bisogno di un bump di versione. I processi hook del plugin e i server MCP e LSP ricevono un `CLAUDE_PLUGIN_ROOT` che punta alla directory di origine. Claude Code non installa le [dipendenze dei pacchetti Node.js](#node-js-package-dependencies) del plugin nella directory di origine. Installatele lì voi stessi, o da un hook nella [directory dei dati persistenti](#persistent-data-directory).

834 859

835Per i plugin copiati, ogni versione installata è una directory separata nella cache, raggruppata per marketplace e plugin e denominata per la versione risolta, con la propria copia dei file del plugin e delle [dipendenze dei pacchetti Node.js](#node-js-package-dependencies). Una dipendenza risolta da un [release tag](/docs/it/plugin-dependencies#tag-plugin-releases-for-version-resolution) ottiene un nome di directory con un suffisso commit-SHA.860Per i plugin copiati, ogni versione installata è una directory separata nella cache, raggruppata per marketplace e plugin e denominata per la versione risolta, con la propria copia dei file del plugin e delle [dipendenze dei pacchetti Node.js](#node-js-package-dependencies). Una dipendenza risolta da un [release tag](/docs/it/plugin-dependencies#tag-plugin-releases-for-version-resolution) ottiene un nome di directory con un suffisso commit-SHA.

836 861

855 880

856Se un plugin contiene più di uno di questi lockfile, Claude Code utilizza la prima corrispondenza, controllando in ordine: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`. Claude Code salta `yarn.lock` e `pnpm-lock.yaml` perché Yarn e pnpm supportano hook di configurazione in fase di risoluzione che bypassano `--ignore-scripts`.881Se un plugin contiene più di uno di questi lockfile, Claude Code utilizza la prima corrispondenza, controllando in ordine: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.

882

883Claude Code salta l'installazione in due casi, ognuno con la propria soluzione:

884

885* Se il vostro plugin contiene solo un `yarn.lock` o `pnpm-lock.yaml`, sostituiscilo con un lockfile npm.

886* Se un `bunfig.toml` si trova accanto al lockfile bun, rimuovete il `bunfig.toml`, o sostituite il lockfile bun con un lockfile npm.

857 887

858Fornite un lockfile npm per la portata più ampia. Claude Code esegue il gestore di pacchetti del lockfile corrispondente dal PATH dell'utente e non esegue il fallback all'altro lockfile se manca. Per un plugin distribuito tramite una fonte npm, utilizzate `npm-shrinkwrap.json`; npm esclude `package-lock.json` dai pacchetti pubblicati.888Fornite un lockfile npm per la portata più ampia. Claude Code esegue il gestore di pacchetti del lockfile corrispondente dal PATH dell'utente e non esegue il fallback all'altro lockfile se manca. Per un plugin distribuito tramite una fonte npm, utilizzate `npm-shrinkwrap.json`; npm esclude `package-lock.json` dai pacchetti pubblicati.

859 889

863* **Nessuno script del ciclo di vita:** `--ignore-scripts` impedisce l'esecuzione degli script `preinstall`, `install` e `postinstall`, in modo che le dipendenze che compilano moduli nativi in questi script scarichino ma non compilino durante questa installazione.893* **Nessuno script del ciclo di vita:** `--ignore-scripts` impedisce l'esecuzione degli script `preinstall`, `install` e `postinstall`, in modo che le dipendenze che compilano moduli nativi in questi script scarichino ma non compilino durante questa installazione.

864* **Timeout di 60 secondi:** Claude Code interrompe un'installazione che dura più a lungo e la tratta come non riuscita.894* **Timeout di 60 secondi:** Claude Code interrompe un'installazione che dura più a lungo e la tratta come non riuscita.

865 895

866Il recupero di un plugin da fonte npm stesso esegue `npm install` con script del ciclo di vita abilitati, prima che questa installazione di dipendenze venga eseguita.896Claude Code recupera un plugin da fonte npm prima di questa installazione di dipendenze, e nessuno degli script di installazione del pacchetto stesso viene eseguito durante il recupero. Vedere [pacchetti npm](/docs/it/plugin-marketplaces#npm-packages).

867 897

868Un'installazione non riuscita o saltata non blocca mai il plugin. Quando l'installazione fallisce, o Claude Code salta un lockfile yarn o pnpm, registra il motivo come avviso nell'[output di debug](#debugging-commands). Un plugin con un `package.json` e nessun lockfile viene saltato senza una voce di log. Un'installazione scaduta può lasciare un albero `node_modules` parziale nella copia memorizzata nella cache.898Un'installazione non riuscita o saltata non blocca mai il plugin. Quando l'installazione fallisce, o Claude Code salta un lockfile yarn o pnpm o un `bunfig.toml`, registra il motivo come avviso nell'[output di debug](#debugging-commands). Un plugin con un `package.json` e nessun lockfile viene saltato senza una voce di log. Un'installazione scaduta può lasciare un albero `node_modules` parziale nella copia memorizzata nella cache.

869 899

870Non potete disattivare l'installazione automatica; nessuna impostazione o variabile di ambiente la disabilita. In reti ristrette, vedere i [requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements) per gli host da consentire.900Non potete disattivare l'installazione automatica; nessuna impostazione o variabile di ambiente la disabilita. In reti ristrette, vedere i [requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements) per gli host da consentire.

871 901

1061Il comando accetta queste opzioni:1091Il comando accetta queste opzioni:

1062 1092

1064| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1094| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |

1066| `--config <key=value>` | Imposta un'opzione [`userConfig`](#user-configuration) dichiarata nel manifest del plugin. Ripeti il flag per impostare più opzioni | |1096| `--config <key=value>` | Imposta un'opzione [`userConfig`](#user-configuration) dichiarata nel manifest del plugin. Ripeti il flag per impostare più opzioni | |

1067| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |1097| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY, a meno che non passi `--accept-command`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |

1098| `--accept-command <sha256>` | Accetta il comando dichiarato dal marketplace il cui `sha256` una precedente esecuzione [`--json`](#plugin-json-result) ha segnalato in `shownCommand`, al posto di `-y`. L'accettazione conta esattamente per quel comando, plugin e catalogo del marketplace. Se uno qualsiasi di essi è cambiato da quando il comando è stato visualizzato, incluso attraverso l'aggiornamento del marketplace della stessa esecuzione, Claude Code non accetta il digest e mostra di nuovo il comando. Non può essere combinato con `-y`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale. Richiede Claude Code v2.1.271 o successivo | |

1068| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi [Formato del risultato JSON](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |1099| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi [Formato del risultato JSON](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1070 1101

1078 1109

1079Altri campi, come `pluginId`, `scope` e `failureCode`, appaiono solo quando applicabili. L'opzione `--json` su `plugin uninstall`, `plugin update`, `plugin enable` e `plugin disable` stampa lo stesso oggetto con i campi propri di quel sottocomando. Un errore di utilizzo, come uno `--scope` non valido, non stampa alcuna riga di risultato ed esce con 1 con il motivo su stderr.1110Altri campi, come `pluginId`, `scope` e `failureCode`, appaiono solo quando applicabili. L'opzione `--json` su `plugin uninstall`, `plugin update`, `plugin enable` e `plugin disable` stampa lo stesso oggetto con i campi propri di quel sottocomando. Un errore di utilizzo, come uno `--scope` non valido, non stampa alcuna riga di risultato ed esce con 1 con il motivo su stderr.

1080 1111

1112Quando un'esecuzione visualizza un comando dichiarato dal marketplace e non lo esegue, il risultato `failed` porta anche un oggetto `shownCommand` i cui campi includono il comando come visualizzato, il plugin a cui appartiene e lo `sha256` del comando. Per accettare esattamente quel comando, esegui di nuovo con quello `sha256` come `--accept-command`. Richiede Claude Code v2.1.271 o successivo.

1113

1114Se `shownCommand.acceptCommandMatched` è `false`, il digest che hai passato non corrisponde al comando ora visualizzato. Mostra quel comando a una persona prima di passare il suo `sha256`.

1115

1081Questi esempi mostrano invocazioni comuni:1116Questi esempi mostrano invocazioni comuni:

1082 1117

1083```bash theme={null}1118```bash theme={null}

1159 1194

1160Il comando accetta questi argomenti:1195Il comando accetta questi argomenti:

1161 1196

1162* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`1197* `<plugin>`: Nome del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` per un [plugin sincronizzato da claude.ai](#synced-plugins)

1163 1198

1164Il comando accetta queste opzioni:1199Il comando accetta queste opzioni:

1165 1200

1173 plugin disable1208 plugin disable

1174</h3>1209</h3>

1175 1210

1176Disabilita un plugin senza disinstallarlo. Quando il target è installato da un marketplace, il comando fallisce se un altro plugin abilitato [dipende da](/docs/it/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) esso. Il messaggio di errore include un comando concatenato che disabilita prima ogni dipendente.1211Disabilita un plugin senza disinstallarlo.

1212

1213Quando il target è installato da un marketplace, il comando fallisce se un altro plugin abilitato [dipende da](/docs/it/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) esso. Il messaggio di errore include un comando concatenato che disabilita prima ogni dipendente.

1214

1215Per un [synced plugin](#synced-plugins) che la tua organizzazione richiede, il comando fallisce e non salva nulla.

1177 1216

1178```bash theme={null}1217```bash theme={null}

1179claude plugin disable [plugin] [options]1218claude plugin disable [plugin] [options]

1181 1220

1182Il comando accetta questi argomenti:1221Il comando accetta questi argomenti:

1183 1222

1184* `[plugin]`: Nome del plugin o `plugin-name@marketplace-name`. Facoltativo quando si usa `--all`1223* `[plugin]`: Nome del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` per un [plugin sincronizzato da claude.ai](#synced-plugins). Facoltativo quando si usa `--all`

1185 1224

1186Il comando accetta queste opzioni:1225Il comando accetta queste opzioni:

1187 1226

1209Il comando accetta queste opzioni:1248Il comando accetta queste opzioni:

1210 1249

1212| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1251| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |

1214| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |1253| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY, a meno che non passi `--accept-command`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |

1254| `--accept-command <sha256>` | Accetta il comando dichiarato dal marketplace il cui `sha256` una precedente esecuzione [`--json`](#plugin-json-result) ha segnalato in `shownCommand`, al posto di `-y`. L'accettazione conta esattamente per quel comando, plugin e catalogo del marketplace. Se uno qualsiasi di essi è cambiato da quando il comando è stato visualizzato, incluso attraverso l'aggiornamento del marketplace della stessa esecuzione, Claude Code non accetta il digest e mostra di nuovo il comando. Non può essere combinato con `-y`. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale. Richiede Claude Code v2.1.271 o successivo | |

1215| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |1255| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1217 1257

1242All'interno di una sessione interattiva, `/plugin list` stampa un elenco simile inline, ma copre solo i plugin installati dal marketplace:1282All'interno di una sessione interattiva, `/plugin list` stampa un elenco simile inline, ma copre solo i plugin installati dal marketplace:

1243 1283

1244* I plugin caricati dalle directory delle skill appaiono nell'interfaccia `/plugin` e in `claude plugin list`, ma non nell'output inline `/plugin list`.1284* I plugin caricati dalle directory delle skill appaiono nell'interfaccia `/plugin` e in `claude plugin list`, ma non nell'output inline `/plugin list`.

1245* Su Claude Code v2.1.239 o successivo, i [plugin sincronizzati da claude.ai](#synced-plugins) appaiono in `claude plugin list` quando lo esegui nell'ambiente in cui una sessione sincronizzata li ha scaricati. Non appaiono nell'output inline `/plugin list`.1285* I [plugin sincronizzati da claude.ai](#synced-plugins) appaiono in `claude plugin list` su Claude Code v2.1.239 o successivo e nell'interfaccia `/plugin`, ma non nell'output inline `/plugin list`.

1246* I plugin caricati per la sessione con `--plugin-dir` o `--plugin-url` appaiono nell'interfaccia `/plugin` e in `claude plugin list` solo quando lo stesso flag precede il sottocomando, come in `claude --plugin-dir <dir> plugin list`. Solo il nome del flag identifica la loro posizione, quindi un semplice `claude plugin list` non può trovarli, a differenza dei plugin sincronizzati e dei plugin della directory delle skill, le cui directory fisse Claude Code scansiona.1286* I plugin caricati per la sessione con `--plugin-dir` o `--plugin-url` appaiono nell'interfaccia `/plugin` e in `claude plugin list` solo quando lo stesso flag precede il sottocomando, come in `claude --plugin-dir <dir> plugin list`. Solo il nome del flag identifica la loro posizione, quindi un semplice `claude plugin list` non può trovarli, a differenza dei plugin sincronizzati e dei plugin della directory delle skill, le cui directory fisse Claude Code scansiona.

1247 1287

1248Il modulo interattivo accetta `--enabled` o `--disabled` per mostrare solo i plugin in quello stato, e `ls` come abbreviazione per `list`.1288Il modulo interattivo accetta `--enabled` o `--disabled` per mostrare solo i plugin in quello stato, e `ls` come abbreviazione per `list`.

1520 Gestione delle versioni1560 Gestione delle versioni

1521</h3>1561</h3>

1522 1562

1523Claude Code utilizza la versione del plugin come chiave di cache che determina se un aggiornamento è disponibile. Quando esegui `/plugin update` o l'aggiornamento automatico si attiva, Claude Code calcola la versione corrente e salta l'aggiornamento se corrisponde a quella già installata.1563Claude Code utilizza la versione del plugin come chiave di cache che determina se un aggiornamento è disponibile. Quando esegui `/plugin update` o l'aggiornamento automatico si attiva, Claude Code calcola la versione corrente e salta l'aggiornamento se corrisponde a quella già installata. Un plugin [caricato in place](#plugin-caching-and-file-resolution) da un marketplace di directory locale carica i suoi file sorgente correnti all'inizio di ogni sessione, indipendentemente da ciò che dice la sua stringa di versione.

1524 1564

1525Per ogni tipo di sorgente eccetto `command`, Claude Code risolve la versione dal primo di questi che è impostato:1565Per ogni tipo di sorgente eccetto `command`, Claude Code risolve la versione dal primo di questi che è impostato:

1526 1566

15282. Il campo `version` nella voce del plugin nel marketplace in `marketplace.json`15682. Il campo `version` nella voce del plugin nel marketplace in `marketplace.json`

15293. Lo SHA del commit git della sorgente del plugin, per le sorgenti `github`, `url`, `git-subdir` e relative-path in un marketplace ospitato su git15693. Lo SHA del commit git della sorgente del plugin, per le sorgenti `github`, `url`, `git-subdir` e relative-path in un marketplace ospitato su git

15304. Il digest SHA-256, per le [sorgenti `archive`](/docs/it/plugin-marketplaces#zip-archives): il pin `sha256` nella voce del marketplace, o il digest del file scaricato quando non imposti alcun pin. Claude Code lo accorcia ai primi 12 caratteri15704. Il digest SHA-256, per le [sorgenti `archive`](/docs/it/plugin-marketplaces#zip-archives): il pin `sha256` nella voce del marketplace, o il digest del file scaricato quando non imposti alcun pin. Claude Code lo accorcia ai primi 12 caratteri

15315. `unknown`, per le sorgenti `npm` o le directory locali non all'interno di un repository git15715. `unknown`, per le sorgenti `npm` o le directory locali quando né la directory del plugin né il suo marketplace è un repository git. Claude Code non prende la versione da un repository che racchiude il percorso di installazione, come un `~/.claude` gestito da git

1532 1572

1533Per una [sorgente `command`](/docs/it/plugin-marketplaces#command-sources), Claude Code deriva sempre la versione da ciò che il comando ha prodotto: un hash di contenuto di 12 caratteri da solo, o aggiunto alla versione `plugin.json` come `<version>-<hash>` quando uno è impostato. Claude Code ignora il campo `version` della voce del marketplace per le sorgenti command. Un comando il cui output con hash cambia produce quindi una nuova versione, anche quando la stringa di versione creata rimane la stessa. In [link mode](/docs/it/plugin-marketplaces#copy-mode-and-link-mode), l'hash copre il percorso reale della directory stampata e le sue voci di primo livello piuttosto che i contenuti dei file.1573Per una [sorgente `command`](/docs/it/plugin-marketplaces#command-sources), Claude Code deriva sempre la versione da ciò che il comando ha prodotto: un hash di contenuto di 12 caratteri da solo, o aggiunto alla versione `plugin.json` come `<version>-<hash>` quando uno è impostato. Claude Code ignora il campo `version` della voce del marketplace per le sorgenti command. Un comando il cui output con hash cambia produce quindi una nuova versione, anche quando la stringa di versione creata rimane la stessa. In [link mode](/docs/it/plugin-marketplaces#copy-mode-and-link-mode), l'hash copre il percorso reale della directory stampata e le sue voci di primo livello piuttosto che i contenuti dei file.

1534 1574

1535Per questi tipi di sorgente, questo ti dà tre modi per versioning di un plugin:1575Per questi tipi di sorgente, questo ti dà tre modi per versioning di un plugin:

1536 1576

1538| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |1578| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |

1539| **Versione esplicita** | Imposta `"version": "2.1.0"` in `plugin.json` | Gli utenti ricevono aggiornamenti solo quando aumenti questo campo. Spingere nuovi commit senza aumentarlo non ha effetto, e `/plugin update` segnala "already at the latest version". | Plugin pubblicati con cicli di rilascio stabili |1579| **Versione esplicita** | Imposta `"version": "2.1.0"` in `plugin.json` | Gli utenti ricevono aggiornamenti solo quando aumenti questo campo. Spingere nuovi commit senza aumentarlo non ha effetto, e `/plugin update` segnala "already at the latest version". Per un plugin [caricato in place](#plugin-caching-and-file-resolution), il nuovo contenuto si carica comunque. | Plugin pubblicati con cicli di rilascio stabili |

1540| **Versione Commit-SHA** | Ometti `version` sia da `plugin.json` che dalla voce del marketplace | Gli utenti ricevono aggiornamenti ogni volta che il commit risolto della sorgente cambia | Plugin interni o di team in sviluppo attivo |1580| **Versione Commit-SHA** | Ometti `version` sia da `plugin.json` che dalla voce del marketplace | Gli utenti ricevono aggiornamenti ogni volta che il commit risolto della sorgente cambia | Plugin interni o di team in sviluppo attivo |

1541| **Versione Digest** | Utilizza una [sorgente `archive`](/docs/it/plugin-marketplaces#zip-archives) e ometti `version` sia da `plugin.json` che dalla voce del marketplace | Con un pin `sha256`, gli utenti ricevono aggiornamenti quando cambi il pin. Senza uno, gli utenti ricevono aggiornamenti ogni volta che i byte del file zip ospitato cambiano | Plugin pubblicati come file zip su un server statico o repository di artefatti |1581| **Versione Digest** | Utilizza una [sorgente `archive`](/docs/it/plugin-marketplaces#zip-archives) e ometti `version` sia da `plugin.json` che dalla voce del marketplace | Con un pin `sha256`, gli utenti ricevono aggiornamenti quando cambi il pin. Senza uno, gli utenti ricevono aggiornamenti ogni volta che i byte del file zip ospitato cambiano | Plugin pubblicati come file zip su un server statico o repository di artefatti |

1542 1582

plugins-reference.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

Plugins reference

Riferimento dei componenti del plugin

Skills

Agents

Hooks

MCP servers

LSP servers

Monitors

Themes

Ambiti di installazione dei plugin

Plugin della directory skills

Scegli da dove il plugin viene caricato

Modifica, ricarica e disabilita un plugin della directory skills

Plugin sincronizzati da claude.ai

Schema del manifest del plugin

Schema completo

Campi obbligatori

Campi non riconosciuti

Campi di metadati

Abilitazione predefinita

Campi del percorso del componente

Componenti sperimentali

Configurazione utente

Canali

Regole di comportamento del percorso

Variabili di ambiente

Directory di dati persistenti

Caching dei plugin e risoluzione dei file

Dipendenze dei pacchetti Node.js

Limitazioni dell'attraversamento dei percorsi

Condividere file all'interno di un marketplace con symlink

Struttura della directory dei plugin

Layout standard dei plugin

Riferimento delle posizioni dei file

Riferimento dei comandi CLI

plugin init

plugin install

plugin uninstall

plugin prune

plugin enable

plugin disable

plugin update

plugin list

plugin details

plugin validate

plugin eval

plugin eval init

plugin tag

Strumenti di debug e sviluppo

Comandi di debug

Problemi comuni

Messaggi di errore di esempio

Risoluzione dei problemi degli hook

Risoluzione dei problemi del server MCP

Errori di struttura della directory

Riferimento di distribuzione e versioning

Gestione delle versioni

Vedi anche