Creare e distribuire un marketplace di plugin

Crea e ospita marketplace di plugin per distribuire estensioni Claude Code tra team e comunità.

Un plugin marketplace è un catalogo che ti consente di distribuire plugin ad altri. I marketplace forniscono scoperta centralizzata, tracciamento delle versioni, aggiornamenti automatici e supporto per più tipi di fonte, inclusi repository git e percorsi locali. Questa guida ti mostra come creare il tuo marketplace per condividere plugin con il tuo team o comunità.

Stai cercando di installare plugin da un marketplace esistente? Vedi Scopri e installa plugin precostruiti.

Panoramica

La creazione e la distribuzione di un marketplace comporta:

Creazione di plugin: crea uno o più plugin con skills, agenti, hooks, server MCP o server LSP. Questa guida presuppone che tu abbia già plugin da distribuire; vedi Crea plugin per i dettagli su come crearli.
Creazione di un file marketplace: definisci un marketplace.json che elenca i tuoi plugin e dove trovarli. Vedi Crea il file marketplace.
Ospita il marketplace: esegui il push su GitHub, GitLab o un altro host git. Vedi Ospita e distribuisci marketplace.
Condividi con gli utenti: gli utenti aggiungono il tuo marketplace con /plugin marketplace add e installano singoli plugin. Vedi Scopri e installa plugin.

Una volta che il tuo marketplace è attivo, puoi aggiornarlo eseguendo il push delle modifiche al tuo repository. Gli utenti aggiornano la loro copia locale con /plugin marketplace update.

Procedura dettagliata: creare un marketplace locale

Questo esempio crea un marketplace con un plugin: una skill quality-review per le revisioni del codice. Creerai la struttura delle directory, aggiungerai una skill, creerai il manifest del plugin e il catalogo del marketplace, quindi lo installerai e lo testerai.

Crea la struttura delle directory

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

Crea la skill

Crea un file SKILL.md che definisce cosa fa la skill quality-review.

---
description: Rivedi il codice per bug, sicurezza e prestazioni
---

Rivedi il codice che ho selezionato o i cambiamenti recenti per:
- Potenziali bug o casi limite
- Problemi di sicurezza
- Problemi di prestazioni
- Miglioramenti di leggibilità

Sii conciso e pratico.

Crea il manifest del plugin

Crea un file plugin.json che descrive il plugin. Il manifest va nella directory .claude-plugin/.

{
"name": "quality-review-plugin",
"description": "Aggiunge una skill quality-review per revisioni rapide del codice",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

Crea il file marketplace

Crea il catalogo marketplace che elenca il tuo plugin.

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Aggiunge una skill quality-review per revisioni rapide del codice"
}
]
}

Aggiungi e installa

Dalla directory che contiene my-marketplace, avvia Claude Code ed esegui i seguenti comandi. Il comando install apre una vista dei dettagli del plugin dove selezioni un ambito di installazione per confermare l'installazione. Controlla il riepilogo dell'installazione: se riporta Run /reload-plugins to activate., vedi Applica le modifiche ai plugin senza riavviare.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

Provalo

Seleziona del codice nel tuo editor ed esegui la tua nuova skill. Le skill dei plugin sono associate allo spazio dei nomi del nome del plugin.

/quality-review-plugin:quality-review

Per saperne di più su cosa possono fare i plugin, inclusi hooks, agenti, server MCP e server LSP, vedi Plugins.

Crea il file marketplace

Crea .claude-plugin/marketplace.json nella radice del tuo repository. Questo file definisce il nome del tuo marketplace, le informazioni del proprietario e un elenco di plugin con le loro fonti.

Ogni voce di plugin ha bisogno almeno di un name e di una source che dice a Claude Code da dove recuperarla. Vedi lo schema completo di seguito per tutti i campi disponibili.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Schema del marketplace

Campi obbligatori

Campo	Tipo	Descrizione	Esempio
`name`	string	Identificatore del marketplace in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: quando aggiungono un secondo marketplace con lo stesso nome, Claude Code sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo `marketplace.json`.	`"acme-tools"`
`owner`	object	Informazioni sul manutentore del marketplace. Vedi Campi del proprietario
`plugins`	array	Elenco dei plugin disponibili	Vedi Voci di plugin

Note

Nomi riservati: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, claude-tag-plugins, healthcare. Anche i nomi che impersonano marketplace ufficiali, come official-claude-plugins o anthropic-plugins-v2, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.

Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è registrato da una fonte non attendibile. Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, first-party-plugins e healthcare non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi. Prima della v2.1.265, claude-tag-plugins non era riservato.

Non puoi nemmeno denominare un marketplace npm, pip, uv, cargo, github, o gh, in nessuna combinazione di maiuscole e minuscole. Questo controllo richiede Claude Code v2.1.275 o successivo.

Campi del proprietario

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome del manutentore o del team
`email`	string	No	Email di contatto per il manutentore
`url`	string	No	Sito web, profilo GitHub o URL dell'organizzazione

Campi opzionali

Campo	Tipo	Descrizione
`$schema`	string	URL dello schema JSON per l'autocompletamento dell'editor e la convalida. Claude Code ignora questo campo al momento del caricamento.
`description`	string	Breve descrizione del marketplace
`version`	string	Versione del manifest del marketplace
`metadata.pluginRoot`	string	Directory che Claude Code risolve sotto i nomi di fonte del plugin bare. Vedi Percorsi relativi. Richiede Claude Code v2.1.239 o successivo.
`allowCrossMarketplaceDependenciesOn`	array	Altri marketplace su cui i plugin in questo marketplace possono dipendere. Le dipendenze da un marketplace non elencato qui sono bloccate all'installazione. Vedi Dipendi da un plugin di un altro marketplace.
`renames`	object	Mappa da un precedente `name` del plugin al suo nome attuale, o a `null` se il plugin è stato rimosso. Consente agli utenti esistenti di migrare automaticamente quando rinomini o rimuovi una voce in `plugins`. Vedi Rinominare o rimuovere un plugin. Richiede Claude Code v2.1.193 o successivo.

description e version sono accettati anche sotto metadata per compatibilità con le versioni precedenti.

Voci di plugin

Ogni voce di plugin nell'array plugins descrive un plugin e dove trovarlo. Puoi includere qualsiasi campo dallo schema del manifest del plugin, come description, version, author, commands e hooks, più questi campi specifici del marketplace: source, category, tags, strict, relevance, headers e headersHelper.

Campi obbligatori

Campo	Tipo	Descrizione
`name`	string	Identificatore del plugin in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano (ad esempio, `/plugin install my-plugin@marketplace`).
`source`	string\|object	Da dove recuperare il plugin (vedi Plugin sources di seguito)

Campi di plugin opzionali

Campi di metadati standard:

Campo	Tipo	Descrizione
`displayName`	string	Nome leggibile mostrato nelle superfici dell'interfaccia utente. Quando né la voce né il `plugin.json` del plugin ne impostano uno, gli utenti vedono il `name` del plugin. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca.
`description`	string	Breve descrizione del plugin
`version`	string	Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una `command` source non è bloccato da nessuno dei due campi. Neanche un plugin caricato in place da un marketplace aggiunto come directory locale. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in version management.
`author`	object	Informazioni sull'autore del plugin (`name` obbligatorio; `email` e `url` opzionali)
`homepage`	string	URL della homepage o della documentazione del plugin
`repository`	string	URL del repository del codice sorgente
`license`	string	Identificatore di licenza SPDX (ad esempio, MIT, Apache-2.0)
`keywords`	array	Tag per la scoperta e la categorizzazione dei plugin
`metadata`	object	Oggetto in formato libero per i tuoi campi personalizzati, come dati di diritto o catalogo. Claude Code non lo legge. Prima della v2.1.222, `claude plugin validate` segnalava la chiave come campo non riconosciuto.
`category`	string	Categoria del plugin per l'organizzazione
`tags`	array	Tag per la ricercabilità
`strict`	boolean	Controlla se `plugin.json` è l'autorità per le definizioni dei componenti (predefinito: true). Vedi Strict mode di seguito.
`relevance`	object	Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi Recommend plugins for your org.
`defaultEnabled`	boolean	Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi Default enablement.

Sia la voce che il plugin.json del plugin stesso possono impostare i campi di visualizzazione displayName, description, author, homepage, repository, license e keywords. Negli elenchi e nei dettagli dei plugin, prima e dopo l'installazione:

Per un campo che imposti sulla voce, gli utenti vedono il valore della voce, anche quando plugin.json ne imposta uno diverso.
Per un campo che la voce lascia non impostato, gli utenti vedono il valore di plugin.json.

Prima dell'installazione, Claude Code può leggere plugin.json solo per le voci con una relative-path source, i cui file di plugin si trovano all'interno del marketplace stesso. Per una voce con qualsiasi altro tipo di source, gli utenti vedono solo i campi della voce stessa fino a quando non installano il plugin.

Campi di configurazione dei componenti:

Campo	Tipo	Descrizione
`skills`	string\|array	Percorsi personalizzati alle directory delle skill contenenti `<name>/SKILL.md`
`commands`	string\|array	Percorsi personalizzati ai file di skill flat `.md` o alle directory
`agents`	string\|array	Percorsi personalizzati ai file degli agenti
`hooks`	string\|object	Configurazione degli hook personalizzati o percorso al file degli hook
`mcpServers`	string\|object	Configurazioni del server MCP o percorso alla configurazione MCP
`lspServers`	string\|object	Configurazioni del server LSP o percorso alla configurazione LSP

Campi di autenticazione dell'archivio:

Imposta questi quando la voce ha una archive source su un server che richiede credenziali.

Campo	Tipo	Descrizione
`headers`	object	Intestazioni HTTP che Claude Code invia quando scarica l'archivio di questa voce. Sostituisce le intestazioni del marketplace con lo stesso nome. Richiede Claude Code v2.1.238 o successivo.
`headersHelper`	string	Comando che stampa le intestazioni HTTP per il download dell'archivio di questa voce come un singolo oggetto JSON, per una credenziale che scade. Vedi Authenticate archive downloads. La voce deve anche impostare `"strict": false`. Richiede Claude Code v2.1.238 o successivo.

Origini dei plugin

Le origini dei plugin indicano a Claude Code dove ottenere ogni singolo plugin elencato nel tuo marketplace. Questi sono impostati nel campo source di ogni voce di plugin in marketplace.json.

Claude Code copia ogni plugin installato nella cache locale dei plugin con versione in ~/.claude/plugins/cache, a meno che il plugin non si carichi al suo posto. Una command source in link mode si carica al suo posto, così come una relative path source in un marketplace aggiunto da una directory locale. Claude Code inoltre installa le dipendenze del pacchetto Node.js idonee del plugin nella copia memorizzata nella cache. Vedi Plugin caching and file resolution per come un plugin caricato al suo posto da un marketplace di directory locale raccoglie i tuoi modifiche.

Origine	Tipo	Campi	Note
Percorso relativo	`string` (ad es. `"./my-plugin"`)	nessuno	Directory locale all'interno del repository del marketplace. Deve iniziare con `./`, a meno che non scrivi un nome semplice sotto `metadata.pluginRoot`. Claude Code risolve il percorso relativo alla radice del marketplace, non alla directory `.claude-plugin/`
`github`	object	`repo`, `ref?`, `sha?`
`url`	object	`url`, `ref?`, `sha?`	Origine URL Git
`git-subdir`	object	`url`, `path`, `ref?`, `sha?`	Sottodirectory all'interno di un repository git. Clona in modo sparso per ridurre al minimo la larghezza di banda per i monorepo
`npm`	object	`package`, `version?`, `registry?`	Pacchetto npm, recuperato con il tuo client npm e decompresso senza eseguire script di installazione
`archive`	object	`url`, `sha256?`	Archivio zip scaricato tramite HTTPS. Funziona senza git o npm sulla macchina dell'utente. Richiede Claude Code v2.1.224 o successivo
`command`	object	`command`, `timeout?`, `mode?`	Directory del plugin prodotta dall'esecuzione di un comando locale, rieseguita una volta per sessione per raccogliere i cambiamenti. Richiede Claude Code v2.1.229 o successivo

Note

Origini del marketplace rispetto alle origini dei plugin: Questi sono concetti diversi che controllano cose diverse.

Origine del marketplace: dove recuperare il catalogo marketplace.json stesso. Impostato quando gli utenti eseguono /plugin marketplace add o nelle impostazioni extraKnownMarketplaces. Le origini del marketplace basate su Git supportano ref (branch/tag) ma non sha.
Origine del plugin: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo source di ogni voce di plugin all'interno di marketplace.json. Le origini dei plugin basate su Git supportano sia ref (branch/tag) che sha (commit esatto).

Ad esempio, un marketplace ospitato in acme-corp/plugin-catalog (origine del marketplace) può elencare un plugin recuperato da acme-corp/code-formatter (origine del plugin). L'origine del marketplace e l'origine del plugin puntano a repository diversi e sono bloccate indipendentemente.

I tipi di origine basati su git di seguito sono github, url e git-subdir. Quando sia ref che sha sono impostati su uno qualsiasi di essi, sha è il blocco effettivo. Claude Code recupera e controlla il commit bloccato direttamente.

Sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket, ciò significa che l'installazione ha successo anche se il branch o il tag denominato da ref è stato successivamente eliminato a monte, purché il commit sia ancora raggiungibile dal repository. Alcuni server, come AWS CodeCommit, non supportano il recupero dei commit per SHA. Su questi server ref deve ancora esistere e il commit bloccato deve essere raggiungibile da esso.

Se distribuisci plugin tramite Impostazioni organizzazione > Plugin, sono consentiti solo alcuni tipi di origine. Vedi Distribuire tramite impostazioni organizzazione.

Percorsi relativi

Per i plugin nello stesso repository, utilizza un percorso che inizia con ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente .claude-plugin/. Nell'esempio precedente, ./plugins/my-plugin punta a <repo>/plugins/my-plugin, anche se marketplace.json si trova in <repo>/.claude-plugin/marketplace.json. Non utilizzare ../ per fare riferimento a percorsi al di fuori della radice del marketplace. Su macOS e Linux, Claude Code rifiuta una voce di percorso con una barra rovesciata in qualsiasi punto dopo il ./ iniziale, quindi scrivi i separatori come / su ogni piattaforma.

Un nome semplice è un singolo nome di directory senza /, come "formatter". Per scrivere nomi semplici invece di percorsi ./, imposta metadata.pluginRoot sulla directory in cui si risolvono. Con "pluginRoot": "./plugins", Claude Code risolve "source": "formatter" in ./plugins/formatter. Richiede Claude Code v2.1.239 o successivo.

metadata.pluginRoot deve essere esso stesso un percorso relativo all'interno del marketplace. Claude Code lo ignora per un'origine che inizia già con ./. Un'origine che contiene un /, come team-a/formatter, non è un nome semplice e ha ancora bisogno del prefisso ./, anche quando metadata.pluginRoot è impostato.

Repository GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Puoi bloccare a un branch, tag o commit specifico:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Campo	Tipo	Descrizione
`repo`	string	Obbligatorio. Repository GitHub nel formato `owner/repo`
`ref`	string	Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository)
`sha`	string	Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta

Repository Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Puoi bloccare a un branch, tag o commit specifico:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL completo del repository git (`https://` o `git@`). Il suffisso `.git` è facoltativo, quindi gli URL di Azure DevOps e AWS CodeCommit senza il suffisso funzionano
`ref`	string	Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository)
`sha`	string	Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta

Sottodirectory Git

Utilizza git-subdir per puntare a un plugin che si trova all'interno di una sottodirectory di un repository git. Claude Code utilizza un clone parziale e sparso per recuperare solo la sottodirectory, riducendo al minimo la larghezza di banda per i grandi monorepo.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Puoi bloccare a un branch, tag o commit specifico:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Il campo url accetta anche una scorciatoia GitHub (owner/repo) o URL SSH (git@github.com:owner/repo.git).

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL del repository Git, scorciatoia GitHub `owner/repo`, o URL SSH
`path`	string	Obbligatorio. Percorso della sottodirectory all'interno del repository contenente il plugin (ad esempio, `"tools/claude-plugin"`)
`ref`	string	Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository)
`sha`	string	Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta

Pacchetti npm

Un'origine npm può denominare qualsiasi pacchetto nel registro npm pubblico o in un registro privato ospitato dal tuo team. Claude Code risolve il pacchetto con il tuo client npm, scarica il tarball e lo decomprime nella cache del plugin.

Gli script di installazione del pacchetto, come preinstall o postinstall, non vengono mai eseguiti, e le sue dipendenze non vengono installate durante il recupero.

Se il pacchetto fornisce un lockfile supportato accanto al suo package.json, Claude Code installa quelle dipendenze del pacchetto Node.js in un passaggio separato, anche con script disabilitati. Altrimenti, pubblica il plugin con tutto ciò di cui ha bisogno già costruito. Un server MCP che ha bisogno di altri pacchetti può avviarsi tramite npx, che li installa al primo esecuzione.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Per bloccare a una versione specifica, aggiungi il campo version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Per installare da un registro privato o interno, aggiungi il campo registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Campo	Tipo	Descrizione
`package`	string	Obbligatorio. Nome del pacchetto o pacchetto con scope (ad esempio, `@org/plugin`)
`version`	string	Facoltativo. Versione o intervallo di versioni (ad esempio, `2.1.0`, `^2.0.0`, `~1.5.0`)
`registry`	string	Facoltativo. URL del registro npm personalizzato. Per impostazione predefinita il registro npm del sistema (in genere npmjs.org)

Archivi zip

Utilizza archive per distribuire un plugin come file zip che Claude Code scarica tramite HTTPS, in modo che le installazioni funzionino senza git o npm sulla macchina dell'utente. Ospita il file su qualsiasi server di file statici o repository di artefatti, come un bucket S3, un repository generico di Artifactory o nginx. Richiede Claude Code v2.1.224 o successivo. Nelle versioni da v2.1.120 a v2.1.223, l'installazione del plugin non riesce con This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.; nelle versioni precedenti, un marketplace contenente una voce archive non si carica affatto.

Questa voce installa il plugin da un file zip su un server di artefatti:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

Quando crei il file zip, puoi comprimere direttamente il contenuto del plugin o comprimere la cartella del plugin stessa. Claude Code cerca .claude-plugin/ in cima all'archivio, quindi all'interno di una singola cartella di primo livello, quindi entrambi i layout si installano:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code non cerca più in profondità di una cartella, quindi un plugin annidato più in basso non si installa. Claude Code rifiuta gli archivi più grandi di 256 MiB.

Per bloccare il file esatto, aggiungi un campo sha256 con il digest dell'archivio:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Se il file scaricato non corrisponde al blocco, Claude Code rifiuta l'installazione e segnala Plugin archive integrity check failed.

Le origini dell'archivio accettano questi campi:

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL HTTPS dell'archivio zip. Claude Code rifiuta gli URL `http://`, insieme agli host loopback, link-local e cloud-metadata. Ogni hop di reindirizzamento deve soddisfare le stesse regole, o Claude Code rifiuta il download
`sha256`	string	Facoltativo. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'installazione in caso di mancata corrispondenza

Il digest sha256 serve anche come versione del plugin quando né plugin.json né la voce del marketplace ne dichiara una. Vedi Gestione delle versioni. Se dichiari una version, quella stringa di versione è il segnale di aggiornamento, quindi dopo aver modificato il file zip e il suo digest, aumenta anche la versione, altrimenti gli utenti mantengono la copia memorizzata nella cache.

Autentica i download dell'archivio

Per autenticare un download dell'archivio, come un download da un registro privato, imposta le intestazioni HTTP che Claude Code invia con esso. Imposta headers sull'origine url da cui hai registrato il marketplace, come una voce extraKnownMarketplaces. Su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce del plugin invece, accanto a source.

Se il valore che inseriresti in headers è di breve durata, come un token che il tuo registro crea su richiesta, imposta invece un comando headersHelper nello stesso posto. Claude Code esegue il comando e invia l'oggetto JSON che stampa come intestazioni di quel posto. Richiede Claude Code v2.1.238 o successivo.

Il posto che scegli decide quali download ricevono le intestazioni e quando Claude Code esegue il comando:

Posto	Download che ricevono le intestazioni	Quando Claude Code esegue un `headersHelper` impostato lì
Origine `url` del marketplace	Download dell'archivio sull'origine dell'URL del marketplace, ovvero lo stesso schema, host e porta	Prima di ogni recupero del `marketplace.json` del marketplace e prima di ogni download dell'archivio su quell'origine. Claude Code riutilizza l'output di un'esecuzione per fino a 60 secondi
Voce del plugin	Solo il download di quella voce	Solo quando un utente installa o aggiorna quel singolo plugin da solo e accetta il comando

Dove entrambi i posti impostano un'intestazione con lo stesso nome, Claude Code invia il valore della voce. All'interno di un posto, un'intestazione che il comando stampa sostituisce un'intestazione con lo stesso nome elencata in headers.

Aggiungi un headersHelper a una voce di plugin

Questa voce imposta headersHelper accanto a source. Imposta anche "strict": false, che Claude Code richiede di una voce marketplace.json che imposta headersHelper. Con "strict": false, la voce del marketplace è l'intera definizione del plugin, quindi un utente può rivedere cosa contiene il plugin prima di accettare il comando:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

Per controllare la voce, esegui claude plugin install my-plugin@your-marketplace. Claude Code ti mostra il comando e l'URL dell'archivio, e scarica il file zip dopo che accetti.

Prima della v2.1.238, Claude Code scaricava l'archivio di una voce senza le sue headers o headersHelper, quindi un'installazione che si basava su di esse non riusciva con HTTP 401 while downloading plugin archive from, seguito dall'URL, con il codice di stato del registro al posto di 401.

Scrivi il comando headersHelper

Che tu imposti headersHelper sull'origine url di un marketplace o su una voce di plugin, scrivi il comando per soddisfare questi requisiti:

Testo del comando: al massimo 500 caratteri di ASCII stampabile, senza sequenze di quattro o più spazi.
Output: stampa un oggetto JSON di nomi di intestazione e valori di stringa su stdout, quindi esci con 0 entro 10 secondi.
Shell e directory di lavoro: Claude Code esegue il comando tramite sh, o cmd.exe su Windows, dalla directory di configurazione, ~/.claude o CLAUDE_CONFIG_DIR. Fornisci un percorso assoluto o un comando su PATH, perché un percorso relativo si risolve rispetto a quella directory, non al progetto dell'utente.
Variabili che Claude Code rimuove: dall'ambiente di un comando impostato in una voce marketplace.json o nelle impostazioni .claude/settings.json o .claude/settings.local.json di un progetto, Claude Code rimuove ogni variabile il cui nome contiene una parola come TOKEN, SECRET, KEY o AUTH, incluso ANTHROPIC_API_KEY. Claude Code non applica questa rimozione a un comando impostato nelle impostazioni utente, in un file --settings o nelle impostazioni gestite.
Variabili che Claude Code imposta: CLAUDE_CODE_MARKETPLACE_URL e CLAUDE_CODE_MARKETPLACE_NAME per il comando di un'origine url, e CLAUDE_CODE_PLUGIN_NAME e CLAUDE_CODE_PLUGIN_ARCHIVE_URL per il comando di una voce. CLAUDE_CODE_MARKETPLACE_NAME non è impostato al primo recupero dopo che un utente aggiunge un marketplace per URL, perché quel recupero è quello che fornisce il nome.

Un comando che crea un token bearer stampa un oggetto come questo:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Quando Claude Code salta un comando headersHelper o scarta il suo output

Claude Code non esegue un comando headersHelper, o scarta le intestazioni che provengono da headers o dall'output del comando, in queste situazioni:

Il comando non riesce: se il comando esce con codice diverso da zero, viene eseguito oltre 10 secondi, o stampa qualcosa di diverso da un oggetto JSON di valori di stringa, Claude Code non effettua il recupero o il download per cui ha eseguito il comando.
L'URL del marketplace non inizia con https://: Claude Code non esegue il comando di quell'origine url e invia solo le intestazioni elencate nel suo campo headers.
Il reindirizzamento lascia l'origine: quando un download viene reindirizzato dall'origine dell'URL dell'archivio, Claude Code scarta i valori headers e l'output del comando sia dell'origine url del marketplace che della voce del plugin.
La voce imposta un'intestazione di routing o identità: Claude Code scarta i nomi di routing delle richieste e identità del client come Host, Cookie e X-Forwarded-* dalle headers e dall'output del comando di una voce, e mantiene i nomi di autenticazione come Authorization. Claude Code filtra ogni voce marketplace.json in questo modo, e una voce inline settings a seconda di quale file la dichiara.
Il comando è impostato nelle impostazioni di una directory --add-dir: Claude Code lo ignora, sia su un'origine url che su una voce di plugin inline, e invia solo le headers di quel file.
Le impostazioni gestite bloccano il comando: impostare disableCommandPluginSources su true blocca i comandi headersHelper, e allowManagedHooksOnly li blocca anche a meno che disableCommandPluginSources non sia esplicitamente false. Sotto uno di questi blocchi, Claude Code esegue comunque il comando per un marketplace che le impostazioni gestite stesse dichiarano.

Come gli utenti accettano un comando headersHelper

Un utente accetta il comando di una voce di plugin ogni volta che installa o aggiorna quel singolo plugin da solo, dalla vista del plugin in /plugin o con claude plugin install o claude plugin update. Claude Code mostra il comando e l'URL dell'archivio, ed esegue il comando solo dopo che l'utente accetta.

In una shell non interattiva, passa --yes per accettare il comando. Per accettare solo il comando che un'esecuzione precedente con --json ha visualizzato, passa --accept-command con lo sha256 che l'esecuzione ha segnalato.

Claude Code esegue solo il comando che ha mostrato, per l'URL dell'archivio che ha mostrato. Se il comando o l'URL dell'archivio della voce sono cambiati nel frattempo, Claude Code rifiuta l'installazione o l'aggiornamento. Un cambio nella stringa di query da solo non conta.

Installazioni e aggiornamenti che rifiutano il comando invece di chiedere

Su qualsiasi operazione diversa da un'installazione o aggiornamento di un singolo plugin, Claude Code non esegue il comando di una voce né scarica il suo archivio, quindi il plugin rimane alla versione installata o rimane disinstallato. Quello che l'utente vede dipende dall'operazione:

Installazione di più plugin contemporaneamente, da un suggerimento di plugin, o come dipendenza di un altro plugin: Claude Code rifiuta il plugin che ha il comando e indirizza l'utente alla vista di quel plugin in /plugin. Gli altri plugin in un'installazione in blocco si installano comunque. Un plugin che dipende dal plugin rifiutato non si installa fino a quando l'utente non installa il plugin rifiutato da solo.
Aggiornamento automatico in background, o avvio della sessione per un plugin il cui archivio non è mai stato scaricato: Claude Code elenca il plugin nella scheda Errori di /plugin in modo che l'utente sappia di installarlo o aggiornarlo manualmente. Un aggiornamento automatico che trova la voce ancora pubblicizza l'elenco della versione installata non mostra nulla.

Quando viene eseguito il comando di un'origine `url` del marketplace

Un headersHelper di un'origine url del marketplace è dichiarato in un file di impostazioni, come una voce extraKnownMarketplaces, piuttosto che nel catalogo che il marketplace pubblica, quindi Claude Code non chiede all'utente di accettarlo su ogni installazione o aggiornamento. Il file di impostazioni che lo dichiara decide quando Claude Code lo esegue:

File di impostazioni	Quando Claude Code esegue il comando
Impostazioni utente, un file `--settings`, o un file di impostazioni gestite sulla macchina	Senza chiedere, incluso durante un aggiornamento del marketplace in background
`.claude/settings.json` o `.claude/settings.local.json` di un progetto	Solo dopo che l'utente accetta la finestra di dialogo di trust dell'area di lavoro per quella cartella stessa. Una sessione `-p` o SDK non conta come accettazione, e nemmeno il trust concesso a una cartella padre
Impostazioni gestite dal server	Solo dopo che l'utente approva le impostazioni consegnate nella finestra di dialogo di approvazione della sicurezza

In una sessione -p o SDK, Claude Code non può mostrare la finestra di dialogo di approvazione della sicurezza. Applica le altre impostazioni consegnate, ma il recupero del marketplace, e qualsiasi download dell'archivio che ha bisogno del comando, non riesce fino a quando un utente non ha approvato in una sessione interattiva.

Per una voce di plugin inline in uno di questi file, Claude Code richiede lo stesso trust della cartella o approvazione delle impostazioni come per un comando a livello di marketplace in quel file, e l'utente accetta anche il comando della voce su ogni installazione o aggiornamento.

Origini dei comandi

Utilizza command quando uno strumento installato localmente produce la directory del plugin, come un IDE che renderizza il suo plugin per la toolchain attualmente selezionata. Claude Code esegue il comando quando l'utente installa il plugin e lo riesegue in background una volta per sessione, quindi i tuoi utenti raccolgono l'output modificato dello strumento senza reinstallare. Richiede Claude Code v2.1.229 o successivo. Nella versione da v2.1.120 a v2.1.228, l'installazione del plugin non riesce con This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again., e nelle versioni precedenti l'intero marketplace non si carica.

Questa voce installa il plugin da qualsiasi directory che lo strumento stampa:

{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

Claude Code esegue il comando tramite la shell della piattaforma, sh su macOS e Linux o cmd.exe su Windows, dalla directory home dell'utente. Il comando deve stampare esattamente una riga su stdout e uscire con codice 0. Quella riga è il percorso assoluto di una directory che contiene il plugin completo al momento dell'uscita del comando, e il percorso può cambiare tra le esecuzioni.

Claude Code interrompe un comando che viene eseguito più a lungo di timeout secondi, e l'installazione o l'aggiornamento non riesce. Claude Code rifiuta anche il percorso stampato in questi casi, e l'installazione o l'aggiornamento non riesce allo stesso modo:

La directory non ha contenuto di plugin al suo livello superiore, come una directory .claude-plugin/ o una directory skills/, commands/, agents/ o hooks/
La directory è quella in cui Claude Code è stato avviato, o una delle sue cartelle padre
Su Windows, il percorso è un percorso UNC

Le origini dei comandi accettano questi campi:

Campo	Tipo	Descrizione
`command`	string	Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce con 0. Deve essere ASCII stampabile, al massimo 500 caratteri, senza sequenze di quattro o più spazi, in modo che gli utenti possano rivedere l'intero comando che viene loro chiesto di accettare
`timeout`	number	Facoltativo. Numero intero di secondi di attesa per il comando prima di rinunciare (predefinito: 60, massimo: 600)
`mode`	string	Facoltativo. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi Modalità copia e modalità link

Modalità copia e modalità link

Con il valore predefinito "mode": "copy", Claude Code copia la directory stampata nella cache del plugin con versione e deriva la versione del plugin da un hash del contenuto della directory. Il tuo strumento può eliminare o riscrivere la directory dopo l'uscita del comando, e una riesecuzione che produce contenuto identico conta come aggiornato. Claude Code rifiuta di installare una directory più grande di 256 MiB o contenente più di 20.000 voci.

Imposta "mode": "link" per le directory di plugin di grandi dimensioni che non dovrebbero essere copiate, come un'esportazione SDK renderizzata. Claude Code riempie la voce della cache del plugin con un link a ogni voce di primo livello della directory stampata e utilizza i file al suo posto, quindi nulla viene copiato, i contenuti dei file non vengono sottoposti a hash, e i limiti di dimensione non si applicano. L'installazione non riesce se una voce di primo livello è un symlink che punta al di fuori della directory stampata. Claude Code salta anche l'installazione della dipendenza del pacchetto Node.js per un plugin in modalità link, quindi stampa una directory che contiene già qualsiasi node_modules di cui il plugin ha bisogno.

Mantieni la directory stampata al suo posto per tutto il tempo in cui il plugin rimane installato, perché Claude Code carica il plugin attraverso quei link ad ogni avvio. Claude Code deriva la versione del plugin dal percorso reale della directory stampata e dalle sue voci di primo livello, non dai file all'interno, quindi stampa un percorso diverso per segnalare nuovo contenuto. In una sessione avviata nella directory stampata o in qualsiasi punto al di sotto di essa, Claude Code non carica affatto il plugin.

Claude Code non supporta la modalità link su Windows e rifiuta di installare un plugin in modalità link lì. Dichiara "mode": "copy" invece.

Come gli utenti accettano il comando

Claude Code esegue il tuo comando sulla macchina dell'utente, quindi lega ogni esecuzione all'accettazione esplicita dell'utente:

Quando gli utenti installano il plugin dalla sua schermata dei dettagli in /plugin, o lo installano o aggiornano con claude plugin install o claude plugin update in un terminale interattivo, Claude Code mostra loro la stringa di comando esatta per prima e registra il comando accettato per quell'installazione. Un claude plugin update che può procedere sull'accettazione registrata dello stesso comando non mostra nulla.
In una shell non interattiva, come uno script di provisioning, passa --yes a claude plugin install o claude plugin update per accettare il comando che stampa. Per accettare solo il comando che un'esecuzione precedente con --json ha visualizzato, passa --accept-command con lo sha256 che l'esecuzione ha segnalato.
Ogni altro percorso esegue solo il comando che l'utente ha già accettato. Questo include gli aggiornamenti avviati da /plugin e le esecuzioni in background descritte in Quando Claude Code riesegue il comando. Quando nessuno è stato accettato, Claude Code rifiuta di eseguire il comando e dice all'utente come rivederlo. Claude Code non installa mai un plugin con origine da comando come dipendenza di un altro plugin, quindi gli utenti lo installano da soli per primi.
Se cambi la voce command, o cambi il suo mode, gli utenti mantengono la versione che hanno già e Claude Code smette di rieseguire il comando. Nelle sessioni interattive, la scheda Errori di /plugin mostra il nuovo comando fino a quando l'utente non lo rivede e accetta eseguendo claude plugin update <plugin>@<marketplace>.

Gli amministratori possono bloccare le origini dei comandi in un'organizzazione con l'impostazione gestita disableCommandPluginSources. Se un'organizzazione imposta allowManagedHooksOnly, Claude Code blocca le origini dei comandi per impostazione predefinita.

Quando Claude Code riesegue il comando

La directory stampata riflette lo stato dello strumento al momento dell'esecuzione del comando, quindi Claude Code esegue il comando di nuovo in questi momenti:

Ogni volta che l'utente installa o aggiorna il plugin
Una volta per sessione per ogni plugin con origine da comando abilitato, in background, poco dopo l'avvio della sessione. Questa esecuzione non passa attraverso l'aggiornamento automatico del marketplace, quindi non dipende dall'impostazione di aggiornamento automatico del marketplace
All'avvio o su /reload-plugins, quando la versione installata di un plugin abilitato è mancante dalla cache del plugin

Claude Code salta le due esecuzioni in background quando l'utente imposta CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Gli aggiornamenti e le installazioni espliciti eseguono comunque il comando con quella variabile impostata.

Quando l'output sottoposto a hash del comando è cambiato, Claude Code installa il risultato come una nuova versione e lo ricarica nella sessione interattiva in esecuzione, passando gli stessi componenti che /reload-plugins passa. L'utente vede una notifica che il plugin è stato ricaricato. Se il ricaricamento al suo posto invaliderebbe la cache del prompt della sessione, Claude Code invece chiede all'utente di eseguire /reload-plugins, che avverte del costo della cache e si applica quando rieseguito con --force.

Voci di plugin avanzate

Questo esempio mostra una voce di plugin che utilizza molti dei campi facoltativi, inclusi percorsi personalizzati per comandi, agenti, hook e server MCP:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Cose chiave da notare:

commands e agents: puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin e devono rimanere al suo interno.
- Claude Code rifiuta un percorso che si risolve al di fuori della directory del plugin, come ./../shared.md, con un errore path escapes plugin directory, e carica comunque il plugin senza quel componente
${CLAUDE_PLUGIN_ROOT}: utilizza questa variabile nei comandi hook e nelle configurazioni del server MCP per fare riferimento ai file all'interno della directory di installazione del plugin.
- Vedi la tabella di sostituzione per quali campi di configurazione la sostituiscono per tipo di server
- Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti del plugin, utilizza ${CLAUDE_PLUGIN_DATA} invece
strict: false: poiché è impostato su false, il plugin non ha bisogno del suo plugin.json. La voce del marketplace definisce tutto. Vedi Modalità strict di seguito.

Per impostazione predefinita, le skill di un plugin vengono caricate dalla directory skills/ sotto la sua source. I percorsi elencati nel campo skills si aggiungono a quella scansione:

"skills": ["./skills/", "./extra-skills/"]

Quando più voci di plugin condividono una cartella skills/ alla radice del marketplace (source: "./"), elenca invece sottodirectory specifiche in modo che ogni voce carichi solo le sue skill:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

Con un'origine alla radice del marketplace, i percorsi elencati sono l'insieme completo per quella voce, e altre directory nella cartella skills/ condivisa non si caricano. Elencare ./skills/ stesso, o la radice del plugin, mantiene la scansione completa. Se nessuno dei percorsi elencati esiste, la scansione predefinita viene eseguita invece.

Modalità strict

Il campo strict controlla se plugin.json è l'autorità per le definizioni dei componenti (skill, agenti, hook, server MCP, stili di output).

Valore	Comportamento
`true` (predefinito)	`plugin.json` è l'autorità. La voce del marketplace può integrarla con componenti aggiuntivi, e entrambe le fonti vengono unite.
`false`	La voce del marketplace è l'intera definizione. Se il plugin ha anche un `plugin.json` che dichiara componenti, è un conflitto e il plugin non si carica.

Quando utilizzare ogni modalità:

strict: true: il plugin ha il suo plugin.json e gestisce i suoi componenti. La voce del marketplace può aggiungere skill o hook extra in cima. Questo è il valore predefinito e funziona per la maggior parte dei plugin.
strict: false: l'operatore del marketplace vuole il controllo completo. Il repository del plugin fornisce file grezzi, e la voce del marketplace definisce quali di quei file sono esposti come skill, agenti, hook, ecc. Utile quando il marketplace ristruttura o cura i componenti di un plugin diversamente da quanto inteso dall'autore del plugin.

Ospitare e distribuire marketplace

Quando gli utenti aggiungono un marketplace ospitato in un repository git, o installano un plugin basato su git che elenca, Claude Code clona quel repository del marketplace o del plugin sulla loro macchina. Il clone non scarica mai il contenuto di Git LFS, quindi i file tracciati da LFS arrivano come file puntatore. Mantieni i file di cui i tuoi plugin hanno bisogno fuori da LFS.

Ospitare su GitHub (consigliato)

GitHub è il modo consigliato per ospitare e distribuire un marketplace:

Creare un repository: configurare un nuovo repository per il tuo marketplace
Aggiungere il file marketplace: creare .claude-plugin/marketplace.json con le definizioni dei tuoi plugin
Condividere con i team: gli utenti aggiungono il tuo marketplace con /plugin marketplace add owner/repo

Vantaggi: funzionalità integrate di controllo versione, tracciamento dei problemi e collaborazione in team.

Ospitare su altri servizi git

Qualsiasi servizio di hosting git funziona, come GitLab, Bitbucket e server self-hosted. Gli utenti aggiungono con l'URL completo del repository:

/plugin marketplace add https://gitlab.com/company/plugins.git

Repository privati

Claude Code supporta l'installazione di plugin da repository privati. Se distribuisci il tuo marketplace attraverso Organization settings > Plugins invece, le tue credenziali git non sono coinvolte: la sincronizzazione dell'organizzazione legge il repository del marketplace attraverso la connessione GitHub o GitLab della tua organizzazione su claude.ai. Vedi Distribuire attraverso le impostazioni dell'organizzazione per sapere quali fonti di plugin possono essere private.

Comandi che esegui

Quando esegui /plugin marketplace add, /plugin install, /plugin update o /plugin marketplace update, Claude Code utilizza i tuoi helper di credenziali git esistenti, quindi l'accesso HTTPS tramite gh auth login, Keychain di macOS o git-credential-store funziona allo stesso modo del tuo terminale. L'accesso SSH funziona finché l'host è già nel tuo file known_hosts e la chiave è caricata in ssh-agent, poiché Claude Code sopprime i prompt SSH interattivi per l'impronta digitale dell'host e la passphrase della chiave. La scorciatoia GitHub owner/repo clona per impostazione predefinita su SSH; imposta CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 per clonarli su HTTPS invece.

Aggiornamenti automatici in background

Per impostazione predefinita, l'aggiornamento in background disabilita gli helper di credenziali git quando controlla il remote del marketplace per i nuovi commit, quindi il controllo non può autenticarsi ai repository privati su HTTPS anche quando un helper è configurato. I remote SSH non sono interessati: una chiave caricata in ssh-agent autentica il controllo in background allo stesso modo dei comandi che esegui.

Quando il controllo trova nuovi commit, o fallisce perché non riesce a raggiungere o autenticarsi al remote, Claude Code clona di nuovo il marketplace e scambia il nuovo clone. Se quel clone fallisce, il checkout esistente rimane al suo posto. La re-clonazione utilizza le tue credenziali git memorizzate, ma può scadere su repository di grandi dimensioni, quindi gli aggiornamenti automatici del marketplace privato possono fallire intermittentemente.

Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:

Imposta CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il checkout esistente senza tentare la re-clonazione quando il controllo in background non riesce a raggiungere o autenticarsi al remote. I tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione, e gli aggiornamenti manuali con /plugin marketplace update continuano a autenticarsi con le tue credenziali.
Configura un helper di credenziali git, ad esempio con gh auth setup-git per GitHub, in modo che la re-clonazione possa autenticarsi senza richiedere.

L'impostazione di un token del provider come GITHUB_TOKEN nel tuo ambiente non abilita di per sé l'autenticazione in background. I token hanno effetto solo attraverso un helper di credenziali configurato, ad esempio l'helper della CLI gh, che legge GH_TOKEN e GITHUB_TOKEN.

Per fare in modo che il controllo in background stesso si autentichi su HTTPS, configura una riscrittura URL git globale. La riscrittura incorpora un token nell'URL remoto, quindi ha effetto anche se il controllo in background disabilita gli helper di credenziali. Quando il controllo trova il checkout aggiornato, Claude Code salta la re-clonazione. L'esempio seguente riscrive l'URL del repository del marketplace per includere un token di accesso:

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

Limita la riscrittura al repository del marketplace o al percorso dell'organizzazione. Una riscrittura la cui base è solo l'host si applica a ogni fetch e push a quell'host sulla macchina e sostituisce le tue credenziali normali, inclusi i push ai tuoi repository.

Ogni provider si aspetta un nome utente diverso nell'URL riscritto, e la stessa limitazione del percorso si applica a ogni provider. Per server self-hosted, sostituisci il nome host con il nome host del tuo server:

Provider	Forma URL riscritto
GitHub	`https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins`
GitLab	`https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins`
Bitbucket	`https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins`

La riscrittura memorizza il token in testo semplice nel tuo gitconfig, quindi utilizza un token con accesso in sola lettura al repository del marketplace.

Distribuire attraverso le impostazioni dell'organizzazione

Se distribuisci plugin attraverso Organization settings > Plugins su un piano Team o Enterprise, si applicano queste regole di origine:

Su github.com e gitlab.com, il repository del marketplace deve essere privato o interno. La sincronizzazione dell'organizzazione legge il repository attraverso la connessione che corrisponde al suo host:
- github.com: l'app GitHub di Claude
- Il tuo host GitHub Enterprise Server: la tua organizzazione GitHub Enterprise App
- gitlab.com o la tua istanza GitLab auto-gestita: il token di accesso nella configurazione GitLab della tua organizzazione per quell'host
Ogni origine di plugin deve essere di tipo github, url o git-subdir, o un percorso relativo che inizia con ./. Se elenchi un plugin per nome semplice sotto metadata.pluginRoot, la sincronizzazione dell'organizzazione lo rifiuta come origine non supportata, quindi scrivi il percorso, come ./plugins/deploy-tools.
Un'origine di plugin può essere privata in tre casi:
- Un'origine github.com che condivide il proprietario del repository del marketplace
- Un'origine sull'host GitHub Enterprise della tua organizzazione con l'app GHE installata sul repository
- Un'origine url o git-subdir sullo stesso host GitLab del repository del marketplace. Su gitlab.com, l'origine deve anche trovarsi sotto lo stesso spazio dei nomi del gruppo di primo livello o dell'utente del repository del marketplace.
Qualsiasi altra origine di plugin deve essere un repository pubblico su github.com, gitlab.com o bitbucket.org, che la sincronizzazione dell'organizzazione recupera senza credenziali. La sincronizzazione dell'organizzazione rifiuta le origini di plugin su host che queste regole non coprono.

Vedi Manage plugins for your organization per il flusso di lavoro dell'amministratore.

Per includere plugin privati, posiziona le cartelle dei plugin all'interno del repository del marketplace e fai riferimento ad esse con un percorso relativo. La sincronizzazione dell'organizzazione pacchettizza ogni plugin durante la distribuzione, quindi gli utenti non hanno mai bisogno di accesso a un repository di origine separato.

Ad esempio, questa voce di plugin marketplace.json fa riferimento a un plugin che hai eseguito il commit a plugins/deploy-tools nel repository del marketplace:

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

Sincronizzare un marketplace ospitato su GitLab

Per sincronizzare un marketplace da gitlab.com o da un'istanza GitLab auto-gestita, un Owner aggiunge prima una configurazione GitLab per quell'host in Organization settings > Claude Code. Le configurazioni GitLab sono in beta pubblica e si applicano solo alla sincronizzazione del marketplace dei plugin. L'aggiunta di una non rende i repository GitLab disponibili alle sessioni cloud. Vedi Manage plugins for your organization per i passaggi di configurazione.

Quando aggiungi il marketplace, inserisci l'URL HTTPS del progetto, come https://gitlab.example.com/platform/claude-plugins. I progetti nei sottogruppi annidati funzionano. La sincronizzazione dell'organizzazione legge il ramo predefinito del progetto. Se attivi Sync automatically, solo i push al ramo predefinito avviano una sincronizzazione.

Mantenere gli eseguibili fuori dalla directory bin di primo livello

Non includere una directory bin/ di primo livello in nessun plugin che distribuisci attraverso le impostazioni dell'organizzazione. claude.ai rifiuta un plugin che ne ha una, indipendentemente dal fatto che il plugin arrivi tramite sincronizzazione del marketplace o caricamento diretto:

Sincronizzazione del marketplace: la sincronizzazione dell'organizzazione rifiuta quel plugin e sincronizza il resto del marketplace. Il messaggio di errore inizia con Plugin contains a top-level bin/ directory.
Caricamento diretto: se carichi il plugin in Organization settings > Plugins invece, claude.ai rifiuta il caricamento con lo stesso messaggio.

Mantieni gli eseguibili in un'altra directory, come scripts/, e fai riferimento ad essi come ${CLAUDE_PLUGIN_ROOT}/scripts/<name> dalle tue skills, hooks o configurazioni del server MCP.

Richiedere marketplace per il tuo team

Puoi configurare il tuo repository in modo che Claude Code aggiunga il tuo marketplace per i membri del team una volta che fidano della cartella del progetto, senza alcun prompt separato. Aggiungi il tuo marketplace a .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Puoi anche specificare quali plugin devono essere abilitati per impostazione predefinita:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Per le opzioni di configurazione complete, vedi Plugin settings.

Pre-popolare plugin per i container

Per le immagini di container e gli ambienti CI, puoi pre-popolare una directory di plugin al momento della compilazione in modo che Claude Code inizi con marketplace e plugin già disponibili, senza clonare nulla al runtime. Imposta la variabile di ambiente CLAUDE_CODE_PLUGIN_SEED_DIR per puntare a questa directory.

Per stratificare più directory seed, separa i percorsi con : su Unix o ; su Windows. Claude Code cerca ogni directory in ordine e utilizza il primo seed che contiene un determinato marketplace o cache di plugin.

La directory seed rispecchia la struttura di ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Per costruire una directory seed, esegui Claude Code una volta durante la compilazione dell'immagine, installa i plugin di cui hai bisogno, quindi copia la directory ~/.claude/plugins risultante nella tua immagine e punta CLAUDE_CODE_PLUGIN_SEED_DIR ad essa.

Per saltare il passaggio di copia, imposta CLAUDE_CODE_PLUGIN_CACHE_DIR sul tuo percorso seed di destinazione durante la compilazione in modo che i plugin si installino direttamente lì:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Quindi imposta CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed nell'ambiente di runtime del tuo container in modo che Claude Code legga dal seed all'avvio.

All'avvio, Claude Code registra i marketplace trovati nel known_marketplaces.json del seed nella configurazione primaria e utilizza le cache di plugin trovate sotto cache/ al loro posto senza re-clonazione. Questo funziona sia in modalità interattiva che in modalità non interattiva con il flag -p.

Dettagli del comportamento:

Sola lettura: Claude Code non scrive mai nella directory seed.
Auto-aggiornamenti disabilitati: i marketplace seed non si auto-aggiornano.
Le voci seed hanno la precedenza: i marketplace dichiarati nel seed sovrascrivono le voci corrispondenti nella configurazione dell'utente ad ogni avvio. Per rinunciare a un plugin seed, utilizza /plugin disable piuttosto che rimuovere il marketplace.
Risoluzione del percorso: Claude Code individua il contenuto del marketplace sondando $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ al runtime, non fidandosi dei percorsi memorizzati all'interno del JSON del seed. Ciò significa che il seed funziona correttamente anche quando montato in un percorso diverso da dove è stato compilato.
La mutazione è bloccata: l'esecuzione di /plugin marketplace remove o /plugin marketplace update su un marketplace gestito da seed fallisce con una guida per chiedere al tuo amministratore di aggiornare l'immagine seed.
Si compone con le impostazioni: se extraKnownMarketplaces o enabledPlugins dichiarano un marketplace che esiste già nel seed, Claude Code utilizza la copia del seed invece di clonare.

Restrizioni del marketplace gestito

Per le organizzazioni che richiedono un controllo rigoroso sulle origini dei plugin, gli amministratori possono limitare quali marketplace di plugin gli utenti possono aggiungere utilizzando l'impostazione strictKnownMarketplaces nelle impostazioni gestite. Per rifiutare anche i flag CLI che caricano plugin, agenti e server MCP per una singola esecuzione, abbinalo a disableSideloadFlags. Per consentire quali plugin dei marketplace possono apparire come suggerimenti di installazione contestuale, imposta pluginSuggestionMarketplaces.

strictKnownMarketplaces corrisponde al marketplace da cui proviene un plugin, non alle voci al suo interno, quindi gli utenti possono comunque installare un plugin con un'origine command da un marketplace consentito. Per bloccare anche le origini dei comandi, imposta disableCommandPluginSources.

Quando strictKnownMarketplaces è configurato nelle impostazioni gestite, il comportamento della restrizione dipende dal valore:

Valore	Comportamento
Non definito (predefinito)	Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace
Array vuoto `[]`	Blocco completo. Blocca ogni origine di marketplace, incluso il marketplace ufficiale di Anthropic
Elenco di origini	Allowlist applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce

Configurazioni comuni

Disabilita tutte le aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:

{
  "strictKnownMarketplaces": []
}

Claude Code scarica i plugin sincronizzati da claude.ai dal tuo account piuttosto che da un marketplace, quindi questo blocco non li copre. Per fermare anche quelli, imposta syncClaudeAiPlugins a false nelle impostazioni gestite, o disattiva Skills per la tua organizzazione su claude.ai.

Consenti solo il marketplace ufficiale di Anthropic. La corrispondenza per una voce di repository singolo è esatta, quindi questa voce non copre varianti ref o path dello stesso repository:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

Con questa voce, Claude Code mantiene disponibile un marketplace ufficiale già registrato e, su una macchina nuova, registra il marketplace automaticamente la prima volta che avvii Claude Code in modo interattivo.

La registrazione automatica non copre ogni macchina. Più comunemente manca:

Ambienti non interattivi che vengono eseguiti prima del primo avvio interattivo della macchina.
Macchine in cui Claude Code è già stato eseguito in modo interattivo secondo una politica che ha bloccato il marketplace, come il blocco dell'array vuoto. Claude Code registra il tentativo bloccato e non ritenta dopo il cambio della politica.

Su queste macchine, aggiungi il marketplace a extraKnownMarketplaces nello stesso managed-settings.json in modo che Claude Code lo registri automaticamente, oppure esegui claude plugin marketplace add anthropics/claude-plugins-official.

Consenti solo marketplace specifici:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Consenti ogni repository di marketplace sotto un'organizzazione GitHub con una voce owner-wildcard. I wildcard del proprietario richiedono Claude Code v2.1.223 o successivo.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

Consenti tutti i marketplace da un server git interno utilizzando la corrispondenza del modello regex sull'host. Questo è l'approccio consigliato per GitHub Enterprise Server o istanze GitLab self-hosted:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Consenti marketplace basati su filesystem da una directory specifica utilizzando la corrispondenza del modello regex sul percorso:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Utilizza ".*" come pathPattern per consentire qualsiasi percorso del filesystem controllando comunque le origini di rete con hostPattern.

Come funzionano le restrizioni

Le restrizioni vengono controllate prima di qualsiasi operazione di rete o filesystem. Il controllo viene eseguito sull'aggiunta del marketplace e sull'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin. Se un marketplace è stato aggiunto prima che la politica fosse configurata e la sua origine non corrisponde più all'allowlist, Claude Code rifiuta di installare o aggiornare plugin da esso. Lo stesso controllo si applica a blockedMarketplaces.

Per bloccare ogni repository di marketplace sotto un proprietario GitHub, utilizza la forma owner-wildcard in una voce blockedMarketplaces: { "source": "github", "repo": "untrusted-org/*" }. Richiede Claude Code v2.1.223 o successivo. Per le regole di corrispondenza, che differiscono tra la blocklist e l'allowlist, vedi Owner wildcards.

Quando un utente aggiunge un URL di repository https:// che Claude Code clona piuttosto che recupera, come un URL di repository bare github.com o gitlab.com, Claude Code lo controlla anche rispetto alle voci url in blockedMarketplaces. Claude Code blocca l'aggiunta se una voce nomina lo stesso URL. In quel confronto, Claude Code ignora il suffisso .git e qualsiasi ref che l'utente aggiunge dopo #. Richiede Claude Code v2.1.232 o successivo. Prima di v2.1.232, Claude Code corrispondeva a una voce url solo rispetto a un URL che recuperava come file marketplace.json ospitato.

L'allowlist utilizza la corrispondenza esatta per la maggior parte dei tipi di origine, a parte le voci github con owner-wildcard. Affinché un marketplace sia consentito, tutti i campi specificati devono corrispondere:

Per le origini GitHub: repo è obbligatorio, nominando un repository o utilizzando la forma owner-wildcard owner/* per coprire ogni repository sotto quel proprietario. Per come le voci wildcard corrispondono, incluso il caso delle regole, vedi Owner wildcards. Per le voci di repository singolo, ref deve corrispondere esattamente o essere assente sia dall'origine del marketplace che dalla voce dell'allowlist, e la stessa regola si applica a path
Per le origini URL: l'URL completo deve corrispondere esattamente
Per le origini hostPattern: l'host del marketplace viene confrontato con il modello regex
Per le origini pathPattern: il percorso del filesystem del marketplace viene confrontato con il modello regex

La corrispondenza esatta dell'allowlist tratta gli URL che differiscono solo per una barra finale, un suffisso .git o lo schema ssh:// e https:// come valori diversi. Se il marketplace della tua organizzazione può essere clonato da più di una forma di URL, preferisci una voce hostPattern rispetto a un URL letterale in modo che i moduli https://, ssh:// e user@host:path corrispondano tutti.

Un marketplace ospitato su claude.ai è abbinato per host: una voce hostPattern che corrisponde a claude.ai lo governa, in strictKnownMarketplaces e in blockedMarketplaces. Sull'allowlist, tale voce non ammette i caricamenti personali su claude.ai di un membro. Richiede Claude Code v2.1.273 o successivo.

Poiché strictKnownMarketplaces è impostato nelle impostazioni gestite, i singoli utenti e le configurazioni del progetto non possono ignorare queste restrizioni.

Per i dettagli di configurazione completi inclusi tutti i tipi di origine supportati e il confronto con extraKnownMarketplaces, vedi il riferimento strictKnownMarketplaces.

Risoluzione della versione e canali di rilascio

Le versioni dei plugin determinano i percorsi della cache e il rilevamento degli aggiornamenti: se la versione risolta corrisponde a quella che un utente ha già, /plugin update e l'auto-aggiornamento saltano il plugin. Per le origini basate su git, se ometti version, Claude Code utilizza lo SHA del commit risolto della fonte, quindi gli utenti ricevono un aggiornamento ogni volta che quel commit cambia; questa è la configurazione più semplice per i plugin interni o in fase di sviluppo attivo. Vedi Version management per l'ordine di risoluzione completo, incluse le origini archive.

Warning

L'impostazione di version fissa il plugin per ogni tipo di origine tranne command, la cui versione include sempre un hash di ciò che il comando ha prodotto. Un plugin caricato in posizione da un marketplace aggiunto come directory locale non è fissato neanche. Se dichiari "version": "1.0.0" in plugin.json e fai il push di nuovi commit senza cambiare quella stringa, gli utenti esistenti di quelle origini mantengono la copia memorizzata nella cache, perché Claude Code vede la stessa versione. Aumenta il campo ad ogni rilascio, o omettilo per ricadere nella versione risolta.

Evita di impostare version sia in plugin.json che nella voce del marketplace. Claude Code utilizza sempre il valore plugin.json senza avvertimento, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in marketplace.json.

Configurare i canali di rilascio

Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a ref o SHA diversi dello stesso repository. Puoi quindi dare a ogni gruppo di utenti il suo marketplace attraverso le impostazioni gestite in uno di due modi:

Distribuisci impostazioni gestite endpoint-managed separate, come un file di impostazioni gestite o un profilo MDM, ai dispositivi di ogni gruppo. Come Claude Code combina le origini gestite dice se il file o il profilo per gruppo si applica su un dispositivo che ha anche un'origine a livello di organizzazione.
Definisci una politica del gateway delle app Claude per gruppo. Il gateway applica la prima politica la cui regola di corrispondenza si adatta a un utente, quindi ordina le politiche in modo che ogni utente raggiunga la politica del suo gruppo. La extraKnownMarketplaces di una politica di gruppo sostituisce la mappa della politica catch-all piuttosto che unirsi ad essa, quindi elenca ogni marketplace di cui il gruppo ha bisogno nella politica del gruppo, non solo il suo marketplace del canale.

Le impostazioni gestite dal server dalla console di amministrazione si applicano a ogni utente della tua organizzazione, quindi non possono portare un'assegnazione per gruppo.

Esempio

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Assegnare i canali ai gruppi di utenti

Assegna ogni marketplace al suo gruppo di utenti attraverso le impostazioni gestite endpoint-managed per gruppo o la politica del gateway descritte in Configurare i canali di rilascio. Ad esempio, il gruppo stabile riceve:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

Il gruppo early-access riceve latest-tools invece:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Fissare le versioni delle dipendenze

Un plugin può limitare le sue dipendenze a un intervallo semver in modo che gli aggiornamenti a una dipendenza non rompano il plugin dipendente. Vedi Constrain plugin dependency versions per la convenzione del tag git {plugin-name}--v{version}, la sintassi dell'intervallo e come più vincoli sulla stessa dipendenza vengono combinati.

Rinominare o rimuovere un plugin

Il name di un plugin è il suo identificatore stabile. Gli utenti lo referenziano in enabledPlugins, pluginConfigs e comandi /plugin install, quindi cambiarlo rompe ogni installazione esistente. Per cambiare l'etichetta mostrata nell'interfaccia utente senza rompere le installazioni, imposta displayName e mantieni name invariato.

Se devi cambiare il name di un plugin, o rimuovi un plugin dall'array plugins, aggiungi una voce renames di primo livello in modo che gli utenti esistenti migrino invece di vedere un errore plugin-not-found. La migrazione automatica richiede Claude Code v2.1.193 o successivo. Mappa ogni nome precedente al suo nome attuale, o a null se il plugin non esiste più. L'esempio seguente rinomina formatter a code-formatter e registra che legacy-linter è stato rimosso:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

Quando un utente avvia Claude Code con il vecchio nome ancora nelle sue impostazioni, Claude Code segue la mappa renames:

Se la voce punta a un nuovo nome, Claude Code carica il plugin con il suo nuovo nome e mostra un avviso di una riga come Renamed to "code-formatter" in the "acme-tools" marketplace. Quindi riscrive la vecchia chiave nella nuova chiave negli ambiti di impostazioni utente, progetto e locale sia per enabledPlugins che per pluginConfigs, quindi l'avviso appare una volta.
Per una voce null, Claude Code elimina la vecchia chiave e l'avviso segnala che il plugin è stato rimosso dal marketplace.
Se il plugin rinominato utilizza un'origine remota come github o npm, Claude Code segnala plugin-cache-miss dopo la ridenominazione e l'utente deve eseguire /plugin install una volta per recuperarlo con il nuovo nome.

Tratta renames come una storia di sola aggiunta: mantieni le vecchie voci al loro posto anche dopo che ti aspetti che ogni utente abbia migrato. Claude Code segue le catene, quindi se in seguito rinomini code-formatter a formatter-pro, aggiungi una seconda voce piuttosto che modificare la prima. Un utente che ha ancora l'originale formatter abilitato si risolve quindi attraverso entrambe le voci a formatter-pro.

Esegui claude plugin validate . dopo aver modificato la mappa; rifiuta qualsiasi voce la cui catena forma un ciclo o non termina a null o a un nome elencato in plugins.

Le versioni precedenti di Claude Code ignorano il campo renames e segnalano plugin-not-found per il vecchio nome.

Validazione e test

Testa il tuo marketplace prima di condividerlo. La validazione controlla la struttura dei file; per testare se un plugin cambia il comportamento di Claude su prompt realistici, esegui la sua suite di eval con claude plugin eval prima di pubblicare una nuova versione.

Dalla tua directory marketplace, valida la sintassi JSON:

claude plugin validate .

O da Claude Code:

/plugin validate .

Aggiungi il marketplace per il test:

/plugin marketplace add ./path/to/marketplace

Installa un plugin di test per verificare che tutto funzioni:

/plugin install test-plugin@marketplace-name

Per i flussi di lavoro di test completi dei plugin, vedi Testa i tuoi plugin localmente. Per la risoluzione dei problemi tecnici, vedi Plugins reference.

Gestisci marketplace dalla CLI

Claude Code fornisce sottocomandi claude plugin marketplace non interattivi per lo scripting e l'automazione. Questi sono equivalenti ai comandi /plugin marketplace disponibili in una sessione interattiva.

Plugin marketplace add

Aggiungi un marketplace da un repository GitHub, URL git, URL remoto o percorso locale.

claude plugin marketplace add <source> [options]

Argomenti:

<source>: Scorciatoia GitHub owner/repo, URL git, URL remoto a un file marketplace.json o percorso di directory locale. Per fissare a un branch o tag, aggiungi @ref alla scorciatoia GitHub o #ref a un URL git

Un URL deve includere il suo schema. A partire da Claude Code v2.1.196, un host digitato senza uno, come gitlab.example.com/team/plugins, viene rifiutato come una scorciatoia owner/repo non valida e l'errore ti dice di aggiungere https:// o usare ./ per un percorso locale. Le versioni precedenti lo leggevano male come un percorso di repository GitHub e falliscono al momento del clone con un errore di GitHub non trovato.

Opzioni:

Opzione	Descrizione	Predefinito
`--scope <scope>`	Dove dichiarare il marketplace: `user`, `project` o `local`. Vedi Plugin installation scopes	`user`
`--sparse <paths...>`	Limita il checkout a directory specifiche tramite git sparse-checkout. Utile per i monorepo
`--claudeai`	Leggi l'argomento come il nome di un marketplace ospitato su claude.ai invece di una fonte. Richiede Claude Code v2.1.273 o successivo

Aggiungi un marketplace da GitHub utilizzando la scorciatoia owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

Fissa a un branch o tag specifico con @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Aggiungi da un URL git su un host non-GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Aggiungi da un URL remoto che serve il file marketplace.json direttamente:

claude plugin marketplace add https://example.com/marketplace.json

Aggiungi da una directory locale per il test:

claude plugin marketplace add ./my-marketplace

Dichiara il marketplace a livello di progetto in modo che sia condiviso con il tuo team tramite .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Per un monorepo, limita il checkout alle directory che contengono il contenuto del plugin:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Aggiungi un marketplace ospitato su claude.ai dal nome stampato nella sezione From claude.ai: di claude plugin marketplace list:

claude plugin marketplace add --claudeai claudeai-organization-library

Con --claudeai, il comando rifiuta --scope e --sparse. Il marketplace è ospitato per il tuo account, non dichiarato in un file di impostazioni, quindi non puoi condividerlo tramite il .claude/settings.json di un progetto.

Plugin marketplace list

Elenca tutti i marketplace configurati.

claude plugin marketplace list [options]

Opzioni:

Opzione	Descrizione
`--json`	Output come JSON

Con --json, ogni voce include name, source, un campo installLocation con il percorso della cache locale dove il marketplace è archiviato, e campi specifici della fonte: repo per le fonti GitHub, url per le fonti git e URL, e path per le fonti locali. Le fonti GitHub e git includono anche un campo ref quando il marketplace è stato aggiunto con un branch o tag fissato.

Un marketplace claude.ai aggiunto non ha un clone locale, quindi la sua voce contiene i suoi identificatori claude.ai, marketplaceId e organizationUuid, al posto di installLocation.

In sessioni di terminale dove i plugin si sincronizzano dal tuo account claude.ai, l'elenco di testo termina con una sezione From claude.ai: che nomina ciò che claude.ai elenca per il tuo account oltre ai marketplace che hai aggiunto. Per aggiungerne uno, vedi Aggiungi da claude.ai. L'output --json copre solo i marketplace configurati e lascia fuori quella sezione. Richiede Claude Code v2.1.273 o successivo.

Plugin marketplace remove

Rimuovi un marketplace configurato. L'alias rm è accettato anche.

claude plugin marketplace remove <name> [options]

Argomenti:

<name>: nome del marketplace da rimuovere, come mostrato da claude plugin marketplace list. Questo è il name da marketplace.json, non la fonte che hai passato a add

Opzioni:

Opzione	Descrizione	Predefinito
`--scope <scope>`	Limita la rimozione a un singolo ambito di impostazioni: `user`, `project` o `local`. Vedi Plugin installation scopes. Se omesso, la dichiarazione viene rimossa da ogni ambito modificabile. Se fornito, solo la dichiarazione di quell'ambito viene rimossa; lo stato condiviso, la cache e i dati dei plugin installati vengono preservati quando il marketplace è ancora dichiarato in un altro ambito	(tutti gli ambiti)

Plugin marketplace update

Aggiorna i marketplace dalle loro fonti per recuperare nuovi plugin e cambiamenti di versione. Un marketplace aggiunto con un branch o tag ref si aggiorna al commit più recente di quel ref, non al branch predefinito del repository.

claude plugin marketplace update [name]

Argomenti:

[name]: nome del marketplace da aggiornare, come mostrato da claude plugin marketplace list. Aggiorna tutti i marketplace se omesso

Sia remove che update non riescono quando eseguiti su un marketplace gestito da seed, che è di sola lettura. Quando si aggiornano tutti i marketplace, le voci gestite da seed vengono saltate e gli altri marketplace si aggiornano comunque. Per modificare i plugin forniti da seed, chiedi al tuo amministratore di aggiornare l'immagine seed. Vedi Pre-popola plugin per i container.

Risoluzione dei problemi

Marketplace non carica

Sintomi: Non è possibile aggiungere il marketplace o visualizzare i plugin da esso

Soluzioni:

Verificare che l'URL del marketplace sia accessibile
Controllare che .claude-plugin/marketplace.json esista nel percorso specificato
Assicurarsi che la sintassi JSON sia valida utilizzando claude plugin validate . o /plugin validate . dalla directory del marketplace. Per controllare il frontmatter di skill, agent e command, vedere Validate a plugin or a directory without a manifest
Per i repository privati, confermare di avere i permessi di accesso

Errori di validazione del marketplace

Eseguire claude plugin validate . o /plugin validate . dalla directory del marketplace per verificare la presenza di problemi. Quando puntato a una directory del marketplace, il validatore controlla marketplace.json per errori di schema, nomi di plugin duplicati e traversal del percorso di origine. Per ogni voce il cui source è un percorso locale, valida anche il plugin.json di quel plugin e avvisa quando la version della voce non corrisponde a quella in plugin.json. I problemi trovati nel plugin.json di un plugin sono preceduti dall'indice della voce, nella forma plugins[2] plugin.json →.

A partire da Claude Code v2.1.196, il pass per voce include anche:

plugin il cui source è .
viene eseguito quando marketplace.json è al di fuori di una directory .claude-plugin, risolvendo le origini rispetto alla directory del file stesso
segnala i problemi di ogni voce anche quando un'altra parte del file ha errori di schema

Le versioni precedenti saltano i plugin nella radice del marketplace e scendono solo da .claude-plugin/marketplace.json.

Da una directory del marketplace, Claude Code non apre i file skill, agent, command o hook dei plugin. Per trovare errori in questi file, vedere Validate a plugin or a directory without a manifest. La tabella seguente elenca gli errori più comuni da una directory del marketplace, con la causa e la soluzione per ciascuno:

Errore	Causa	Soluzione
`No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json`	La directory denominata non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file skill, agent o command da controllare	Eseguire dalla radice del marketplace, o creare `.claude-plugin/marketplace.json` con i campi obbligatori
`Invalid JSON syntax: Unexpected token...`	Errore di sintassi JSON in marketplace.json	Controllare la presenza di virgole mancanti, virgole extra o stringhe non quotate
`Duplicate plugin name "x" found in marketplace`	Due plugin condividono lo stesso nome	Assegnare a ogni plugin un valore `name` univoco
`plugins[0].source: Path contains ".."`	Un segmento del percorso di origine è `..`	Utilizzare percorsi relativi alla radice del marketplace senza segmenti `..`. Vedere Relative paths
`Marketplace name cannot contain control or bidirectional-formatting characters`	Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una nuova riga	Rimuovere il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace`
`Plugin name cannot contain control or bidirectional-formatting characters`	Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una nuova riga	Rimuovere il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo

Avvisi (non bloccanti):

Marketplace has no plugins defined: aggiungere almeno un plugin all'array plugins
No marketplace description provided: aggiungere una description di livello superiore per aiutare gli utenti a comprendere il marketplace
Plugin name "x" is not kebab-case: rinominare utilizzando solo lettere minuscole, cifre e trattini (ad esempio, my-plugin). Claude Code accetta altre forme, ma la sincronizzazione del marketplace claude.ai le rifiuta.
Marketplace name "x" is reserved in Claude Desktop: il marketplace è denominato org, org-provisioned o unknown, in qualsiasi maiuscola. Claude Code accetta questi nomi, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta l'intero marketplace. Rinominare il marketplace. Prima della v2.1.221, claude plugin validate non eseguiva questo controllo.
Marketplace name "x" is not accepted by Claude Desktop o Plugin name "x" is not accepted by Claude Desktop: Claude Desktop accetta nomi di lunghezza fino a 128 caratteri composti da lettere, cifre, ., _ e -, che iniziano con una lettera o una cifra. Claude Code accetta altre forme, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta un marketplace il cui nome non supera il controllo e scarta silenziosamente una voce di plugin il cui nome non lo fa. Rinominare il marketplace o il plugin. Prima della v2.1.221, claude plugin validate non eseguiva questi controlli.

Validate a plugin or a directory without a manifest

Per trovare file skill, agent e command il cui frontmatter non viene analizzato, eseguire claude plugin validate e denominare la directory che li contiene. Claude Code non guarda al di fuori della directory denominata. Ogni esecuzione tranne una rispetto a un plugin che ha un plugin.json richiede Claude Code v2.1.233 o successivo.

Scegliere la directory da denominare

Claude Code controlla file diversi a seconda di quale directory denominate. Trovare ciò che si desidera controllare nella prima colonna ed eseguire il comando di quella riga:

Per controllare	Eseguire	Claude Code controlla
Un plugin che ha un `plugin.json`	`claude plugin validate ./plugins/my-plugin`	`plugin.json`, `hooks/hooks.json` e le directory `skills`, `agents` e `commands` nella radice del plugin
Una directory di skill, agent o command, come un plugin che non ha ancora un `plugin.json`	`claude plugin validate .claude/skills`, `~/.claude/agents` o `./my-plugin/agents`	Ogni file skill, agent o command in quella directory
Una cartella il cui skill è il suo `SKILL.md` radice	`claude plugin validate ./skills`, denominando la directory `skills` che contiene la cartella	Il `SKILL.md` radice di ogni cartella. La directory contenente deve essere denominata `skills`; una cartella con un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice
Le tre directory di un progetto contemporaneamente	`claude plugin validate .claude`, o la radice del progetto quando non ha un manifest `.claude-plugin/`	`.claude/skills`, `.claude/agents` e `.claude/commands`
Le directory a livello di utente	`claude plugin validate ~/.claude`	`~/.claude/skills`, `~/.claude/agents` e `~/.claude/commands`

Controllare un plugin il cui skill è il suo `SKILL.md` radice

Quando si esegue claude plugin validate rispetto a una directory di plugin, Claude Code non controlla un SKILL.md nella radice del plugin. Quando il plugin si trova in una directory denominata skills, eseguire il comando due volte:

Denominare quella directory skills per controllare il SKILL.md radice del plugin.
Denominare la directory del plugin per controllare il resto.

Quando il plugin si trova con un altro nome, come plugins/, l'esecuzione della directory skills non è disponibile e nessuna esecuzione controlla il suo SKILL.md radice.

Controllare file dietro symlink

Quando si esegue claude plugin validate, Claude Code non segue i symlink all'interno della directory denominata. Ciò che fa dipende da dove si trova il collegamento:

Una directory skills, agents o commands collegata sotto la radice del plugin o .claude: Claude Code avverte che nulla in essa è stato letto.
Una voce collegata all'interno di una directory skills, agents o commands: Claude Code la salta e avvisa, per directory, quante voci ha saltato che una sessione caricherà.
La directory skills, agents o commands denominata è essa stessa un symlink, o la sua directory padre .claude è: Claude Code segnala un errore e non controlla nulla in essa. Denominare invece la directory reale.

In due casi di skill, l'esecuzione passa con avvisi. Per controllare i file collegati, eseguire di nuovo e denominare una directory che li contiene direttamente:

Un plugin il cui directory skills si collega a una directory skills di un plugin sibling: denominare la directory del plugin sibling.
Una voce skill collegata in ~/.claude/skills o .claude/skills: Claude Code segue la voce in una sessione. Per controllarla, denominare una directory chiamata skills che contiene la cartella reale.

Leggere i risultati della validazione

Un'esecuzione pulita termina con Validation passed.

No manifest found in directory significa che Claude Code non ha trovato plugin.json o marketplace.json lì, e nessun file skill, agent o command nelle directory che sonda sotto di essa. Denominare invece la directory skills, agents o commands che contiene i file.

Due degli errori che Claude Code segnala da queste esecuzioni, con la soluzione per ciascuno:

YAML frontmatter failed to parse: ...: correggere lo YAML nel blocco frontmatter del file skill, agent o command. Fino a quando non lo farete, una sessione non legge alcun campo frontmatter dal file
Invalid JSON syntax: ... su hooks/hooks.json: correggere la sintassi JSON. Fino a quando non lo farete, una sessione carica il plugin senza gli hook in quel file. Claude Code segnala questo errore solo in un'esecuzione di plugin

In un'esecuzione di plugin, Claude Code avverte anche di un CLAUDE.md nella radice del plugin. Per i percorsi impostati tramite i component path fields in plugin.json, Claude Code controlla che ogni percorso esista ma non legge i file lì.

Errori di installazione del plugin

Sintomi: Il marketplace appare ma l'installazione del plugin non riesce

Soluzioni:

Verificare che gli URL di origine del plugin siano accessibili
Controllare che le directory dei plugin contengano i file obbligatori
Per le origini GitHub, assicurarsi che i repository siano pubblici o che si abbia accesso
Testare manualmente le origini dei plugin clonando/scaricando
Se l'origine fissa sia ref che sha, un ramo o un tag upstream eliminato non blocca l'installazione sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket. Su server che non supportano il recupero di commit per SHA, come AWS CodeCommit, il ref deve ancora esistere e il commit bloccato deve essere raggiungibile da esso. Se l'installazione continua a non riuscire, confermare che il commit bloccato esiste ancora nel repository

L'autenticazione del repository privato non riesce

Sintomi: Errori di autenticazione durante l'installazione di plugin da repository privati

Soluzioni:

Per l'installazione manuale e gli aggiornamenti:

Verificare di essere autenticati con il provider git (ad esempio, eseguire gh auth status per GitHub)
Controllare che il helper delle credenziali sia configurato: git config --global credential.helper
Eseguire git ls-remote <marketplace-url> per verificare se git può autenticarsi da solo. Se git chiede un nome utente o una password, archiviare prima la credenziale: per GitHub su HTTPS, eseguire gh auth setup-git, e per i remote SSH, caricare la chiave in ssh-agent

Per gli aggiornamenti automatici in background:

Per impostazione predefinita, gli aggiornamenti in background disabilitano gli helper delle credenziali git quando controllano il remote per nuovi commit, quindi il controllo non può autenticarsi su HTTPS. I remote SSH con una chiave caricata in ssh-agent si autenticano ancora
Quando il controllo non può autenticarsi, Claude Code ri-clona il marketplace con le credenziali archiviate, ma il ri-clone potrebbe scadere su repository di grandi dimensioni
Impostare CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il clone esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote
Configurare un helper delle credenziali git, ad esempio gh auth setup-git, in modo che il ri-clone possa autenticarsi
Se il re-clone scade su un repository di grandi dimensioni, aumentare il limite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
Configurare una riscrittura dell'URL git limitata al repository del marketplace in modo che il controllo in background si autentichi direttamente
Oppure aggiornare i marketplace privati manualmente con /plugin marketplace update <name>, che utilizza le credenziali

Gli aggiornamenti del marketplace non riescono in ambienti offline

Sintomi: In un ambiente offline o airgapped, l'aggiornamento in background del marketplace non riesce a raggiungere il remote e Claude Code tenta ripetutamente un ri-clone che non può avere successo.

Causa: L'aggiornamento in background controlla il remote del marketplace per nuovi commit, e quando il controllo non riesce a raggiungere il remote, Claude Code tenta di clonare di nuovo il marketplace. Offline, il clone non riesce allo stesso modo e il clone esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva git pull nel clone esistente, spostava il clone da parte per ri-clonare quando il pull non riusciva, e lo ripristinava in seguito su base best-effort.

L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio. Ogni sessione ripete comunque il tentativo non riuscito, e ogni operazione git può attendere il timeout di 120 secondi.

Soluzione: Impostare CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per saltare il tentativo di ri-clone e continuare a utilizzare il clone esistente quando il controllo non riesce a raggiungere il remote:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizzare CLAUDE_CODE_PLUGIN_SEED_DIR per pre-popolare la directory dei plugin al momento della compilazione.

Le operazioni Git scadono

Sintomi: L'installazione del plugin o gli aggiornamenti del marketplace non riescono con un errore di timeout come Git clone timed out after 120s.

Causa: Claude Code utilizza un timeout di 120 secondi per tutte le operazioni git, inclusa la clonazione di repository di plugin e il ri-clone di un marketplace per aggiornarlo. I repository di grandi dimensioni o le connessioni di rete lente potrebbero superare questo limite.

Soluzione: Aumentare il timeout utilizzando la variabile di ambiente CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. Il valore è in millisecondi:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

I plugin con percorsi relativi non riescono nei marketplace basati su URL

Sintomi: È stato aggiunto un marketplace tramite un URL come https://example.com/marketplace.json, ma i plugin con origini di percorso relativo come "./plugins/my-plugin" non riescono a installarsi con its marketplace entry path does not stay inside the marketplace directory. I plugin già installati non riescono a caricarsi con Plugin source path refused. Entrambi i messaggi hanno una voce di riferimento dell'errore.

Causa: l'aggiunta di un marketplace basato su URL scarica solo il file marketplace.json stesso, e Claude Code non recupera i file dei plugin per percorso relativo da quel server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.

Soluzioni:

Utilizzare origini esterne: modificare le voci dei plugin in qualsiasi plugin source diverso da un percorso relativo:
```
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
```
Utilizzare un marketplace basato su Git: ospitare il marketplace in un repository Git e aggiungerlo con l'URL git. I marketplace basati su Git clonano l'intero repository, rendendo i percorsi relativi funzionanti correttamente.

File non trovati dopo l'installazione

Sintomi: Il plugin si installa ma i riferimenti ai file non riescono, specialmente i file al di fuori della directory del plugin

Causa: Claude Code copia i plugin installati in una directory cache, a meno che il plugin non si carichi in place. Una command source in link mode si carica in place, così come una relative path source in un marketplace aggiunto da una directory locale. I percorsi che fanno riferimento a file al di fuori della directory di un plugin copiato (come ../shared-utils) non funzioneranno perché questi file non vengono copiati.

Soluzioni: Vedere Plugin caching and file resolution per soluzioni alternative inclusi symlink e ristrutturazione delle directory.

Per ulteriori strumenti di debug e problemi comuni, vedere Debugging and development tools.

Vedi anche

Scopri e installa plugin precostruiti - Installazione di plugin da marketplace esistenti
Plugins - Creazione dei tuoi plugin
Plugins reference - Specifiche tecniche complete e schemi
Plugin settings - Opzioni di configurazione dei plugin
strictKnownMarketplaces reference - Restrizioni del marketplace gestito

plugin-marketplaces.md +341 −293

71 ```71 ```

72 72

73 <Note>73 <Note>

74 Impostare `version` significa che gli utenti ricevono aggiornamenti solo quando modifichi questo campo, quindi incrementalo ad ogni rilascio. Un plugin con una [`command` source](#command-sources) non è bloccato da questo campo. Se ometti `version`, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management).74 Impostare `version` significa che gli utenti ricevono aggiornamenti solo quando modifichi questo campo, quindi incrementalo ad ogni rilascio. Un plugin con una [`command` source](#command-sources) non è bloccato da questo campo. Nemmeno un plugin [caricato in posizione](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale. Se ometti `version`, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management).

75 </Note>75 </Note>

76 </Step>76 </Step>

77 77

116Per saperne di più su cosa possono fare i plugin, inclusi hooks, agenti, server MCP e server LSP, vedi [Plugins](/docs/it/plugins).116Per saperne di più su cosa possono fare i plugin, inclusi hooks, agenti, server MCP e server LSP, vedi [Plugins](/docs/it/plugins).

117 117

118<Note>118<Note>

119 **Come vengono installati i plugin**: quando gli utenti installano un plugin, Claude Code copia la directory del plugin in una posizione cache, ad eccezione di una [`command` source in link mode](#copy-mode-and-link-mode), che viene utilizzata al suo posto. I plugin copiati non possono fare riferimento a file al di fuori della loro directory utilizzando percorsi come `../shared-utils`, perché quei file non verranno copiati.119 **Come vengono installati i plugin**: quando gli utenti installano un plugin, Claude Code copia la directory del plugin in una posizione cache, a meno che il plugin non si carichi in posizione. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica in posizione, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. I plugin copiati non possono fare riferimento a file al di fuori della loro directory utilizzando percorsi come `../shared-utils`, perché quei file non verranno copiati.

120 120

121 Se hai bisogno di condividere file tra plugin, usa symlink. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per i dettagli.121 Se hai bisogno di condividere file tra plugin, usa symlink. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per i dettagli.

122</Note>122</Note>

167</h3>167</h3>

168 168

170| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |170| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

171| `name` | string | Identificatore del marketplace in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: quando aggiungono un secondo marketplace con lo stesso nome, Claude Code sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |171| `name` | string | Identificatore del marketplace in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: quando aggiungono un secondo marketplace con lo stesso nome, Claude Code sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |

174 174

175<Note>175<Note>

176 **Nomi riservati**: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `claude-tag-plugins`, `healthcare`. Anche i nomi che impersonano marketplace ufficiali, come `official-claude-plugins` o `anthropic-plugins-v2`, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.176 **Nomi riservati**: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `claude-tag-plugins`, `healthcare`. Anche i nomi che impersonano marketplace ufficiali, come `official-claude-plugins` o `anthropic-plugins-v2`, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.

177 177

178 Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è [registrato da una fonte non attendibile](/docs/it/errors#marketplace-is-registered-from-an-untrusted-source). Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, `first-party-plugins` e `healthcare` non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi. Prima della v2.1.265, `claude-tag-plugins` non era riservato.178 Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è [registrato da una fonte non attendibile](/docs/it/errors#marketplace-is-registered-from-an-untrusted-source). Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, `first-party-plugins` e `healthcare` non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi. Prima della v2.1.265, `claude-tag-plugins` non era riservato.

179

180 Non puoi nemmeno denominare un marketplace `npm`, `pip`, `uv`, `cargo`, `github`, o `gh`, in nessuna combinazione di maiuscole e minuscole. Questo controllo richiede Claude Code v2.1.275 o successivo.

179</Note>181</Note>

180 182

181<h3 id="owner-fields">183<h3 id="owner-fields">

225**Campi di metadati standard:**227**Campi di metadati standard:**

226 228

228| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |230| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

229| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Quando né la voce né il `plugin.json` del plugin ne impostano uno, gli utenti vedono il `name` del plugin. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |231| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Quando né la voce né il `plugin.json` del plugin ne impostano uno, gli utenti vedono il `name` del plugin. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |

231| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una [`command` source](#command-sources) non è bloccato da nessuno dei due campi. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |233| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una [`command` source](#command-sources) non è bloccato da nessuno dei due campi. Neanche un plugin [caricato in place](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |

269| `headersHelper` | string | Comando che stampa le intestazioni HTTP per il download dell'archivio di questa voce come un singolo oggetto JSON, per una credenziale che scade. Vedi [Authenticate archive downloads](#authenticate-archive-downloads). La voce deve anche impostare [`"strict": false`](#strict-mode). Richiede Claude Code v2.1.238 o successivo. |271| `headersHelper` | string | Comando che stampa le intestazioni HTTP per il download dell'archivio di questa voce come un singolo oggetto JSON, per una credenziale che scade. Vedi [Authenticate archive downloads](#authenticate-archive-downloads). La voce deve anche impostare [`"strict": false`](#strict-mode). Richiede Claude Code v2.1.238 o successivo. |

270 272

271<h2 id="plugin-sources">273<h2 id="plugin-sources">

272 Plugin sources274 Origini dei plugin

273</h2>275</h2>

274 276

275Le plugin sources indicano a Claude Code dove recuperare ogni singolo plugin elencato nel tuo marketplace. Questi sono impostati nel campo `source` di ogni voce di plugin in `marketplace.json`.277Le origini dei plugin indicano a Claude Code dove ottenere ogni singolo plugin elencato nel tuo marketplace. Questi sono impostati nel campo `source` di ogni voce di plugin in `marketplace.json`.

276 278

277Claude Code copia ogni plugin installato nella cache del plugin locale con versione in `~/.claude/plugins/cache`, ad eccezione di una [`command` source in link mode](#copy-mode-and-link-mode), che Claude Code utilizza al suo posto. Claude Code inoltre [installa le dipendenze del pacchetto Node.js idonee del plugin](/docs/it/plugins-reference#node-js-package-dependencies) nella copia memorizzata nella cache.279Claude Code copia ogni plugin installato nella cache locale dei plugin con versione in `~/.claude/plugins/cache`, a meno che il plugin non si carichi al suo posto. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica al suo posto, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. Claude Code inoltre [installa le dipendenze del pacchetto Node.js idonee del plugin](/docs/it/plugins-reference#node-js-package-dependencies) nella copia memorizzata nella cache. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per come un plugin caricato al suo posto da un marketplace di directory locale raccoglie i tuoi modifiche.

278 280

280| ----------------- | --------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |282| ----------------- | --------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

281| Percorso relativo | `string` (ad es. `"./my-plugin"`) | nessuno | Directory locale all'interno del repository del marketplace. Deve iniziare con `./`, a meno che non scrivi un [bare name sotto `metadata.pluginRoot`](#relative-paths). Claude Code risolve il percorso relativamente alla radice del marketplace, non alla directory `.claude-plugin/` |283| Percorso relativo | `string` (ad es. `"./my-plugin"`) | nessuno | Directory locale all'interno del repository del marketplace. Deve iniziare con `./`, a meno che non scrivi un [nome semplice sotto `metadata.pluginRoot`](#relative-paths). Claude Code risolve il percorso relativo alla radice del marketplace, non alla directory `.claude-plugin/` |

287| `command` | object | `command`, `timeout?`, `mode?` | Directory del plugin prodotta dall'esecuzione di un comando locale, rieseguita una volta per sessione per raccogliere i cambiamenti. Richiede Claude Code v2.1.229 o successivo |289| `command` | object | `command`, `timeout?`, `mode?` | Directory del plugin prodotta dall'esecuzione di un comando locale, rieseguita una volta per sessione per raccogliere i cambiamenti. Richiede Claude Code v2.1.229 o successivo |

288 290

289<Note>291<Note>

290 **Marketplace sources vs plugin sources**: Questi sono concetti diversi che controllano cose diverse.292 **Origini del marketplace rispetto alle origini dei plugin**: Questi sono concetti diversi che controllano cose diverse.

291 293

292 * **Marketplace source**: dove recuperare il catalogo `marketplace.json` stesso. Impostato quando gli utenti eseguono `/plugin marketplace add` o nelle impostazioni `extraKnownMarketplaces`. Le marketplace sources basate su git supportano `ref` (branch/tag) ma non `sha`.294 * **Origine del marketplace**: dove recuperare il catalogo `marketplace.json` stesso. Impostato quando gli utenti eseguono `/plugin marketplace add` o nelle impostazioni `extraKnownMarketplaces`. Le origini del marketplace basate su Git supportano `ref` (branch/tag) ma non `sha`.

293 * **Plugin source**: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo `source` di ogni voce di plugin all'interno di `marketplace.json`. Le plugin sources basate su git supportano sia `ref` (branch/tag) che `sha` (commit esatto).295 * **Origine del plugin**: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo `source` di ogni voce di plugin all'interno di `marketplace.json`. Le origini dei plugin basate su Git supportano sia `ref` (branch/tag) che `sha` (commit esatto).

294 296

295 Ad esempio, un marketplace ospitato in `acme-corp/plugin-catalog` (marketplace source) può elencare un plugin recuperato da `acme-corp/code-formatter` (plugin source). La marketplace source e la plugin source puntano a repository diversi e sono fissate indipendentemente.297 Ad esempio, un marketplace ospitato in `acme-corp/plugin-catalog` (origine del marketplace) può elencare un plugin recuperato da `acme-corp/code-formatter` (origine del plugin). L'origine del marketplace e l'origine del plugin puntano a repository diversi e sono bloccate indipendentemente.

296</Note>298</Note>

297 299

298I tipi di source basati su git di seguito sono `github`, `url` e `git-subdir`. Quando sia `ref` che `sha` sono impostati su uno qualsiasi di essi, `sha` è il pin effettivo. Claude Code recupera e controlla il commit fissato direttamente.300I tipi di origine basati su git di seguito sono `github`, `url` e `git-subdir`. Quando sia `ref` che `sha` sono impostati su uno qualsiasi di essi, `sha` è il blocco effettivo. Claude Code recupera e controlla il commit bloccato direttamente.

299 301

300Su la maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket, questo significa che l'installazione ha successo anche se il branch o il tag denominato da `ref` è stato eliminato a monte, purché il commit sia ancora raggiungibile dal repository. Alcuni server, come AWS CodeCommit, non supportano il recupero dei commit per SHA. Su quei server il `ref` deve ancora esistere e il commit fissato deve essere raggiungibile da esso.302Sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket, ciò significa che l'installazione ha successo anche se il branch o il tag denominato da `ref` è stato successivamente eliminato a monte, purché il commit sia ancora raggiungibile dal repository. Alcuni server, come AWS CodeCommit, non supportano il recupero dei commit per SHA. Su questi server `ref` deve ancora esistere e il commit bloccato deve essere raggiungibile da esso.

301 303

302Se distribuisci plugin tramite **Organization settings > Plugins**, solo alcuni tipi di source sono consentiti. Vedi [Distribute through organization settings](#distribute-through-organization-settings).304Se distribuisci plugin tramite **Impostazioni organizzazione > Plugin**, sono consentiti solo alcuni tipi di origine. Vedi [Distribuire tramite impostazioni organizzazione](#distribute-through-organization-settings).

303 305

304<h3 id="relative-paths">306<h3 id="relative-paths">

305 Percorsi relativi307 Percorsi relativi

306</h3>308</h3>

307 309

308Per i plugin nello stesso repository, usa un percorso che inizia con `./`:310Per i plugin nello stesso repository, utilizza un percorso che inizia con `./`:

309 311

310```json theme={null}312```json theme={null}

311{313{

314}316}

315```317```

316 318

317I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente `.claude-plugin/`. Nell'esempio sopra, `./plugins/my-plugin` punta a `<repo>/plugins/my-plugin`, anche se `marketplace.json` si trova in `<repo>/.claude-plugin/marketplace.json`. Non usare `../` per fare riferimento a percorsi al di fuori della radice del marketplace. Su macOS e Linux, Claude Code rifiuta una voce di percorso con una barra rovesciata ovunque dopo il `./` iniziale, quindi scrivi i separatori come `/` su ogni piattaforma.319I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente `.claude-plugin/`. Nell'esempio precedente, `./plugins/my-plugin` punta a `<repo>/plugins/my-plugin`, anche se `marketplace.json` si trova in `<repo>/.claude-plugin/marketplace.json`. Non utilizzare `../` per fare riferimento a percorsi al di fuori della radice del marketplace. Su macOS e Linux, Claude Code rifiuta una voce di percorso con una barra rovesciata in qualsiasi punto dopo il `./` iniziale, quindi scrivi i separatori come `/` su ogni piattaforma.

318 320

319Un bare name è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere bare names invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) sulla directory in cui si risolvono. Con `"pluginRoot": "./plugins"`, Claude Code risolve `"source": "formatter"` a `./plugins/formatter`. Richiede Claude Code v2.1.239 o successivo.321Un nome semplice è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere nomi semplici invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) sulla directory in cui si risolvono. Con `"pluginRoot": "./plugins"`, Claude Code risolve `"source": "formatter"` in `./plugins/formatter`. Richiede Claude Code v2.1.239 o successivo.

320 322

321`metadata.pluginRoot` deve essere esso stesso un percorso relativo all'interno del marketplace. Claude Code lo ignora per una source che inizia già con `./`. Una source che contiene un `/`, come `team-a/formatter`, non è un bare name e ha ancora bisogno del prefisso `./`, anche quando `metadata.pluginRoot` è impostato.323`metadata.pluginRoot` deve essere esso stesso un percorso relativo all'interno del marketplace. Claude Code lo ignora per un'origine che inizia già con `./`. Un'origine che contiene un `/`, come `team-a/formatter`, non è un nome semplice e ha ancora bisogno del prefisso `./`, anche quando `metadata.pluginRoot` è impostato.

322 324

323<Note>325<Note>

324 Claude Code risolve i percorsi relativi rispetto a una copia locale del marketplace, quindi funzionano quando gli utenti aggiungono il tuo marketplace da una fonte git o da una directory locale. Se gli utenti aggiungono il tuo marketplace tramite un URL diretto al file `marketplace.json`, i percorsi relativi non si risolveranno, perché viene scaricato solo quel file. Per la distribuzione basata su URL, usa invece qualsiasi altra [plugin source](#plugin-sources). Vedi [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) per i dettagli.326 Claude Code risolve i percorsi relativi rispetto a una copia locale del marketplace, quindi funzionano quando gli utenti aggiungono il tuo marketplace da un'origine git o da una directory locale. Se gli utenti aggiungono il tuo marketplace tramite un URL diretto al file `marketplace.json`, i percorsi relativi non si risolveranno, perché Claude Code scarica solo quel file. Per la distribuzione basata su URL, utilizza invece qualsiasi altra [origine del plugin](#plugin-sources). Vedi [Risoluzione dei problemi](#plugins-with-relative-paths-fail-in-url-based-marketplaces) per i dettagli.

325</Note>327</Note>

326 328

327<h3 id="github-repositories">329<h3 id="github-repositories">

338}340}

339```341```

340 342

341Puoi fissare a un branch, tag o commit specifico:343Puoi bloccare a un branch, tag o commit specifico:

342 344

343```json theme={null}345```json theme={null}

344{346{

353```355```

354 356

356| :----- | :----- | :-------------------------------------------------------------------------------------- |358| :----- | :----- | :------------------------------------------------------------------------------------------------ |

358| `ref` | string | Opzionale. Branch o tag Git (predefinito al branch predefinito del repository) |360| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

359| `sha` | string | Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta |361| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

360 362

361<h3 id="git-repositories">363<h3 id="git-repositories">

362 Repository Git364 Repository Git

372}374}

373```375```

374 376

375Puoi fissare a un branch, tag o commit specifico:377Puoi bloccare a un branch, tag o commit specifico:

376 378

377```json theme={null}379```json theme={null}

378{380{

387```389```

388 390

390| :---- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |392| :---- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

391| `url` | string | Obbligatorio. URL completo del repository git (`https://` o `git@`). Il suffisso `.git` è opzionale, quindi gli URL di Azure DevOps e AWS CodeCommit senza il suffisso funzionano |393| `url` | string | Obbligatorio. URL completo del repository git (`https://` o `git@`). Il suffisso `.git` è facoltativo, quindi gli URL di Azure DevOps e AWS CodeCommit senza il suffisso funzionano |

392| `ref` | string | Opzionale. Branch o tag Git (predefinito al branch predefinito del repository) |394| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

393| `sha` | string | Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta |395| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

394 396

395<h3 id="git-subdirectories">397<h3 id="git-subdirectories">

396 Sottodirectory Git398 Sottodirectory Git

397</h3>399</h3>

398 400

399Usa `git-subdir` per puntare a un plugin che si trova all'interno di una sottodirectory di un repository git. Claude Code utilizza un clone parziale e sparso per recuperare solo la sottodirectory, riducendo al minimo la larghezza di banda per i grandi monorepo.401Utilizza `git-subdir` per puntare a un plugin che si trova all'interno di una sottodirectory di un repository git. Claude Code utilizza un clone parziale e sparso per recuperare solo la sottodirectory, riducendo al minimo la larghezza di banda per i grandi monorepo.

400 402

401```json theme={null}403```json theme={null}

402{404{

409}411}

410```412```

411 413

412Puoi fissare a un branch, tag o commit specifico:414Puoi bloccare a un branch, tag o commit specifico:

413 415

414```json theme={null}416```json theme={null}

415{417{

427Il campo `url` accetta anche una scorciatoia GitHub (`owner/repo`) o URL SSH (`git@github.com:owner/repo.git`).429Il campo `url` accetta anche una scorciatoia GitHub (`owner/repo`) o URL SSH (`git@github.com:owner/repo.git`).

428 430

430| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------- |432| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------------- |

431| `url` | string | Obbligatorio. URL del repository Git, scorciatoia GitHub `owner/repo` o URL SSH |433| `url` | string | Obbligatorio. URL del repository Git, scorciatoia GitHub `owner/repo`, o URL SSH |

433| `ref` | string | Opzionale. Branch o tag Git (predefinito al branch predefinito del repository) |435| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

434| `sha` | string | Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta |436| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

435 437

436<h3 id="npm-packages">438<h3 id="npm-packages">

437 Pacchetti npm439 Pacchetti npm

438</h3>440</h3>

439 441

440I plugin distribuiti come pacchetti npm vengono installati utilizzando `npm install`. Questo funziona con qualsiasi pacchetto nel registro npm pubblico o in un registro privato ospitato dal tuo team.442Un'origine npm può denominare qualsiasi pacchetto nel registro npm pubblico o in un registro privato ospitato dal tuo team. Claude Code risolve il pacchetto con il tuo client npm, scarica il tarball e lo decomprime nella cache del plugin.

443

444Gli script di installazione del pacchetto, come `preinstall` o `postinstall`, non vengono mai eseguiti, e le sue dipendenze non vengono installate durante il recupero.

445

446Se il pacchetto fornisce un lockfile supportato accanto al suo `package.json`, Claude Code installa quelle [dipendenze del pacchetto Node.js](/docs/it/plugins-reference#node-js-package-dependencies) in un passaggio separato, anche con script disabilitati. Altrimenti, pubblica il plugin con tutto ciò di cui ha bisogno già costruito. Un server MCP che ha bisogno di altri pacchetti può avviarsi tramite `npx`, che li installa al primo esecuzione.

441 447

442```json theme={null}448```json theme={null}

443{449{

449}455}

450```456```

451 457

452Per fissare a una versione specifica, aggiungi il campo `version`:458Per bloccare a una versione specifica, aggiungi il campo `version`:

453 459

454```json theme={null}460```json theme={null}

455{461{

477```483```

478 484

480| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------- |486| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------- |

484 490

485<h3 id="zip-archives">491<h3 id="zip-archives">

486 Archivi zip492 Archivi zip

487</h3>493</h3>

488 494

489Usa `archive` per distribuire un plugin come file zip che Claude Code scarica tramite HTTPS, in modo che gli install funzionino senza git o npm sulla macchina dell'utente. Ospita il file su qualsiasi server di file statici o repository di artefatti, come un bucket S3, un repository generico di Artifactory o nginx. Richiede Claude Code v2.1.224 o successivo. Sulle versioni da v2.1.120 a v2.1.223, l'installazione del plugin fallisce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`; sulle versioni precedenti, un marketplace contenente una voce `archive` non riesce a caricarsi completamente.495Utilizza `archive` per distribuire un plugin come file zip che Claude Code scarica tramite HTTPS, in modo che le installazioni funzionino senza git o npm sulla macchina dell'utente. Ospita il file su qualsiasi server di file statici o repository di artefatti, come un bucket S3, un repository generico di Artifactory o nginx. Richiede Claude Code v2.1.224 o successivo. Nelle versioni da v2.1.120 a v2.1.223, l'installazione del plugin non riesce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`; nelle versioni precedenti, un marketplace contenente una voce `archive` non si carica affatto.

490 496

491Questa voce installa il plugin da un file zip su un server di artefatti:497Questa voce installa il plugin da un file zip su un server di artefatti:

492 498

500}506}

501```507```

502 508

503Quando crei lo zip, puoi zippare i contenuti del plugin direttamente o zippare la cartella del plugin stessa. Claude Code cerca `.claude-plugin/` in cima all'archivio, quindi all'interno di una singola cartella di livello superiore, quindi entrambi i layout si installano:509Quando crei il file zip, puoi comprimere direttamente il contenuto del plugin o comprimere la cartella del plugin stessa. Claude Code cerca `.claude-plugin/` in cima all'archivio, quindi all'interno di una singola cartella di primo livello, quindi entrambi i layout si installano:

504 510

505```text theme={null}511```text theme={null}

506my-plugin.zip my-plugin.zip512my-plugin.zip my-plugin.zip

510 └── commands/516 └── commands/

511```517```

512 518

513Claude Code non cerca più in profondità di una cartella, quindi un plugin annidato più in basso non riesce a installarsi. Claude Code rifiuta gli archivi più grandi di 256 MiB.519Claude Code non cerca più in profondità di una cartella, quindi un plugin annidato più in basso non si installa. Claude Code rifiuta gli archivi più grandi di 256 MiB.

514 520

515Per fissare il file esatto, aggiungi un campo `sha256` con il digest dell'archivio:521Per bloccare il file esatto, aggiungi un campo `sha256` con il digest dell'archivio:

516 522

517```json theme={null}523```json theme={null}

518{524{

525}531}

526```532```

527 533

528Se il file scaricato non corrisponde al pin, Claude Code rifiuta l'install e segnala [`Plugin archive integrity check failed`](/docs/it/errors#plugin-archive-integrity-check-failed).534Se il file scaricato non corrisponde al blocco, Claude Code rifiuta l'installazione e segnala [`Plugin archive integrity check failed`](/docs/it/errors#plugin-archive-integrity-check-failed).

529 535

530Le archive sources accettano questi campi:536Le origini dell'archivio accettano questi campi:

531 537

533| :------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |539| :------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

534| `url` | string | Obbligatorio. URL HTTPS dell'archivio zip. Claude Code rifiuta gli URL `http://`, insieme agli host loopback, link-local e cloud-metadata. Ogni hop di reindirizzamento deve soddisfare le stesse regole, o Claude Code rifiuta il download |540| `url` | string | Obbligatorio. URL HTTPS dell'archivio zip. Claude Code rifiuta gli URL `http://`, insieme agli host loopback, link-local e cloud-metadata. Ogni hop di reindirizzamento deve soddisfare le stesse regole, o Claude Code rifiuta il download |

535| `sha256` | string | Opzionale. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'install su una mancata corrispondenza |541| `sha256` | string | Facoltativo. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'installazione in caso di mancata corrispondenza |

536 542

537Il digest `sha256` serve anche come versione del plugin quando né `plugin.json` né la voce del marketplace ne dichiara una. Vedi [Version management](/docs/it/plugins-reference#version-management). Se dichiari una `version`, quella stringa di versione è il segnale di aggiornamento, quindi dopo aver cambiato lo zip e il suo digest, aumenta anche la versione, o gli utenti mantengono la copia memorizzata nella cache.543Il digest `sha256` serve anche come versione del plugin quando né `plugin.json` né la voce del marketplace ne dichiara una. Vedi [Gestione delle versioni](/docs/it/plugins-reference#version-management). Se dichiari una `version`, quella stringa di versione è il segnale di aggiornamento, quindi dopo aver modificato il file zip e il suo digest, aumenta anche la versione, altrimenti gli utenti mantengono la copia memorizzata nella cache.

538 544

539<h4 id="authenticate-archive-downloads">545<h4 id="authenticate-archive-downloads">

540 Autentica i download degli archivi546 Autentica i download dell'archivio

541</h4>547</h4>

542 548

543Per autenticare un download di archivio, come un download da un registro privato, imposta le intestazioni HTTP che Claude Code invia con esso. Imposta `headers` sulla `url` source da cui hai registrato il marketplace, come una voce [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces). Su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce del plugin invece, accanto a `source`.549Per autenticare un download dell'archivio, come un download da un registro privato, imposta le intestazioni HTTP che Claude Code invia con esso. Imposta `headers` sull'origine `url` da cui hai registrato il marketplace, come una voce [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces). Su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce del plugin invece, accanto a `source`.

544 550

545Se il valore che metteresti in `headers` è di breve durata, come un token che il tuo registro conia su richiesta, imposta un comando `headersHelper` nello stesso posto. Claude Code esegue il comando e invia l'oggetto JSON che stampa come intestazioni di quel posto. Richiede Claude Code v2.1.238 o successivo.551Se il valore che inseriresti in `headers` è di breve durata, come un token che il tuo registro crea su richiesta, imposta invece un comando `headersHelper` nello stesso posto. Claude Code esegue il comando e invia l'oggetto JSON che stampa come intestazioni di quel posto. Richiede Claude Code v2.1.238 o successivo.

546 552

547Il posto che scegli decide quali download ottengono le intestazioni e quando Claude Code esegue il comando:553Il posto che scegli decide quali download ricevono le intestazioni e quando Claude Code esegue il comando:

548 554

550| :----------------------- | :----------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |556| :---------------------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

551| Marketplace `url` source | Download di archivi sull'origine dell'URL del marketplace, ovvero lo stesso schema, host e porta | Prima di ogni fetch del `marketplace.json` del marketplace e prima di ogni download di archivio su quell'origine. Claude Code riutilizza l'output di un'esecuzione per fino a 60 secondi |557| Origine `url` del marketplace | Download dell'archivio sull'origine dell'URL del marketplace, ovvero lo stesso schema, host e porta | Prima di ogni recupero del `marketplace.json` del marketplace e prima di ogni download dell'archivio su quell'origine. Claude Code riutilizza l'output di un'esecuzione per fino a 60 secondi |

552| Voce del plugin | Solo il download di quella voce | Solo quando un utente installa o aggiorna quel singolo plugin da solo e [accetta il comando](#how-users-accept-a-headershelper-command) |558| Voce del plugin | Solo il download di quella voce | Solo quando un utente installa o aggiorna quel singolo plugin da solo e [accetta il comando](#how-users-accept-a-headershelper-command) |

553 559

554Dove entrambi i posti impostano un'intestazione con lo stesso nome, Claude Code invia il valore della voce. All'interno di un posto, un'intestazione che il comando stampa sostituisce un'intestazione con lo stesso nome elencata in `headers`.560Dove entrambi i posti impostano un'intestazione con lo stesso nome, Claude Code invia il valore della voce. All'interno di un posto, un'intestazione che il comando stampa sostituisce un'intestazione con lo stesso nome elencata in `headers`.

557 Aggiungi un headersHelper a una voce di plugin563 Aggiungi un headersHelper a una voce di plugin

558</h5>564</h5>

559 565

560Questa voce imposta `headersHelper` accanto a `source`. Imposta anche `"strict": false`, che Claude Code richiede di una voce `marketplace.json` che imposta `headersHelper`. Con [`"strict": false`](#strict-mode), la voce del marketplace è la definizione completa del plugin, quindi un utente può rivedere cosa contiene il plugin prima di accettare il comando:566Questa voce imposta `headersHelper` accanto a `source`. Imposta anche `"strict": false`, che Claude Code richiede di una voce `marketplace.json` che imposta `headersHelper`. Con [`"strict": false`](#strict-mode), la voce del marketplace è l'intera definizione del plugin, quindi un utente può rivedere cosa contiene il plugin prima di accettare il comando:

561 567

562```json theme={null}568```json theme={null}

563{569{

573}579}

574```580```

575 581

576Per controllare la voce, esegui `claude plugin install my-plugin@your-marketplace`. Claude Code ti mostra il comando e l'URL dell'archivio, e scarica lo zip dopo che accetti.582Per controllare la voce, esegui `claude plugin install my-plugin@your-marketplace`. Claude Code ti mostra il comando e l'URL dell'archivio, e scarica il file zip dopo che accetti.

577 583

578Prima di v2.1.238, Claude Code scaricava un archivio di una voce senza le sue `headers` o `headersHelper`, quindi un install che si basava su di esse falliva con `HTTP 401 while downloading plugin archive from`, seguito dall'URL, con il codice di stato del registro al posto di 401.584Prima della v2.1.238, Claude Code scaricava l'archivio di una voce senza le sue `headers` o `headersHelper`, quindi un'installazione che si basava su di esse non riusciva con `HTTP 401 while downloading plugin archive from`, seguito dall'URL, con il codice di stato del registro al posto di 401.

579 585

580<h4 id="write-the-headershelper-command">586<h4 id="write-the-headershelper-command">

581 Scrivi il comando headersHelper587 Scrivi il comando headersHelper

582</h4>588</h4>

583 589

584Che tu imposti `headersHelper` su una `url` source di un marketplace o su una voce di plugin, scrivi il comando per soddisfare questi requisiti:590Che tu imposti `headersHelper` sull'origine `url` di un marketplace o su una voce di plugin, scrivi il comando per soddisfare questi requisiti:

585 591

586* **Testo del comando**: al massimo 500 caratteri di ASCII stampabile, senza una sequenza di quattro o più spazi.592* **Testo del comando**: al massimo 500 caratteri di ASCII stampabile, senza sequenze di quattro o più spazi.

587* **Output**: stampa un oggetto JSON di nomi di intestazione e valori di stringa su stdout, quindi esci con 0 entro 10 secondi.593* **Output**: stampa un oggetto JSON di nomi di intestazione e valori di stringa su stdout, quindi esci con 0 entro 10 secondi.

588* **Shell e directory di lavoro**: Claude Code esegue il comando tramite `sh`, o `cmd.exe` su Windows, dalla directory di configurazione, `~/.claude` o [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars#variables). Fornisci un percorso assoluto o un comando su `PATH`, perché un percorso relativo si risolve rispetto a quella directory, non al progetto dell'utente.594* **Shell e directory di lavoro**: Claude Code esegue il comando tramite `sh`, o `cmd.exe` su Windows, dalla directory di configurazione, `~/.claude` o [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars#variables). Fornisci un percorso assoluto o un comando su `PATH`, perché un percorso relativo si risolve rispetto a quella directory, non al progetto dell'utente.

589* **Variabili che Claude Code rimuove**: dall'ambiente di un comando impostato in una voce `marketplace.json` o in un `.claude/settings.json` o `.claude/settings.local.json` di un progetto, Claude Code rimuove ogni variabile il cui nome contiene una parola come `TOKEN`, `SECRET`, `KEY` o `AUTH`, incluso `ANTHROPIC_API_KEY`. Claude Code non applica questa rimozione a un comando impostato nelle impostazioni utente, un file `--settings` o impostazioni gestite.595* **Variabili che Claude Code rimuove**: dall'ambiente di un comando impostato in una voce `marketplace.json` o nelle impostazioni `.claude/settings.json` o `.claude/settings.local.json` di un progetto, Claude Code rimuove ogni variabile il cui nome contiene una parola come `TOKEN`, `SECRET`, `KEY` o `AUTH`, incluso `ANTHROPIC_API_KEY`. Claude Code non applica questa rimozione a un comando impostato nelle impostazioni utente, in un file `--settings` o nelle impostazioni gestite.

590* **Variabili che Claude Code imposta**: `CLAUDE_CODE_MARKETPLACE_URL` e `CLAUDE_CODE_MARKETPLACE_NAME` per il comando di una `url` source, e `CLAUDE_CODE_PLUGIN_NAME` e `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` per il comando di una voce. `CLAUDE_CODE_MARKETPLACE_NAME` non è impostato al primo fetch dopo che un utente aggiunge un marketplace per URL, perché quel fetch è quello che fornisce il nome.596* **Variabili che Claude Code imposta**: `CLAUDE_CODE_MARKETPLACE_URL` e `CLAUDE_CODE_MARKETPLACE_NAME` per il comando di un'origine `url`, e `CLAUDE_CODE_PLUGIN_NAME` e `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` per il comando di una voce. `CLAUDE_CODE_MARKETPLACE_NAME` non è impostato al primo recupero dopo che un utente aggiunge un marketplace per URL, perché quel recupero è quello che fornisce il nome.

591 597

592Un comando che conia un token bearer stampa un oggetto come questo:598Un comando che crea un token bearer stampa un oggetto come questo:

593 599

594```json theme={null}600```json theme={null}

595{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

601 607

602Claude Code non esegue un comando `headersHelper`, o scarta le intestazioni che provengono da `headers` o dall'output del comando, in queste situazioni:608Claude Code non esegue un comando `headersHelper`, o scarta le intestazioni che provengono da `headers` o dall'output del comando, in queste situazioni:

603 609

604* **Il comando fallisce**: se il comando esce con non-zero, corre oltre 10 secondi, o stampa qualcosa di diverso da un oggetto JSON di valori di stringa, Claude Code non effettua il fetch o il download per cui ha eseguito il comando.610* **Il comando non riesce**: se il comando esce con codice diverso da zero, viene eseguito oltre 10 secondi, o stampa qualcosa di diverso da un oggetto JSON di valori di stringa, Claude Code non effettua il recupero o il download per cui ha eseguito il comando.

605* **L'URL del marketplace non inizia con `https://`**: Claude Code non esegue il comando di quella `url` source e invia solo le intestazioni elencate nel suo campo `headers`.611* **L'URL del marketplace non inizia con `https://`**: Claude Code non esegue il comando di quell'origine `url` e invia solo le intestazioni elencate nel suo campo `headers`.

606* **Il reindirizzamento lascia l'origine**: quando un download viene reindirizzato fuori dall'origine dell'URL dell'archivio, Claude Code scarta i valori `headers` e l'output del comando sia della `url` source del marketplace che della voce del plugin.612* **Il reindirizzamento lascia l'origine**: quando un download viene reindirizzato dall'origine dell'URL dell'archivio, Claude Code scarta i valori `headers` e l'output del comando sia dell'origine `url` del marketplace che della voce del plugin.

607* **La voce imposta un'intestazione di routing o identità**: Claude Code scarta i nomi di routing delle richieste e identità del client come `Host`, `Cookie` e `X-Forwarded-*` da `headers` e dall'output del comando di una voce, e mantiene i nomi di autenticazione come `Authorization`. Claude Code filtra ogni voce `marketplace.json` in questo modo, e una voce [inline settings](/docs/it/settings-reference#extraknownmarketplaces) a seconda di quale file la dichiara.613* **La voce imposta un'intestazione di routing o identità**: Claude Code scarta i nomi di routing delle richieste e identità del client come `Host`, `Cookie` e `X-Forwarded-*` dalle `headers` e dall'output del comando di una voce, e mantiene i nomi di autenticazione come `Authorization`. Claude Code filtra ogni voce `marketplace.json` in questo modo, e una voce [inline settings](/docs/it/settings-reference#extraknownmarketplaces) a seconda di quale file la dichiara.

608* **Il comando è impostato nelle impostazioni di una directory `--add-dir`**: Claude Code lo ignora, su una `url` source e su una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces) allo stesso modo, e invia solo le `headers` di quel file.614* **Il comando è impostato nelle impostazioni di una directory `--add-dir`**: Claude Code lo ignora, sia su un'origine `url` che su una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces), e invia solo le `headers` di quel file.

609* **Le impostazioni gestite bloccano il comando**: impostare [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources) a `true` blocca i comandi `headersHelper`, e [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) li blocca anche a meno che `disableCommandPluginSources` non sia esplicitamente `false`. Sotto uno di questi blocchi, Claude Code esegue ancora il comando per un marketplace che le impostazioni gestite stesse dichiarano.615* **Le impostazioni gestite bloccano il comando**: impostare [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources) su `true` blocca i comandi `headersHelper`, e [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) li blocca anche a meno che `disableCommandPluginSources` non sia esplicitamente `false`. Sotto uno di questi blocchi, Claude Code esegue comunque il comando per un marketplace che le impostazioni gestite stesse dichiarano.

610 616

611<h4 id="how-users-accept-a-headershelper-command">617<h4 id="how-users-accept-a-headershelper-command">

612 Come gli utenti accettano un comando headersHelper618 Come gli utenti accettano un comando headersHelper

613</h4>619</h4>

614 620

615Un utente accetta il comando di una voce di plugin ogni volta che installa o aggiorna quel singolo plugin da solo, dalla vista del plugin in `/plugin` o con `claude plugin install` o `claude plugin update`. Claude Code mostra il comando e l'URL dell'archivio, ed esegue il comando solo dopo che l'utente accetta. In una shell non interattiva, passa [`--yes`](/docs/it/plugins-reference#plugin-install) per accettarlo.621Un utente accetta il comando di una voce di plugin ogni volta che installa o aggiorna quel singolo plugin da solo, dalla vista del plugin in `/plugin` o con `claude plugin install` o `claude plugin update`. Claude Code mostra il comando e l'URL dell'archivio, ed esegue il comando solo dopo che l'utente accetta.

616 622

617Claude Code esegue solo il comando che ha mostrato, per l'URL dell'archivio che ha mostrato. Se il comando o l'URL dell'archivio della voce sono cambiati nel frattempo, Claude Code rifiuta l'install o l'aggiornamento. Un cambio nella stringa di query da solo non conta.623In una shell non interattiva, passa [`--yes`](/docs/it/plugins-reference#plugin-install) per accettare il comando. Per accettare solo il comando che un'esecuzione precedente con `--json` ha visualizzato, passa [`--accept-command`](/docs/it/plugins-reference#plugin-install) con lo `sha256` che l'esecuzione ha segnalato.

624

625Claude Code esegue solo il comando che ha mostrato, per l'URL dell'archivio che ha mostrato. Se il comando o l'URL dell'archivio della voce sono cambiati nel frattempo, Claude Code rifiuta l'installazione o l'aggiornamento. Un cambio nella stringa di query da solo non conta.

618 626

619<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">627<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

620 Install e aggiornamenti che rifiutano il comando invece di chiedere628 Installazioni e aggiornamenti che rifiutano il comando invece di chiedere

621</h5>629</h5>

622 630

623Su qualsiasi operazione diversa da un install o aggiornamento di un singolo plugin, Claude Code non esegue il comando di una voce né scarica il suo archivio, quindi il plugin rimane alla sua versione installata o rimane disinstallato. Quello che l'utente vede dipende dall'operazione:631Su qualsiasi operazione diversa da un'installazione o aggiornamento di un singolo plugin, Claude Code non esegue il comando di una voce né scarica il suo archivio, quindi il plugin rimane alla versione installata o rimane disinstallato. Quello che l'utente vede dipende dall'operazione:

624 632

625* **Installazione di più plugin contemporaneamente, da un suggerimento di plugin o come dipendenza di un altro plugin**: Claude Code rifiuta il plugin che ha il comando e punta l'utente alla vista di quel plugin in `/plugin`. Gli altri plugin in un install in blocco si installano comunque. Un plugin che dipende dal plugin rifiutato non riesce a installarsi finché l'utente non installa il plugin rifiutato da solo.633* **Installazione di più plugin contemporaneamente, da un suggerimento di plugin, o come dipendenza di un altro plugin**: Claude Code rifiuta il plugin che ha il comando e indirizza l'utente alla vista di quel plugin in `/plugin`. Gli altri plugin in un'installazione in blocco si installano comunque. Un plugin che dipende dal plugin rifiutato non si installa fino a quando l'utente non installa il plugin rifiutato da solo.

626* **Auto-aggiornamento in background, o avvio della sessione per un plugin il cui archivio non è mai stato scaricato**: Claude Code elenca il plugin nella scheda `/plugin` Errors in modo che l'utente sappia di installarlo o aggiornarlo manualmente. Un auto-aggiornamento che trova la voce ancora pubblicizza la versione installata non elenca nulla.634* **Aggiornamento automatico in background, o avvio della sessione per un plugin il cui archivio non è mai stato scaricato**: Claude Code elenca il plugin nella scheda Errori di `/plugin` in modo che l'utente sappia di installarlo o aggiornarlo manualmente. Un aggiornamento automatico che trova la voce ancora pubblicizza l'elenco della versione installata non mostra nulla.

627 635

628<h5 id="when-a-marketplace-url-source’s-command-runs">636<h5 id="when-a-marketplace-url-source’s-command-runs">

629 Quando il comando headersHelper di una marketplace `url` source viene eseguito637 Quando viene eseguito il comando di un'origine `url` del marketplace

630</h5>638</h5>

631 639

632Un `headersHelper` di una marketplace `url` source è dichiarato in un file di impostazioni, come una voce [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces), piuttosto che nel catalogo che il marketplace pubblica, quindi Claude Code non chiede all'utente di accettarlo su ogni install o aggiornamento. Il file di impostazioni che lo dichiara decide quando Claude Code lo esegue:640Un `headersHelper` di un'origine `url` del marketplace è dichiarato in un file di impostazioni, come una voce [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces), piuttosto che nel catalogo che il marketplace pubblica, quindi Claude Code non chiede all'utente di accettarlo su ogni installazione o aggiornamento. Il file di impostazioni che lo dichiara decide quando Claude Code lo esegue:

633 641

634| File di impostazioni | Quando Claude Code esegue il comando |642| File di impostazioni | Quando Claude Code esegue il comando |

635| :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |643| :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

636| Impostazioni utente, un file `--settings` o un file di impostazioni gestite sulla macchina | Senza chiedere, incluso durante un aggiornamento del marketplace in background |644| Impostazioni utente, un file `--settings`, o un file di impostazioni gestite sulla macchina | Senza chiedere, incluso durante un aggiornamento del marketplace in background |

637| Un `.claude/settings.json` o `.claude/settings.local.json` di un progetto | Solo dopo che l'utente accetta la [workspace trust dialog](/docs/it/permissions#what-runs-before-you-trust-a-folder) per quella cartella stessa. Una sessione `-p` o SDK non conta come accettarla, e nemmeno la fiducia concessa a una cartella padre |645| `.claude/settings.json` o `.claude/settings.local.json` di un progetto | Solo dopo che l'utente accetta la [finestra di dialogo di trust dell'area di lavoro](/docs/it/permissions#what-runs-before-you-trust-a-folder) per quella cartella stessa. Una sessione `-p` o SDK non conta come accettazione, e nemmeno il trust concesso a una cartella padre |

638| Impostazioni gestite dal server | Solo dopo che l'utente approva le impostazioni consegnate nella [security approval dialog](/docs/it/server-managed-settings#security-approval-dialogs) |646| Impostazioni gestite dal server | Solo dopo che l'utente approva le impostazioni consegnate nella [finestra di dialogo di approvazione della sicurezza](/docs/it/server-managed-settings#security-approval-dialogs) |

639 647

640In una sessione `-p` o SDK, Claude Code non può mostrare la security approval dialog. Applica le altre impostazioni consegnate, ma il fetch del marketplace e qualsiasi download di archivio che ha bisogno del comando fallisce finché un utente non ha approvato in una sessione interattiva.648In una sessione `-p` o SDK, Claude Code non può mostrare la finestra di dialogo di approvazione della sicurezza. Applica le altre impostazioni consegnate, ma il recupero del marketplace, e qualsiasi download dell'archivio che ha bisogno del comando, non riesce fino a quando un utente non ha approvato in una sessione interattiva.

641 649

642Per una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces) in uno di questi file, Claude Code richiede la stessa fiducia della cartella o approvazione delle impostazioni come per un comando a livello di marketplace in quel file, e l'utente accetta anche il comando della voce su ogni install o aggiornamento.650Per una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces) in uno di questi file, Claude Code richiede lo stesso trust della cartella o approvazione delle impostazioni come per un comando a livello di marketplace in quel file, e l'utente accetta anche il comando della voce su ogni installazione o aggiornamento.

643 651

644<h3 id="command-sources">652<h3 id="command-sources">

645 Command sources653 Origini dei comandi

646</h3>654</h3>

647 655

648Usa `command` quando uno strumento installato localmente produce la directory del plugin, come un IDE che renderizza il suo plugin per la toolchain attualmente selezionata. Claude Code esegue il comando quando l'utente installa il plugin e lo riesegue in background una volta per sessione, quindi i tuoi utenti raccolgono l'output modificato dello strumento senza reinstallare. Richiede Claude Code v2.1.229 o successivo. Su v2.1.120 attraverso v2.1.228, l'installazione del plugin fallisce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`, e sulle versioni precedenti l'intero marketplace non riesce a caricarsi.656Utilizza `command` quando uno strumento installato localmente produce la directory del plugin, come un IDE che renderizza il suo plugin per la toolchain attualmente selezionata. Claude Code esegue il comando quando l'utente installa il plugin e lo riesegue in background una volta per sessione, quindi i tuoi utenti raccolgono l'output modificato dello strumento senza reinstallare. Richiede Claude Code v2.1.229 o successivo. Nella versione da v2.1.120 a v2.1.228, l'installazione del plugin non riesce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`, e nelle versioni precedenti l'intero marketplace non si carica.

649 657

650Questa voce installa il plugin da qualsiasi directory che lo strumento stampa:658Questa voce installa il plugin da qualsiasi directory che lo strumento stampa:

651 659

659}667}

660```668```

661 669

662Claude Code esegue il comando tramite la shell della piattaforma, `sh` su macOS e Linux o `cmd.exe` su Windows, dalla directory home dell'utente. Il comando deve stampare esattamente una riga su stdout e uscire con codice 0. Quella riga è il percorso assoluto di una directory che contiene il plugin completo al momento in cui il comando esce, e il percorso può cambiare tra le esecuzioni.670Claude Code esegue il comando tramite la shell della piattaforma, `sh` su macOS e Linux o `cmd.exe` su Windows, dalla directory home dell'utente. Il comando deve stampare esattamente una riga su stdout e uscire con codice 0. Quella riga è il percorso assoluto di una directory che contiene il plugin completo al momento dell'uscita del comando, e il percorso può cambiare tra le esecuzioni.

663 671

664Claude Code ferma un comando che corre più a lungo di `timeout` secondi, e l'install o l'aggiornamento fallisce. Claude Code rifiuta anche il percorso stampato in questi casi, e l'install o l'aggiornamento fallisce allo stesso modo:672Claude Code interrompe un comando che viene eseguito più a lungo di `timeout` secondi, e l'installazione o l'aggiornamento non riesce. Claude Code rifiuta anche il percorso stampato in questi casi, e l'installazione o l'aggiornamento non riesce allo stesso modo:

665 673

666* La directory non ha contenuto di plugin al suo livello superiore, come una directory `.claude-plugin/` o una directory `skills/`, `commands/`, `agents/` o `hooks/`674* La directory non ha contenuto di plugin al suo livello superiore, come una directory `.claude-plugin/` o una directory `skills/`, `commands/`, `agents/` o `hooks/`

667* La directory è quella in cui Claude Code è stato avviato, o una delle sue padre675* La directory è quella in cui Claude Code è stato avviato, o una delle sue cartelle padre

668* Su Windows, il percorso è un percorso UNC676* Su Windows, il percorso è un percorso UNC

669 677

670Le command sources accettano questi campi:678Le origini dei comandi accettano questi campi:

671 679

673| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |681| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

674| `command` | string | Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce 0. Deve essere ASCII stampabile, al massimo 500 caratteri, senza sequenze di quattro o più spazi, in modo che gli utenti possano rivedere l'intero comando che gli viene chiesto di accettare |682| `command` | string | Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce con 0. Deve essere ASCII stampabile, al massimo 500 caratteri, senza sequenze di quattro o più spazi, in modo che gli utenti possano rivedere l'intero comando che viene loro chiesto di accettare |

676| `mode` | string | Opzionale. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi [Copy mode and link mode](#copy-mode-and-link-mode) |684| `mode` | string | Facoltativo. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi [Modalità copia e modalità link](#copy-mode-and-link-mode) |

677 685

678<h4 id="copy-mode-and-link-mode">686<h4 id="copy-mode-and-link-mode">

679 Copy mode and link mode687 Modalità copia e modalità link

680</h4>688</h4>

681 689

682Con il predefinito `"mode": "copy"`, Claude Code copia la directory stampata nella cache del plugin con versione e deriva la [plugin version](/docs/it/plugins-reference#version-management) da un hash dei contenuti della directory. Il tuo strumento può eliminare o riscrivere la directory dopo che il comando esce, e una riesecuzione che produce contenuto identico conta come aggiornato. Claude Code rifiuta di installare una directory più grande di 256 MiB o contenente più di 20.000 voci.690Con il valore predefinito `"mode": "copy"`, Claude Code copia la directory stampata nella cache del plugin con versione e deriva la [versione del plugin](/docs/it/plugins-reference#version-management) da un hash del contenuto della directory. Il tuo strumento può eliminare o riscrivere la directory dopo l'uscita del comando, e una riesecuzione che produce contenuto identico conta come aggiornato. Claude Code rifiuta di installare una directory più grande di 256 MiB o contenente più di 20.000 voci.

683 691

684Imposta `"mode": "link"` per le directory di plugin grandi che non dovrebbero essere copiate, come un'esportazione SDK renderizzata. Claude Code riempie la voce della cache del plugin con un link a ogni voce di livello superiore della directory stampata e utilizza i file al suo posto, quindi nulla viene copiato, i contenuti dei file non vengono sottoposti a hash e i limiti di dimensione non si applicano. L'install fallisce se una voce di livello superiore è un symlink che punta al di fuori della directory stampata. Claude Code salta anche l'[install della dipendenza del pacchetto Node.js](/docs/it/plugins-reference#node-js-package-dependencies) per un plugin in link mode, quindi stampa una directory che contiene già qualsiasi `node_modules` di cui il plugin ha bisogno.692Imposta `"mode": "link"` per le directory di plugin di grandi dimensioni che non dovrebbero essere copiate, come un'esportazione SDK renderizzata. Claude Code riempie la voce della cache del plugin con un link a ogni voce di primo livello della directory stampata e utilizza i file al suo posto, quindi nulla viene copiato, i contenuti dei file non vengono sottoposti a hash, e i limiti di dimensione non si applicano. L'installazione non riesce se una voce di primo livello è un symlink che punta al di fuori della directory stampata. Claude Code salta anche l'[installazione della dipendenza del pacchetto Node.js](/docs/it/plugins-reference#node-js-package-dependencies) per un plugin in modalità link, quindi stampa una directory che contiene già qualsiasi `node_modules` di cui il plugin ha bisogno.

685 693

686Mantieni la directory stampata al suo posto finché il plugin rimane installato, perché Claude Code carica il plugin attraverso quei link ad ogni avvio. Claude Code deriva la [plugin version](/docs/it/plugins-reference#version-management) dal percorso reale della directory stampata e dalle sue voci di livello superiore, non dai file all'interno, quindi stampa un percorso diverso per segnalare nuovo contenuto. In una sessione avviata nella directory stampata o ovunque al di sotto di essa, Claude Code non carica il plugin affatto.694Mantieni la directory stampata al suo posto per tutto il tempo in cui il plugin rimane installato, perché Claude Code carica il plugin attraverso quei link ad ogni avvio. Claude Code deriva la [versione del plugin](/docs/it/plugins-reference#version-management) dal percorso reale della directory stampata e dalle sue voci di primo livello, non dai file all'interno, quindi stampa un percorso diverso per segnalare nuovo contenuto. In una sessione avviata nella directory stampata o in qualsiasi punto al di sotto di essa, Claude Code non carica affatto il plugin.

687 695

688Claude Code non supporta link mode su Windows e rifiuta di installare un plugin in link mode lì. Dichiara `"mode": "copy"` invece.696Claude Code non supporta la modalità link su Windows e rifiuta di installare un plugin in modalità link lì. Dichiara `"mode": "copy"` invece.

689 697

690<h4 id="how-users-accept-the-command">698<h4 id="how-users-accept-the-command">

691 Come gli utenti accettano il comando699 Come gli utenti accettano il comando

693 701

694Claude Code esegue il tuo comando sulla macchina dell'utente, quindi lega ogni esecuzione all'accettazione esplicita dell'utente:702Claude Code esegue il tuo comando sulla macchina dell'utente, quindi lega ogni esecuzione all'accettazione esplicita dell'utente:

695 703

696* Quando gli utenti installano il plugin dalla sua schermata dei dettagli in `/plugin`, o lo installano o aggiornano con `claude plugin install` o `claude plugin update` in un terminale interattivo, Claude Code mostra loro la stringa di comando esatta per prima e registra il comando accettato per quella installazione. Un `claude plugin update` che può procedere sull'accettazione registrata dello stesso comando non mostra nulla. In una shell non interattiva, come uno script di provisioning, passa `--yes` a `claude plugin install` o `claude plugin update` per accettare il comando che stampa.704* Quando gli utenti installano il plugin dalla sua schermata dei dettagli in `/plugin`, o lo installano o aggiornano con `claude plugin install` o `claude plugin update` in un terminale interattivo, Claude Code mostra loro la stringa di comando esatta per prima e registra il comando accettato per quell'installazione. Un `claude plugin update` che può procedere sull'accettazione registrata dello stesso comando non mostra nulla.

697* Ogni altro percorso esegue solo il comando che l'utente ha già accettato. Questo include gli aggiornamenti avviati da `/plugin` e le esecuzioni in background descritte in [When Claude Code re-runs the command](#when-claude-code-re-runs-the-command). Quando nessuno è stato accettato, Claude Code rifiuta di eseguire il comando e dice all'utente come rivederlo. Claude Code non installa mai un plugin con source command come dipendenza di un altro plugin, quindi gli utenti lo installano da soli per primi.705* In una shell non interattiva, come uno script di provisioning, passa `--yes` a `claude plugin install` o `claude plugin update` per accettare il comando che stampa. Per accettare solo il comando che un'esecuzione precedente con `--json` ha visualizzato, passa [`--accept-command`](/docs/it/plugins-reference#plugin-install) con lo `sha256` che l'esecuzione ha segnalato.

698* Se cambi il `command` della voce, o cambi il suo `mode`, gli utenti mantengono la versione che hanno già e Claude Code smette di rieseguire il comando. Nelle sessioni interattive, la scheda `/plugin` Errors mostra il nuovo comando finché l'utente non lo rivede e accetta eseguendo `claude plugin update <plugin>@<marketplace>`.706* Ogni altro percorso esegue solo il comando che l'utente ha già accettato. Questo include gli aggiornamenti avviati da `/plugin` e le esecuzioni in background descritte in [Quando Claude Code riesegue il comando](#when-claude-code-re-runs-the-command). Quando nessuno è stato accettato, Claude Code rifiuta di eseguire il comando e dice all'utente come rivederlo. Claude Code non installa mai un plugin con origine da comando come dipendenza di un altro plugin, quindi gli utenti lo installano da soli per primi.

707* Se cambi la voce `command`, o cambi il suo `mode`, gli utenti mantengono la versione che hanno già e Claude Code smette di rieseguire il comando. Nelle sessioni interattive, la scheda Errori di `/plugin` mostra il nuovo comando fino a quando l'utente non lo rivede e accetta eseguendo `claude plugin update <plugin>@<marketplace>`.

699 708

700Gli amministratori possono bloccare le command sources in tutta un'organizzazione con l'impostazione gestita [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources). Se un'organizzazione imposta [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly), Claude Code blocca le command sources per impostazione predefinita.709Gli amministratori possono bloccare le origini dei comandi in un'organizzazione con l'impostazione gestita [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources). Se un'organizzazione imposta [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly), Claude Code blocca le origini dei comandi per impostazione predefinita.

701 710

702<h4 id="when-claude-code-re-runs-the-command">711<h4 id="when-claude-code-re-runs-the-command">

703 Quando Claude Code riesegue il comando712 Quando Claude Code riesegue il comando

704</h4>713</h4>

705 714

706La directory stampata riflette lo stato dello strumento al momento in cui il comando è stato eseguito, quindi Claude Code esegue il comando di nuovo in questi momenti:715La directory stampata riflette lo stato dello strumento al momento dell'esecuzione del comando, quindi Claude Code esegue il comando di nuovo in questi momenti:

707 716

708* Ogni volta che l'utente installa o aggiorna il plugin717* Ogni volta che l'utente installa o aggiorna il plugin

709* Una volta per sessione per ogni plugin con command source abilitato, in background, poco dopo l'avvio della sessione. Questa esecuzione non passa attraverso l'auto-aggiornamento del marketplace, quindi non dipende dall'[auto-update setting](/docs/it/discover-plugins#configure-auto-updates) del marketplace718* Una volta per sessione per ogni plugin con origine da comando abilitato, in background, poco dopo l'avvio della sessione. Questa esecuzione non passa attraverso l'aggiornamento automatico del marketplace, quindi non dipende dall'[impostazione di aggiornamento automatico](/docs/it/discover-plugins#configure-auto-updates) del marketplace

710* All'avvio o su `/reload-plugins`, quando la versione installata di un plugin abilitato è mancante dalla cache del plugin719* All'avvio o su `/reload-plugins`, quando la versione installata di un plugin abilitato è mancante dalla cache del plugin

711 720

712Claude Code salta le due esecuzioni in background quando l'utente imposta [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/it/env-vars). Gli install e gli aggiornamenti espliciti eseguono comunque il comando con quella variabile impostata.721Claude Code salta le due esecuzioni in background quando l'utente imposta [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/it/env-vars). Gli aggiornamenti e le installazioni espliciti eseguono comunque il comando con quella variabile impostata.

713 722

714Quando l'output sottoposto a hash del comando è cambiato, Claude Code installa il risultato come una nuova versione e lo ricarica nella sessione interattiva in esecuzione, passando [gli stessi componenti che `/reload-plugins` passa](/docs/it/plugins-reference#environment-variables). L'utente vede una notifica che il plugin è stato ricaricato. Se ricaricare al suo posto invaliderebbe la cache del prompt della sessione, Claude Code invece chiede all'utente di eseguire `/reload-plugins`, che [avverte del costo della cache e si applica quando rieseguito con `--force`](/docs/it/prompt-caching#enabling-or-disabling-a-plugin).723Quando l'output sottoposto a hash del comando è cambiato, Claude Code installa il risultato come una nuova versione e lo ricarica nella sessione interattiva in esecuzione, passando [gli stessi componenti che `/reload-plugins` passa](/docs/it/plugins-reference#environment-variables). L'utente vede una notifica che il plugin è stato ricaricato. Se il ricaricamento al suo posto invaliderebbe la cache del prompt della sessione, Claude Code invece chiede all'utente di eseguire `/reload-plugins`, che [avverte del costo della cache e si applica quando rieseguito con `--force`](/docs/it/prompt-caching#enabling-or-disabling-a-plugin).

715 724

716<h3 id="advanced-plugin-entries">725<h3 id="advanced-plugin-entries">

717 Voci di plugin avanzate726 Voci di plugin avanzate

718</h3>727</h3>

719 728

720Questo esempio mostra una voce di plugin che utilizza molti dei campi opzionali, inclusi percorsi personalizzati per comandi, agenti, hooks e server MCP:729Questo esempio mostra una voce di plugin che utilizza molti dei campi facoltativi, inclusi percorsi personalizzati per comandi, agenti, hook e server MCP:

721 730

722```json theme={null}731```json theme={null}

723{732{

726 "source": "github",735 "source": "github",

727 "repo": "company/enterprise-plugin"736 "repo": "company/enterprise-plugin"

728 },737 },

729 "description": "Strumenti di automazione del flusso di lavoro aziendale",738 "description": "Enterprise workflow automation tools",

730 "version": "2.1.0",739 "version": "2.1.0",

731 "author": {740 "author": {

732 "name": "Enterprise Team",741 "name": "Enterprise Team",

766}775}

767```776```

768 777

769Cose importanti da notare:778Cose chiave da notare:

770 779

771* **`commands` e `agents`**: puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin e devono rimanere all'interno di essa.780* **`commands` e `agents`**: puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin e devono rimanere al suo interno.

772 * Claude Code rifiuta un percorso che si risolve al di fuori della directory del plugin, come `./../shared.md`, con un errore [`path escapes plugin directory`](/docs/it/errors#path-escapes-plugin-directory), e carica comunque il plugin senza quel componente781 * Claude Code rifiuta un percorso che si risolve al di fuori della directory del plugin, come `./../shared.md`, con un errore [`path escapes plugin directory`](/docs/it/errors#path-escapes-plugin-directory), e carica comunque il plugin senza quel componente

773* **`${CLAUDE_PLUGIN_ROOT}`**: usa questa variabile nei comandi degli hook e nelle configurazioni del server MCP per fare riferimento ai file all'interno della directory di installazione del plugin.782* **`${CLAUDE_PLUGIN_ROOT}`**: utilizza questa variabile nei comandi hook e nelle configurazioni del server MCP per fare riferimento ai file all'interno della directory di installazione del plugin.

774 * Vedi la [tabella di sostituzione](/docs/it/plugins-reference#environment-variables) per quali campi di configurazione la sostituiscono per tipo di server783 * Vedi la [tabella di sostituzione](/docs/it/plugins-reference#environment-variables) per quali campi di configurazione la sostituiscono per tipo di server

775 * Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti dei plugin, usa [`${CLAUDE_PLUGIN_DATA}`](/docs/it/plugins-reference#persistent-data-directory) invece784 * Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti del plugin, utilizza [`${CLAUDE_PLUGIN_DATA}`](/docs/it/plugins-reference#persistent-data-directory) invece

776* **`strict: false`**: poiché è impostato su false, il plugin non ha bisogno del suo `plugin.json`. La voce del marketplace definisce tutto. Vedi [Strict mode](#strict-mode) di seguito.785* **`strict: false`**: poiché è impostato su false, il plugin non ha bisogno del suo `plugin.json`. La voce del marketplace definisce tutto. Vedi [Modalità strict](#strict-mode) di seguito.

777 786

778Per impostazione predefinita, le skills di un plugin vengono caricate dalla directory `skills/` sotto la sua `source`. I percorsi elencati nel campo `skills` si aggiungono a quella scansione:787Per impostazione predefinita, le skill di un plugin vengono caricate dalla directory `skills/` sotto la sua `source`. I percorsi elencati nel campo `skills` si aggiungono a quella scansione:

779 788

780```json theme={null}789```json theme={null}

781"skills": ["./skills/", "./extra-skills/"]790"skills": ["./skills/", "./extra-skills/"]

782```791```

783 792

784Quando più voci di plugin condividono una cartella `skills/` alla radice del marketplace (`source: "./"`), elenca invece sottodirectory specifiche in modo che ogni voce carichi solo le sue skills:793Quando più voci di plugin condividono una cartella `skills/` alla radice del marketplace (`source: "./"`), elenca invece sottodirectory specifiche in modo che ogni voce carichi solo le sue skill:

785 794

786```json theme={null}795```json theme={null}

787"source": "./",796"source": "./",

788"skills": ["./skills/code-review", "./skills/docs"]797"skills": ["./skills/code-review", "./skills/docs"]

789```798```

790 799

791Con una source della radice del marketplace, i percorsi elencati sono il set completo per quella voce, e altre directory nella cartella `skills/` condivisa non vengono caricate. L'elenco di `./skills/` stesso, o della radice del plugin, mantiene la scansione completa. Se nessuno dei percorsi elencati esiste, viene eseguita la scansione predefinita.800Con un'origine alla radice del marketplace, i percorsi elencati sono l'insieme completo per quella voce, e altre directory nella cartella `skills/` condivisa non si caricano. Elencare `./skills/` stesso, o la radice del plugin, mantiene la scansione completa. Se nessuno dei percorsi elencati esiste, la scansione predefinita viene eseguita invece.

792 801

793<h3 id="strict-mode">802<h3 id="strict-mode">

794 Strict mode803 Modalità strict

795</h3>804</h3>

796 805

797Il campo `strict` controlla se `plugin.json` è l'autorità per le definizioni dei componenti (skills, agenti, hooks, server MCP, stili di output).806Il campo `strict` controlla se `plugin.json` è l'autorità per le definizioni dei componenti (skill, agenti, hook, server MCP, stili di output).

798 807

799| Valore | Comportamento |808| Valore | Comportamento |

800| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |809| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |

801| `true` (predefinito) | `plugin.json` è l'autorità. La voce del marketplace può integrarla con componenti aggiuntivi e entrambe le fonti vengono unite. |810| `true` (predefinito) | `plugin.json` è l'autorità. La voce del marketplace può integrarla con componenti aggiuntivi, e entrambe le fonti vengono unite. |

802| `false` | La voce del marketplace è la definizione completa. Se il plugin ha anche un `plugin.json` che dichiara componenti, è un conflitto e il plugin non riesce a caricarsi. |811| `false` | La voce del marketplace è l'intera definizione. Se il plugin ha anche un `plugin.json` che dichiara componenti, è un conflitto e il plugin non si carica. |

803 812

804**Quando usare ogni modalità:**813**Quando utilizzare ogni modalità:**

805 814

806* **`strict: true`**: il plugin ha il suo `plugin.json` e gestisce i suoi componenti. La voce del marketplace può aggiungere skills o hooks extra in cima. Questo è il predefinito e funziona per la maggior parte dei plugin.815* **`strict: true`**: il plugin ha il suo `plugin.json` e gestisce i suoi componenti. La voce del marketplace può aggiungere skill o hook extra in cima. Questo è il valore predefinito e funziona per la maggior parte dei plugin.

807* **`strict: false`**: l'operatore del marketplace vuole il controllo completo. Il repository del plugin fornisce file grezzi e la voce del marketplace definisce quali di questi file sono esposti come skills, agenti, hooks, ecc. Utile quando il marketplace ristruttura o cura i componenti di un plugin diversamente da quanto previsto dall'autore del plugin.816* **`strict: false`**: l'operatore del marketplace vuole il controllo completo. Il repository del plugin fornisce file grezzi, e la voce del marketplace definisce quali di quei file sono esposti come skill, agenti, hook, ecc. Utile quando il marketplace ristruttura o cura i componenti di un plugin diversamente da quanto inteso dall'autore del plugin.

808 817

809<h2 id="host-and-distribute-marketplaces">818<h2 id="host-and-distribute-marketplaces">

810 Ospita e distribuisci marketplace819 Ospitare e distribuire marketplace

811</h2>820</h2>

812 821

822Quando gli utenti aggiungono un marketplace ospitato in un repository git, o installano un plugin basato su git che elenca, Claude Code clona quel repository del marketplace o del plugin sulla loro macchina. Il clone non scarica mai il contenuto di [Git LFS](https://git-lfs.com), quindi i file tracciati da LFS arrivano come file puntatore. Mantieni i file di cui i tuoi plugin hanno bisogno fuori da LFS.

823

813<h3 id="host-on-github-recommended">824<h3 id="host-on-github-recommended">

814 Ospita su GitHub (consigliato)825 Ospitare su GitHub (consigliato)

815</h3>826</h3>

816 827

817GitHub è il metodo consigliato per ospitare e distribuire un marketplace:828GitHub è il modo consigliato per ospitare e distribuire un marketplace:

818 829

8191. **Crea un repository**: configura un nuovo repository per il tuo marketplace8301. **Creare un repository**: configurare un nuovo repository per il tuo marketplace

8202. **Aggiungi il file marketplace**: crea `.claude-plugin/marketplace.json` con le tue definizioni di plugin8312. **Aggiungere il file marketplace**: creare `.claude-plugin/marketplace.json` con le definizioni dei tuoi plugin

8213. **Condividi con i team**: gli utenti aggiungono il tuo marketplace con `/plugin marketplace add owner/repo`8323. **Condividere con i team**: gli utenti aggiungono il tuo marketplace con `/plugin marketplace add owner/repo`

822 833

823**Vantaggi**: controllo della versione integrato, tracciamento dei problemi e funzionalità di collaborazione del team.834**Vantaggi**: funzionalità integrate di controllo versione, tracciamento dei problemi e collaborazione in team.

824 835

825<h3 id="host-on-other-git-services">836<h3 id="host-on-other-git-services">

826 Ospita su altri servizi git837 Ospitare su altri servizi git

827</h3>838</h3>

828 839

829Qualsiasi servizio di hosting git funziona, come GitLab, Bitbucket e server self-hosted. Gli utenti aggiungono con l'URL completo del repository:840Qualsiasi servizio di hosting git funziona, come GitLab, Bitbucket e server self-hosted. Gli utenti aggiungono con l'URL completo del repository:

836 Repository privati847 Repository privati

837</h3>848</h3>

838 849

839Claude Code supporta l'installazione di plugin da repository privati. Se distribuisci il tuo marketplace tramite [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) invece, le tue credenziali git non sono coinvolte: la sincronizzazione dell'organizzazione legge il repository del marketplace tramite l'app GitHub di Claude o l'app GitHub Enterprise della tua organizzazione, e una fonte di plugin che non può autenticare deve essere pubblica. Vedi [Distribuisci tramite impostazioni dell'organizzazione](#distribute-through-organization-settings) per le regole complete.850Claude Code supporta l'installazione di plugin da repository privati. Se distribuisci il tuo marketplace attraverso [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) invece, le tue credenziali git non sono coinvolte: la sincronizzazione dell'organizzazione legge il repository del marketplace attraverso la connessione GitHub o GitLab della tua organizzazione su claude.ai. Vedi [Distribuire attraverso le impostazioni dell'organizzazione](#distribute-through-organization-settings) per sapere quali fonti di plugin possono essere private.

840 851

841<h4 id="commands-you-run">852<h4 id="commands-you-run">

842 Comandi che esegui853 Comandi che esegui

843</h4>854</h4>

844 855

845Quando esegui `/plugin marketplace add`, `/plugin install`, `/plugin update` o `/plugin marketplace update`, Claude Code utilizza i tuoi helper di credenziali git esistenti, quindi l'accesso HTTPS tramite `gh auth login`, Keychain di macOS o `git-credential-store` funziona come nel tuo terminale. L'accesso SSH funziona finché l'host è già nel tuo file `known_hosts` e la chiave è caricata in `ssh-agent`, poiché Claude Code sopprime i prompt SSH interattivi per l'impronta digitale dell'host e la passphrase della chiave. Gli shorthand `owner/repo` di GitHub clonano per impostazione predefinita su SSH; imposta [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/it/env-vars#variables) per clonare su HTTPS invece.856Quando esegui `/plugin marketplace add`, `/plugin install`, `/plugin update` o `/plugin marketplace update`, Claude Code utilizza i tuoi helper di credenziali git esistenti, quindi l'accesso HTTPS tramite `gh auth login`, Keychain di macOS o `git-credential-store` funziona allo stesso modo del tuo terminale. L'accesso SSH funziona finché l'host è già nel tuo file `known_hosts` e la chiave è caricata in `ssh-agent`, poiché Claude Code sopprime i prompt SSH interattivi per l'impronta digitale dell'host e la passphrase della chiave. La scorciatoia GitHub `owner/repo` clona per impostazione predefinita su SSH; imposta [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/it/env-vars#variables) per clonarli su HTTPS invece.

846 857

847<h4 id="background-auto-updates">858<h4 id="background-auto-updates">

848 Aggiornamenti automatici in background859 Aggiornamenti automatici in background

849</h4>860</h4>

850 861

851Per impostazione predefinita, l'aggiornamento in background disabilita gli helper di credenziali git per il suo `git pull`, quindi il pull non può autenticarsi ai repository privati su HTTPS anche quando un helper è configurato. I remote SSH non sono interessati: una chiave caricata in `ssh-agent` autentica i pull in background allo stesso modo dei comandi che esegui. Quando il pull in background non riesce, Claude Code ricade nel ri-clonare il marketplace da zero. Il ri-clone utilizza le tue credenziali git archiviate, ma può [scadere su repository di grandi dimensioni](#git-operations-time-out), quindi gli aggiornamenti automatici del marketplace privato possono non riuscire intermittentemente.862Per impostazione predefinita, l'aggiornamento in background disabilita gli helper di credenziali git quando controlla il remote del marketplace per i nuovi commit, quindi il controllo non può autenticarsi ai repository privati su HTTPS anche quando un helper è configurato. I remote SSH non sono interessati: una chiave caricata in `ssh-agent` autentica il controllo in background allo stesso modo dei comandi che esegui.

863

864Quando il controllo trova nuovi commit, o fallisce perché non riesce a raggiungere o autenticarsi al remote, Claude Code clona di nuovo il marketplace e scambia il nuovo clone. Se quel clone fallisce, il checkout esistente rimane al suo posto. La re-clonazione utilizza le tue credenziali git memorizzate, ma può [scadere su repository di grandi dimensioni](#git-operations-time-out), quindi gli aggiornamenti automatici del marketplace privato possono fallire intermittentemente.

852 865

853Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:866Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:

854 867

855* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il clone esistente quando il pull in background non riesce, invece di eliminare e ri-clonare. I tuoi plugin continuano a funzionare dallo stato sincronizzato più recente, e gli aggiornamenti manuali con `/plugin marketplace update` continuano a eseguire il pull con le tue credenziali.868* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare la re-clonazione quando il controllo in background non riesce a raggiungere o autenticarsi al remote. I tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione, e gli aggiornamenti manuali con `/plugin marketplace update` continuano a autenticarsi con le tue credenziali.

856* Configura un helper di credenziali git, ad esempio con `gh auth setup-git` per GitHub, in modo che il fallback di ri-clone possa autenticarsi senza richiedere.869* Configura un helper di credenziali git, ad esempio con `gh auth setup-git` per GitHub, in modo che la re-clonazione possa autenticarsi senza richiedere.

857 870

858Impostare un token del provider come `GITHUB_TOKEN` nel tuo ambiente non abilita di per sé l'autenticazione in background. I token hanno effetto solo attraverso un helper di credenziali configurato, ad esempio l'helper della CLI `gh`, che legge `GH_TOKEN` e `GITHUB_TOKEN`.871L'impostazione di un token del provider come `GITHUB_TOKEN` nel tuo ambiente non abilita di per sé l'autenticazione in background. I token hanno effetto solo attraverso un helper di credenziali configurato, ad esempio l'helper della CLI `gh`, che legge `GH_TOKEN` e `GITHUB_TOKEN`.

859 872

860Per fare in modo che il pull in background stesso si autentichi su HTTPS, configura una riscrittura URL git globale. La riscrittura incorpora un token nell'URL remoto, quindi ha effetto anche se il pull in background disabilita gli helper di credenziali, e un pull riuscito salta il fallback di ri-clone. L'esempio seguente riscrive l'URL del repository del marketplace per includere un token di accesso:873Per fare in modo che il controllo in background stesso si autentichi su HTTPS, configura una riscrittura URL git globale. La riscrittura incorpora un token nell'URL remoto, quindi ha effetto anche se il controllo in background disabilita gli helper di credenziali. Quando il controllo trova il checkout aggiornato, Claude Code salta la re-clonazione. L'esempio seguente riscrive l'URL del repository del marketplace per includere un token di accesso:

861 874

862```bash theme={null}875```bash theme={null}

863git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"876git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

865 878

866Limita la riscrittura al repository del marketplace o al percorso dell'organizzazione. Una riscrittura la cui base è solo l'host si applica a ogni fetch e push a quell'host sulla macchina e sostituisce le tue credenziali normali, inclusi i push ai tuoi repository.879Limita la riscrittura al repository del marketplace o al percorso dell'organizzazione. Una riscrittura la cui base è solo l'host si applica a ogni fetch e push a quell'host sulla macchina e sostituisce le tue credenziali normali, inclusi i push ai tuoi repository.

867 880

868Ogni provider si aspetta un nome utente diverso nell'URL riscritto, e lo stesso scoping del percorso si applica a ogni provider. Per server self-hosted, sostituisci il nome host con il nome host del tuo server:881Ogni provider si aspetta un nome utente diverso nell'URL riscritto, e la stessa limitazione del percorso si applica a ogni provider. Per server self-hosted, sostituisci il nome host con il nome host del tuo server:

869 882

870| Provider | Forma URL riscritta |883| Provider | Forma URL riscritto |

871| :-------- | :---------------------------------------------------------------- |884| :-------- | :---------------------------------------------------------------- |

875 888

876La riscrittura archivia il token in testo semplice nel tuo gitconfig, quindi utilizza un token con accesso di sola lettura al repository del marketplace.889La riscrittura memorizza il token in testo semplice nel tuo gitconfig, quindi utilizza un token con accesso in sola lettura al repository del marketplace.

877 890

878<Note>891<Note>

879 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del flusso di lavoro predefinito può accedere solo al repository del flusso di lavoro stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app. Una riscrittura URL globale configurata nella pipeline autentica anche il pull in background direttamente.892 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del workflow predefinito può accedere solo al repository del workflow stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app.

893

894 Se configuri una riscrittura URL globale nella pipeline, la riscrittura autentica anche il controllo in background direttamente.

880</Note>895</Note>

881 896

882<h3 id="distribute-through-organization-settings">897<h3 id="distribute-through-organization-settings">

883 Distribuisci tramite impostazioni dell'organizzazione898 Distribuire attraverso le impostazioni dell'organizzazione

884</h3>899</h3>

885 900

886Se distribuisci plugin tramite [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) su un piano Team o Enterprise, si applicano queste regole di origine:901Se distribuisci plugin attraverso [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) su un piano Team o Enterprise, si applicano queste regole di origine:

887 902

888* Il repository del marketplace deve essere privato o interno. La sincronizzazione dell'organizzazione lo legge tramite l'app GitHub di Claude o l'app GitHub Enterprise della tua organizzazione.903* Su github.com e gitlab.com, il repository del marketplace deve essere privato o interno. La sincronizzazione dell'organizzazione legge il repository attraverso la connessione che corrisponde al suo host:

889* Ogni origine di plugin deve essere di tipo `github`, `url` o `git-subdir`, o un [percorso relativo](#relative-paths) che inizia con `./`. Se elenchi un plugin per nome semplice sotto `metadata.pluginRoot`, la sincronizzazione dell'organizzazione lo rifiuta come origine non supportata, quindi scrivi il percorso, ad esempio `./plugins/deploy-tools`.904 * **github.com**: l'app GitHub di Claude

890* Un'origine di plugin può essere privata in due casi:905 * **Il tuo host GitHub Enterprise Server**: la tua organizzazione [GitHub Enterprise App](/docs/it/github-enterprise-server#admin-setup)

906 * **gitlab.com o la tua istanza GitLab auto-gestita**: il token di accesso nella configurazione [GitLab](#sync-a-gitlab-hosted-marketplace) della tua organizzazione per quell'host

907* Ogni origine di plugin deve essere di tipo `github`, `url` o `git-subdir`, o un [percorso relativo](#relative-paths) che inizia con `./`. Se elenchi un plugin per nome semplice sotto `metadata.pluginRoot`, la sincronizzazione dell'organizzazione lo rifiuta come origine non supportata, quindi scrivi il percorso, come `./plugins/deploy-tools`.

908* Un'origine di plugin può essere privata in tre casi:

891 * Un'origine github.com che condivide il proprietario del repository del marketplace909 * Un'origine github.com che condivide il proprietario del repository del marketplace

892 * Un'origine sull'host GitHub Enterprise della tua organizzazione con l'app GHE installata sul repository910 * Un'origine sull'host GitHub Enterprise della tua organizzazione con l'app GHE installata sul repository

893* La sincronizzazione dell'organizzazione recupera ogni altra origine senza credenziali, quindi i repository github.com sotto un proprietario diverso e i repository su altri host, come GitLab o Bitbucket, devono essere pubblici.911 * Un'origine `url` o `git-subdir` sullo stesso host GitLab del repository del marketplace. Su gitlab.com, l'origine deve anche trovarsi sotto lo stesso spazio dei nomi del gruppo di primo livello o dell'utente del repository del marketplace.

912* Qualsiasi altra origine di plugin deve essere un repository pubblico su github.com, gitlab.com o bitbucket.org, che la sincronizzazione dell'organizzazione recupera senza credenziali. La sincronizzazione dell'organizzazione rifiuta le origini di plugin su host che queste regole non coprono.

894 913

895Vedi [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) per il flusso di lavoro dell'amministratore.914Vedi [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) per il flusso di lavoro dell'amministratore.

896 915

897Per includere plugin privati, posiziona le cartelle dei plugin all'interno del repository del marketplace e fai riferimento ad esse con un [percorso relativo](#relative-paths). La sincronizzazione dell'organizzazione pacchetto ogni plugin durante la distribuzione, quindi gli utenti non hanno mai bisogno di accesso a un repository di origine separato.916Per includere plugin privati, posiziona le cartelle dei plugin all'interno del repository del marketplace e fai riferimento ad esse con un [percorso relativo](#relative-paths). La sincronizzazione dell'organizzazione pacchettizza ogni plugin durante la distribuzione, quindi gli utenti non hanno mai bisogno di accesso a un repository di origine separato.

898 917

899Ad esempio, questa voce di plugin `marketplace.json` fa riferimento a un plugin che hai eseguito il commit a `plugins/deploy-tools` nel repository del marketplace:918Ad esempio, questa voce di plugin `marketplace.json` fa riferimento a un plugin che hai eseguito il commit a `plugins/deploy-tools` nel repository del marketplace:

900 919

905}924}

906```925```

907 926

927<h4 id="sync-a-gitlab-hosted-marketplace">

928 Sincronizzare un marketplace ospitato su GitLab

929</h4>

930

931Per sincronizzare un marketplace da gitlab.com o da un'istanza GitLab auto-gestita, un [Owner](/docs/it/server-managed-settings#access-control) aggiunge prima una configurazione GitLab per quell'host in [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code). Le configurazioni GitLab sono in beta pubblica e si applicano solo alla sincronizzazione del marketplace dei plugin. L'aggiunta di una non rende i repository GitLab disponibili alle [sessioni cloud](/docs/it/claude-code-on-the-web#limitations). Vedi [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) per i passaggi di configurazione.

932

933Quando aggiungi il marketplace, inserisci l'URL HTTPS del progetto, come `https://gitlab.example.com/platform/claude-plugins`. I progetti nei sottogruppi annidati funzionano. La sincronizzazione dell'organizzazione legge il ramo predefinito del progetto. Se attivi **Sync automatically**, solo i push al ramo predefinito avviano una sincronizzazione.

934

908<h4 id="keep-executables-out-of-the-top-level-bin-directory">935<h4 id="keep-executables-out-of-the-top-level-bin-directory">

909 Mantieni gli eseguibili fuori dalla directory bin di livello superiore936 Mantenere gli eseguibili fuori dalla directory bin di primo livello

910</h4>937</h4>

911 938

912Non includere una directory `bin/` di livello superiore in nessun plugin che distribuisci tramite impostazioni dell'organizzazione. claude.ai rifiuta un plugin che ne ha una, indipendentemente dal fatto che il plugin arrivi tramite sincronizzazione del marketplace o caricamento diretto:939Non includere una directory `bin/` di primo livello in nessun plugin che distribuisci attraverso le impostazioni dell'organizzazione. claude.ai rifiuta un plugin che ne ha una, indipendentemente dal fatto che il plugin arrivi tramite sincronizzazione del marketplace o caricamento diretto:

913 940

914* **Sincronizzazione del marketplace**: la sincronizzazione dell'organizzazione rifiuta quel plugin e sincronizza il resto del marketplace. Il messaggio di errore inizia con `Plugin contains a top-level bin/ directory`.941* **Sincronizzazione del marketplace**: la sincronizzazione dell'organizzazione rifiuta quel plugin e sincronizza il resto del marketplace. Il messaggio di errore inizia con `Plugin contains a top-level bin/ directory`.

915* **Caricamento diretto**: se carichi il plugin in [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) invece, claude.ai rifiuta il caricamento con lo stesso messaggio.942* **Caricamento diretto**: se carichi il plugin in [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) invece, claude.ai rifiuta il caricamento con lo stesso messaggio.

916 943

917Mantieni gli eseguibili in un'altra directory, come `scripts/`, e fai riferimento ad essi come `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` dalle tue [skills, hooks, o configurazioni del server MCP](/docs/it/plugins-reference#environment-variables).944Mantieni gli eseguibili in un'altra directory, come `scripts/`, e fai riferimento ad essi come `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` dalle tue [skills, hooks o configurazioni del server MCP](/docs/it/plugins-reference#environment-variables).

918 945

919<h3 id="require-marketplaces-for-your-team">946<h3 id="require-marketplaces-for-your-team">

920 Richiedi marketplace per il tuo team947 Richiedere marketplace per il tuo team

921</h3>948</h3>

922 949

923Puoi configurare il tuo repository in modo che Claude Code aggiunga il tuo marketplace per i membri del team una volta che [fidano della cartella del progetto](/docs/it/permissions#what-runs-before-you-trust-a-folder), senza alcun prompt separato. Aggiungi il tuo marketplace a `.claude/settings.json`:950Puoi configurare il tuo repository in modo che Claude Code aggiunga il tuo marketplace per i membri del team una volta che [fidano della cartella del progetto](/docs/it/permissions#what-runs-before-you-trust-a-folder), senza alcun prompt separato. Aggiungi il tuo marketplace a `.claude/settings.json`:

949Per le opzioni di configurazione complete, vedi [Plugin settings](/docs/it/settings-reference#plugin-settings).976Per le opzioni di configurazione complete, vedi [Plugin settings](/docs/it/settings-reference#plugin-settings).

950 977

951<Note>978<Note>

952 Se usi una fonte locale `directory` o `file` con un percorso relativo, il percorso si risolve rispetto al checkout principale del tuo repository. Quando esegui Claude Code da un git worktree, il percorso punta ancora al checkout principale, quindi tutti i worktree condividono la stessa posizione del marketplace. Lo stato del marketplace viene archiviato una volta per utente in `~/.claude/plugins/known_marketplaces.json`, non per progetto.979 Se utilizzi un'origine locale `directory` o `file` con un percorso relativo, il percorso si risolve rispetto al checkout principale del tuo repository. Quando esegui Claude Code da un git worktree, il percorso punta ancora al checkout principale, quindi tutti i worktree condividono la stessa posizione del marketplace. Lo stato del marketplace è memorizzato una volta per utente in `~/.claude/plugins/known_marketplaces.json`, non per progetto.

953</Note>980</Note>

954 981

955<h3 id="pre-populate-plugins-for-containers">982<h3 id="pre-populate-plugins-for-containers">

956 Pre-popola plugin per i container983 Pre-popolare plugin per i container

957</h3>984</h3>

958 985

959Per le immagini container e gli ambienti CI, puoi pre-popolare una directory di plugin al momento della compilazione in modo che Claude Code si avvii con marketplace e plugin già disponibili, senza clonare nulla al runtime. Imposta la variabile di ambiente `CLAUDE_CODE_PLUGIN_SEED_DIR` per puntare a questa directory.986Per le immagini di container e gli ambienti CI, puoi pre-popolare una directory di plugin al momento della compilazione in modo che Claude Code inizi con marketplace e plugin già disponibili, senza clonare nulla al runtime. Imposta la variabile di ambiente `CLAUDE_CODE_PLUGIN_SEED_DIR` per puntare a questa directory.

960 987

961Per stratificare più directory seed, separa i percorsi con `:` su Unix o `;` su Windows. Claude Code cerca ogni directory in ordine e utilizza il primo seed che contiene un determinato marketplace o cache di plugin.988Per stratificare più directory seed, separa i percorsi con `:` su Unix o `;` su Windows. Claude Code cerca ogni directory in ordine e utilizza il primo seed che contiene un determinato marketplace o cache di plugin.

962 989

980 1007

981Quindi imposta `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed` nell'ambiente di runtime del tuo container in modo che Claude Code legga dal seed all'avvio.1008Quindi imposta `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed` nell'ambiente di runtime del tuo container in modo che Claude Code legga dal seed all'avvio.

982 1009

983All'avvio, Claude Code registra i marketplace trovati nel `known_marketplaces.json` del seed nella configurazione primaria e utilizza le cache dei plugin trovate sotto `cache/` al posto senza ri-clonare. Questo funziona sia in modalità interattiva che in modalità non interattiva con il flag `-p`.1010All'avvio, Claude Code registra i marketplace trovati nel `known_marketplaces.json` del seed nella configurazione primaria e utilizza le cache di plugin trovate sotto `cache/` al loro posto senza re-clonazione. Questo funziona sia in modalità interattiva che in modalità non interattiva con il flag `-p`.

984 1011

985Dettagli del comportamento:1012Dettagli del comportamento:

986 1013

987* **Sola lettura**: la directory seed non viene mai scritta. Gli aggiornamenti automatici sono disabilitati per i marketplace seed poiché git pull fallirebbe su un filesystem di sola lettura.1014* **Sola lettura**: Claude Code non scrive mai nella directory seed.

988* **Le voci seed hanno precedenza**: i marketplace dichiarati nel seed sovrascrivono qualsiasi voce corrispondente nella configurazione dell'utente ad ogni avvio. Per rinunciare a un plugin seed, usa `/plugin disable` piuttosto che rimuovere il marketplace.1015* **Auto-aggiornamenti disabilitati**: i marketplace seed non si auto-aggiornano.

989* **Risoluzione del percorso**: Claude Code individua il contenuto del marketplace sondando `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` al runtime, non fidandosi dei percorsi archiviati all'interno del JSON del seed. Ciò significa che il seed funziona correttamente anche quando montato in un percorso diverso da dove è stato compilato.1016* **Le voci seed hanno la precedenza**: i marketplace dichiarati nel seed sovrascrivono le voci corrispondenti nella configurazione dell'utente ad ogni avvio. Per rinunciare a un plugin seed, utilizza `/plugin disable` piuttosto che rimuovere il marketplace.

990* **La mutazione è bloccata**: l'esecuzione di `/plugin marketplace remove` o `/plugin marketplace update` su un marketplace gestito da seed non riesce con una guida per chiedere al tuo amministratore di aggiornare l'immagine seed.1017* **Risoluzione del percorso**: Claude Code individua il contenuto del marketplace sondando `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` al runtime, non fidandosi dei percorsi memorizzati all'interno del JSON del seed. Ciò significa che il seed funziona correttamente anche quando montato in un percorso diverso da dove è stato compilato.

991* **Compone con le impostazioni**: se `extraKnownMarketplaces` o `enabledPlugins` dichiarano un marketplace che esiste già nel seed, Claude Code utilizza la copia del seed invece di clonare.1018* **La mutazione è bloccata**: l'esecuzione di `/plugin marketplace remove` o `/plugin marketplace update` su un marketplace gestito da seed fallisce con una guida per chiedere al tuo amministratore di aggiornare l'immagine seed.

1019* **Si compone con le impostazioni**: se `extraKnownMarketplaces` o `enabledPlugins` dichiarano un marketplace che esiste già nel seed, Claude Code utilizza la copia del seed invece di clonare.

992 1020

993<h3 id="managed-marketplace-restrictions">1021<h3 id="managed-marketplace-restrictions">

994 Restrizioni del marketplace gestito1022 Restrizioni del marketplace gestito

995</h3>1023</h3>

996 1024

997Per le organizzazioni che richiedono un controllo rigoroso sulle fonti dei plugin, gli amministratori possono limitare quali marketplace di plugin gli utenti possono aggiungere utilizzando l'impostazione [`strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces) nelle impostazioni gestite. Per anche rifiutare i flag CLI che caricano plugin, agenti e server MCP per una singola esecuzione, abbinalo a [`disableSideloadFlags`](/docs/it/settings-reference#disablesideloadflags). Per consentire quali plugin dei marketplace possono apparire come suggerimenti di installazione contestuali, imposta [`pluginSuggestionMarketplaces`](/docs/it/settings-reference#pluginsuggestionmarketplaces).1025Per le organizzazioni che richiedono un controllo rigoroso sulle origini dei plugin, gli amministratori possono limitare quali marketplace di plugin gli utenti possono aggiungere utilizzando l'impostazione [`strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces) nelle impostazioni gestite. Per rifiutare anche i flag CLI che caricano plugin, agenti e server MCP per una singola esecuzione, abbinalo a [`disableSideloadFlags`](/docs/it/settings-reference#disablesideloadflags). Per consentire quali plugin dei marketplace possono apparire come suggerimenti di installazione contestuale, imposta [`pluginSuggestionMarketplaces`](/docs/it/settings-reference#pluginsuggestionmarketplaces).

998 1026

999`strictKnownMarketplaces` corrisponde al marketplace da cui proviene un plugin, non alle voci al suo interno, quindi gli utenti possono ancora installare un plugin con un'[origine `command`](#command-sources) da un marketplace consentito. Per bloccare anche le origini dei comandi, imposta [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources).1027`strictKnownMarketplaces` corrisponde al marketplace da cui proviene un plugin, non alle voci al suo interno, quindi gli utenti possono comunque installare un plugin con un'origine [`command`](#command-sources) da un marketplace consentito. Per bloccare anche le origini dei comandi, imposta [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources).

1000 1028

1001Quando `strictKnownMarketplaces` è configurato nelle impostazioni gestite, il comportamento della restrizione dipende dal valore:1029Quando `strictKnownMarketplaces` è configurato nelle impostazioni gestite, il comportamento della restrizione dipende dal valore:

1002 1030

1003| Valore | Comportamento |1031| Valore | Comportamento |

1004| -------------------------- | --------------------------------------------------------------------------------------------------------------- |1032| -------------------------- | -------------------------------------------------------------------------------------------------- |

1005| Non definito (predefinito) | Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace |1033| Non definito (predefinito) | Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace |

1007| Elenco di fonti | Elenco di autorizzazione applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce |1035| Elenco di origini | Allowlist applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce |

1008 1036

1009<h4 id="common-configurations">1037<h4 id="common-configurations">

1010 Configurazioni comuni1038 Configurazioni comuni

1011</h4>1039</h4>

1012 1040

1013Disabilita tutti gli aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:1041Disabilita tutte le aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:

1014 1042

1015```json theme={null}1043```json theme={null}

1016{1044{

1018}1046}

1019```1047```

1020 1048

1049Claude Code scarica i plugin [sincronizzati da claude.ai](/docs/it/plugins-reference#synced-plugins) dal tuo account piuttosto che da un marketplace, quindi questo blocco non li copre. Per fermare anche quelli, imposta [`syncClaudeAiPlugins`](/docs/it/settings-reference#syncclaudeaiplugins) a `false` nelle impostazioni gestite, o disattiva Skills per la tua organizzazione su claude.ai.

1050

1021Consenti solo il marketplace ufficiale di Anthropic. La corrispondenza per una voce di repository singolo è esatta, quindi questa voce non copre varianti `ref` o `path` dello stesso repository:1051Consenti solo il marketplace ufficiale di Anthropic. La corrispondenza per una voce di repository singolo è esatta, quindi questa voce non copre varianti `ref` o `path` dello stesso repository:

1022 1052

1023```json theme={null}1053```json theme={null}

1036La registrazione automatica non copre ogni macchina. Più comunemente manca:1066La registrazione automatica non copre ogni macchina. Più comunemente manca:

1037 1067

1038* Ambienti non interattivi che vengono eseguiti prima del primo avvio interattivo della macchina.1068* Ambienti non interattivi che vengono eseguiti prima del primo avvio interattivo della macchina.

1039* Macchine dove Claude Code è già stato eseguito in modo interattivo con una policy che ha bloccato il marketplace, come il blocco dell'array vuoto. Claude Code registra il tentativo bloccato e non ritenta dopo il cambio della policy.1069* Macchine in cui Claude Code è già stato eseguito in modo interattivo secondo una politica che ha bloccato il marketplace, come il blocco dell'array vuoto. Claude Code registra il tentativo bloccato e non ritenta dopo il cambio della politica.

1040 1070

1041Su queste macchine, aggiungi il marketplace a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json` in modo che Claude Code lo registri automaticamente, o esegui `claude plugin marketplace add anthropics/claude-plugins-official`.1071Su queste macchine, aggiungi il marketplace a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json` in modo che Claude Code lo registri automaticamente, oppure esegui `claude plugin marketplace add anthropics/claude-plugins-official`.

1042 1072

1043Consenti solo marketplace specifici:1073Consenti solo marketplace specifici:

1044 1074

1101}1131}

1102```1132```

1103 1133

1104Usa `".*"` come `pathPattern` per consentire qualsiasi percorso del filesystem controllando comunque le fonti di rete con `hostPattern`.1134Utilizza `".*"` come `pathPattern` per consentire qualsiasi percorso del filesystem controllando comunque le origini di rete con `hostPattern`.

1105 1135

1106<Note>1136<Note>

1107 `strictKnownMarketplaces` limita ciò che gli utenti possono aggiungere, ma non registra i marketplace di per sé. Per registrare un marketplace consentito per gli utenti automaticamente, aggiungilo a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json`.1137 `strictKnownMarketplaces` limita ciò che gli utenti possono aggiungere, ma non registra i marketplace di per sé. Per registrare un marketplace consentito per gli utenti automaticamente, aggiungilo a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json`.

1108 1138

1109 Il marketplace ufficiale di Anthropic è l'unico che Claude Code registra di per sé, e solo quando l'elenco di autorizzazione lo consente. La registrazione automatica manca anche alcune macchine, come ambienti non interattivi e macchine dove una policy precedente lo ha bloccato. Per coprire quelle macchine, aggiungi il marketplace ufficiale a `extraKnownMarketplaces` anche. Per i due setting affiancati, vedi il [riferimento `strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces).1139 Il marketplace ufficiale di Anthropic è l'unico che Claude Code registra di per sé, e solo quando l'allowlist lo consente. La registrazione automatica manca anche su alcune macchine, come gli ambienti non interattivi e le macchine in cui una politica precedente lo ha bloccato. Per coprire quelle macchine, aggiungi il marketplace ufficiale a `extraKnownMarketplaces` anche. Per i due setting affiancati, vedi il riferimento [`strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces).

1110</Note>1140</Note>

1111 1141

1112<h4 id="how-restrictions-work">1142<h4 id="how-restrictions-work">

1113 Come funzionano le restrizioni1143 Come funzionano le restrizioni

1114</h4>1144</h4>

1115 1145

1116Le restrizioni vengono convalidate prima di qualsiasi operazione di rete o del filesystem. Il controllo viene eseguito all'aggiunta del marketplace e all'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin. Se un marketplace è stato aggiunto prima della configurazione della policy e la sua fonte non corrisponde più all'elenco di autorizzazione, Claude Code rifiuta di installare o aggiornare i plugin da esso. Lo stesso controllo si applica a `blockedMarketplaces`.1146Le restrizioni vengono controllate prima di qualsiasi operazione di rete o filesystem. Il controllo viene eseguito sull'aggiunta del marketplace e sull'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin. Se un marketplace è stato aggiunto prima che la politica fosse configurata e la sua origine non corrisponde più all'allowlist, Claude Code rifiuta di installare o aggiornare plugin da esso. Lo stesso controllo si applica a `blockedMarketplaces`.

1147

1148Per bloccare ogni repository di marketplace sotto un proprietario GitHub, utilizza la forma owner-wildcard in una voce `blockedMarketplaces`: `{ "source": "github", "repo": "untrusted-org/*" }`. Richiede Claude Code v2.1.223 o successivo. Per le regole di corrispondenza, che differiscono tra la blocklist e l'allowlist, vedi [Owner wildcards](/docs/it/settings-reference#owner-wildcards).

1117 1149

1118Per bloccare ogni repository di marketplace sotto un proprietario GitHub, usa la forma owner-wildcard in una voce `blockedMarketplaces`: `{ "source": "github", "repo": "untrusted-org/*" }`. Richiede Claude Code v2.1.223 o successivo. Per le regole di corrispondenza, che differiscono tra la blocklist e l'elenco di autorizzazione, vedi [Owner wildcards](/docs/it/settings-reference#owner-wildcards).1150Quando un utente aggiunge un URL di repository `https://` che Claude Code [clona piuttosto che recupera](/docs/it/discover-plugins#add-from-other-git-hosts), come un URL di repository bare `github.com` o `gitlab.com`, Claude Code lo controlla anche rispetto alle voci `url` in `blockedMarketplaces`. Claude Code blocca l'aggiunta se una voce nomina lo stesso URL. In quel confronto, Claude Code ignora il suffisso `.git` e qualsiasi ref che l'utente aggiunge dopo `#`. Richiede Claude Code v2.1.232 o successivo. Prima di v2.1.232, Claude Code corrispondeva a una voce `url` solo rispetto a un URL che recuperava come file `marketplace.json` ospitato.

1119 1151

1120Quando un utente aggiunge un URL di repository `https://` che Claude Code [clona piuttosto che recupera](/docs/it/discover-plugins#add-from-other-git-hosts), come un URL di repository `github.com` o `gitlab.com` semplice, Claude Code lo controlla anche contro le voci `url` in `blockedMarketplaces`. Claude Code blocca l'aggiunta se una voce nomina lo stesso URL. In quel confronto, Claude Code ignora il suffisso `.git` e qualsiasi ref che l'utente aggiunge dopo `#`. Richiede Claude Code v2.1.232 o successivo. Prima di v2.1.232, Claude Code ha abbinato una voce `url` solo a un URL che ha recuperato come file `marketplace.json` ospitato.1152L'allowlist utilizza la corrispondenza esatta per la maggior parte dei tipi di origine, a parte le voci `github` con owner-wildcard. Affinché un marketplace sia consentito, tutti i campi specificati devono corrispondere:

1121 1153

1122L'elenco di autorizzazione utilizza la corrispondenza esatta per la maggior parte dei tipi di fonte, a parte le voci `github` owner-wildcard. Affinché un marketplace sia consentito, tutti i campi specificati devono corrispondere:1154* Per le origini GitHub: `repo` è obbligatorio, nominando un repository o utilizzando la forma owner-wildcard `owner/*` per coprire ogni repository sotto quel proprietario. Per come le voci wildcard corrispondono, incluso il caso delle regole, vedi [Owner wildcards](/docs/it/settings-reference#owner-wildcards). Per le voci di repository singolo, `ref` deve corrispondere esattamente o essere assente sia dall'origine del marketplace che dalla voce dell'allowlist, e la stessa regola si applica a `path`

1155* Per le origini URL: l'URL completo deve corrispondere esattamente

1156* Per le origini `hostPattern`: l'host del marketplace viene confrontato con il modello regex

1157* Per le origini `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex

1123 1158

1124* Per le fonti GitHub: `repo` è obbligatorio, nominando un repository o usando la forma owner-wildcard `owner/*` per coprire ogni repository sotto quel proprietario. Per come le voci wildcard corrispondono, incluso il caso delle regole, vedi [Owner wildcards](/docs/it/settings-reference#owner-wildcards). Per le voci di repository singolo, `ref` deve corrispondere esattamente o essere assente sia dall'origine del marketplace che dalla voce dell'elenco di autorizzazione, e la stessa regola si applica a `path`1159La corrispondenza esatta dell'allowlist tratta gli URL che differiscono solo per una barra finale, un suffisso `.git` o lo schema `ssh://` e `https://` come valori diversi. Se il marketplace della tua organizzazione può essere clonato da più di una forma di URL, preferisci una voce `hostPattern` rispetto a un URL letterale in modo che i moduli `https://`, `ssh://` e `user@host:path` corrispondano tutti.

1125* Per le fonti URL: l'URL completo deve corrispondere esattamente

1126* Per le fonti `hostPattern`: l'host del marketplace viene confrontato con il modello regex

1127* Per le fonti `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex

1128 1160

1129La corrispondenza esatta dell'elenco di autorizzazione tratta gli URL che differiscono solo per una barra finale, un suffisso `.git` o lo schema `ssh://` e `https://` come valori diversi. Se il marketplace della tua organizzazione può essere clonato da più di una forma di URL, preferisci una voce `hostPattern` rispetto a un URL letterale in modo che le forme `https://`, `ssh://` e `user@host:path` corrispondano tutte.1161Un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) è abbinato per host: una voce `hostPattern` che corrisponde a `claude.ai` lo governa, in `strictKnownMarketplaces` e in `blockedMarketplaces`. Sull'allowlist, tale voce non ammette i caricamenti personali su claude.ai di un membro. Richiede Claude Code v2.1.273 o successivo.

1130 1162

1131Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/docs/it/managed-settings), le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.1163Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/docs/it/managed-settings), i singoli utenti e le configurazioni del progetto non possono ignorare queste restrizioni.

1132 1164

1133Per i dettagli di configurazione completi inclusi tutti i tipi di fonte supportati e il confronto con `extraKnownMarketplaces`, vedi il [riferimento strictKnownMarketplaces](/docs/it/settings-reference#strictknownmarketplaces).1165Per i dettagli di configurazione completi inclusi tutti i tipi di origine supportati e il confronto con `extraKnownMarketplaces`, vedi il riferimento [strictKnownMarketplaces](/docs/it/settings-reference#strictknownmarketplaces).

1134 1166

1135<h3 id="version-resolution-and-release-channels">1167<h3 id="version-resolution-and-release-channels">

1136 Risoluzione della versione e canali di rilascio1168 Risoluzione della versione e canali di rilascio

1137</h3>1169</h3>

1138 1170

1139Le versioni dei plugin determinano i percorsi della cache e il rilevamento degli aggiornamenti: se la versione risolta corrisponde a quella che un utente ha già, `/plugin update` e l'auto-aggiornamento saltano il plugin. Per le fonti basate su git, se ometti `version`, Claude Code utilizza lo SHA del commit risolto della fonte, quindi gli utenti ottengono un aggiornamento ogni volta che quel commit cambia; questa è la configurazione più semplice per i plugin interni o in fase di sviluppo attivo. Vedi [Version management](/docs/it/plugins-reference#version-management) per l'ordine di risoluzione completo, incluse le fonti `archive`.1171Le versioni dei plugin determinano i percorsi della cache e il rilevamento degli aggiornamenti: se la versione risolta corrisponde a quella che un utente ha già, `/plugin update` e l'auto-aggiornamento saltano il plugin. Per le origini basate su git, se ometti `version`, Claude Code utilizza lo SHA del commit risolto della fonte, quindi gli utenti ricevono un aggiornamento ogni volta che quel commit cambia; questa è la configurazione più semplice per i plugin interni o in fase di sviluppo attivo. Vedi [Version management](/docs/it/plugins-reference#version-management) per l'ordine di risoluzione completo, incluse le origini `archive`.

1140 1172

1141<Warning>1173<Warning>

1142 Impostare `version` fissa il plugin per ogni tipo di fonte tranne [`command`](#command-sources), la cui versione include sempre un hash di ciò che il comando ha prodotto. Se dichiari `"version": "1.0.0"` in `plugin.json` e spingi nuovi commit senza cambiare quella stringa, gli utenti esistenti di quelle fonti mantengono la copia in cache, perché Claude Code vede la stessa versione. Aumenta il campo ad ogni rilascio, o omettilo per ricadere sulla versione risolta.1174 L'impostazione di `version` fissa il plugin per ogni tipo di origine tranne [`command`](#command-sources), la cui versione include sempre un hash di ciò che il comando ha prodotto. Un plugin [caricato in posizione](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale non è fissato neanche. Se dichiari `"version": "1.0.0"` in `plugin.json` e fai il push di nuovi commit senza cambiare quella stringa, gli utenti esistenti di quelle origini mantengono la copia memorizzata nella cache, perché Claude Code vede la stessa versione. Aumenta il campo ad ogni rilascio, o omettilo per ricadere nella versione risolta.

1143 1175

1144 Evita di impostare `version` sia in `plugin.json` che nella voce del marketplace. Il valore `plugin.json` vince sempre silenziosamente, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in `marketplace.json`.1176 Evita di impostare `version` sia in `plugin.json` che nella voce del marketplace. Claude Code utilizza sempre il valore `plugin.json` senza avvertimento, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in `marketplace.json`.

1145</Warning>1177</Warning>

1146 1178

1147<h4 id="set-up-release-channels">1179<h4 id="set-up-release-channels">

1148 Configura i canali di rilascio1180 Configurare i canali di rilascio

1149</h4>1181</h4>

1150 1182

1151Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a diversi ref o SHA dello stesso repo. Puoi quindi assegnare ogni gruppo di utenti il suo marketplace tramite impostazioni gestite in uno di due modi:1183Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a ref o SHA diversi dello stesso repository. Puoi quindi dare a ogni gruppo di utenti il suo marketplace attraverso le impostazioni gestite in uno di due modi:

1152 1184

1153* Distribuisci [impostazioni gestite endpoint-managed](/docs/it/managed-settings#delivery-mechanisms) separate, come un file di impostazioni gestite o un profilo MDM, ai dispositivi di ogni gruppo. [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#precedence-within-the-managed-tier) dice se il file per gruppo o il profilo si applica su un dispositivo che ha anche una fonte a livello di organizzazione.1185* Distribuisci [impostazioni gestite endpoint-managed](/docs/it/managed-settings#delivery-mechanisms) separate, come un file di impostazioni gestite o un profilo MDM, ai dispositivi di ogni gruppo. [Come Claude Code combina le origini gestite](/docs/it/managed-settings#precedence-within-the-managed-tier) dice se il file o il profilo per gruppo si applica su un dispositivo che ha anche un'origine a livello di organizzazione.

1154* Definisci una [policy del gateway delle app Claude](/docs/it/claude-apps-gateway-config#managed) per gruppo. Il gateway applica la prima policy la cui regola di corrispondenza si adatta a un utente, quindi ordina le policy in modo che ogni utente raggiunga la policy del suo gruppo. La `extraKnownMarketplaces` di una policy di gruppo sostituisce la mappa della policy catch-all piuttosto che unirsi ad essa, quindi elenca ogni marketplace di cui il gruppo ha bisogno nella policy del gruppo, non solo il suo marketplace di canale.1186* Definisci una [politica del gateway delle app Claude](/docs/it/claude-apps-gateway-config#managed) per gruppo. Il gateway applica la prima politica la cui regola di corrispondenza si adatta a un utente, quindi ordina le politiche in modo che ogni utente raggiunga la politica del suo gruppo. La `extraKnownMarketplaces` di una politica di gruppo sostituisce la mappa della politica catch-all piuttosto che unirsi ad essa, quindi elenca ogni marketplace di cui il gruppo ha bisogno nella politica del gruppo, non solo il suo marketplace del canale.

1155 1187

1156Le impostazioni gestite dal server dalla console di amministrazione [si applicano a ogni utente nella tua organizzazione](/docs/it/server-managed-settings#current-limitations), quindi non possono portare un'assegnazione per gruppo.1188Le impostazioni gestite dal server dalla console di amministrazione [si applicano a ogni utente della tua organizzazione](/docs/it/server-managed-settings#current-limitations), quindi non possono portare un'assegnazione per gruppo.

1157 1189

1158<Warning>1190<Warning>

1159 Ogni canale deve risolversi a una versione diversa. Se usi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref fissato. Se ometti `version`, gli SHA dei commit distinti già distinguono i canali. Se due ref si risolvono alla stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.1191 Ogni canale deve risolversi in una versione diversa. Se utilizzi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref fissato. Se ometti `version`, gli SHA di commit distinti già distinguono i canali. Se due ref si risolvono nella stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.

1160</Warning>1192</Warning>

1161 1193

1162<h5 id="example">1194<h5 id="example">

1196```1228```

1197 1229

1198<h5 id="assign-channels-to-user-groups">1230<h5 id="assign-channels-to-user-groups">

1199 Assegna i canali ai gruppi di utenti1231 Assegnare i canali ai gruppi di utenti

1200</h5>1232</h5>

1201 1233

1202Assegna ogni marketplace al suo gruppo di utenti tramite le impostazioni gestite endpoint-managed per gruppo o la policy del gateway descritte sotto [Configura i canali di rilascio](#set-up-release-channels). Ad esempio, il gruppo stabile riceve:1234Assegna ogni marketplace al suo gruppo di utenti attraverso le impostazioni gestite endpoint-managed per gruppo o la politica del gateway descritte in [Configurare i canali di rilascio](#set-up-release-channels). Ad esempio, il gruppo stabile riceve:

1203 1235

1204```json theme={null}1236```json theme={null}

1205{1237{

1214}1246}

1215```1247```

1216 1248

1217Il gruppo early-access riceve invece `latest-tools`:1249Il gruppo early-access riceve `latest-tools` invece:

1218 1250

1219```json theme={null}1251```json theme={null}

1220{1252{

1230```1262```

1231 1263

1232<h4 id="pin-dependency-versions">1264<h4 id="pin-dependency-versions">

1233 Fissa le versioni delle dipendenze1265 Fissare le versioni delle dipendenze

1234</h4>1266</h4>

1235 1267

1236Un plugin può vincolare le sue dipendenze a un intervallo semver in modo che gli aggiornamenti a una dipendenza non interrompano il plugin dipendente. Vedi [Vincola le versioni delle dipendenze dei plugin](/docs/it/plugin-dependencies) per la convenzione del tag git `{plugin-name}--v{version}`, la sintassi dell'intervallo e come più vincoli sulla stessa dipendenza vengono combinati.1268Un plugin può limitare le sue dipendenze a un intervallo semver in modo che gli aggiornamenti a una dipendenza non rompano il plugin dipendente. Vedi [Constrain plugin dependency versions](/docs/it/plugin-dependencies) per la convenzione del tag git `{plugin-name}--v{version}`, la sintassi dell'intervallo e come più vincoli sulla stessa dipendenza vengono combinati.

1237 1269

1238<h3 id="rename-or-remove-a-plugin">1270<h3 id="rename-or-remove-a-plugin">

1239 Rinomina o rimuovi un plugin1271 Rinominare o rimuovere un plugin

1240</h3>1272</h3>

1241 1273

1242Il `name` di un plugin è il suo identificatore stabile. Gli utenti lo referenziano in `enabledPlugins`, `pluginConfigs` e comandi `/plugin install`, quindi cambiarlo interrompe ogni installazione esistente. Per cambiare l'etichetta mostrata nell'interfaccia utente senza interrompere le installazioni, imposta [`displayName`](#optional-plugin-fields) e mantieni `name` invariato.1274Il `name` di un plugin è il suo identificatore stabile. Gli utenti lo referenziano in `enabledPlugins`, `pluginConfigs` e comandi `/plugin install`, quindi cambiarlo rompe ogni installazione esistente. Per cambiare l'etichetta mostrata nell'interfaccia utente senza rompere le installazioni, imposta [`displayName`](#optional-plugin-fields) e mantieni `name` invariato.

1243 1275

1244Se devi cambiare il `name` di un plugin, o rimuovi un plugin dall'array `plugins`, aggiungi una voce `renames` di livello superiore in modo che gli utenti esistenti migrino invece di vedere un errore `plugin-not-found`. La migrazione automatica richiede Claude Code v2.1.193 o successivo. Mappa ogni nome precedente al suo nome attuale, o a `null` se il plugin non esiste più. L'esempio seguente rinomina `formatter` a `code-formatter` e registra che `legacy-linter` è stato rimosso:1276Se devi cambiare il `name` di un plugin, o rimuovi un plugin dall'array `plugins`, aggiungi una voce `renames` di primo livello in modo che gli utenti esistenti migrino invece di vedere un errore `plugin-not-found`. La migrazione automatica richiede Claude Code v2.1.193 o successivo. Mappa ogni nome precedente al suo nome attuale, o a `null` se il plugin non esiste più. L'esempio seguente rinomina `formatter` a `code-formatter` e registra che `legacy-linter` è stato rimosso:

1245 1277

1246```json theme={null}1278```json theme={null}

1247{1279{

1259 1291

1260Quando un utente avvia Claude Code con il vecchio nome ancora nelle sue impostazioni, Claude Code segue la mappa `renames`:1292Quando un utente avvia Claude Code con il vecchio nome ancora nelle sue impostazioni, Claude Code segue la mappa `renames`:

1261 1293

1262* Se la voce punta a un nuovo nome, Claude Code carica il plugin con il suo nuovo nome e mostra un avviso di una riga come `Renamed to "code-formatter" in the "acme-tools" marketplace`. Quindi riscrive la vecchia chiave alla nuova chiave negli ambiti di impostazioni utente, progetto e locale sia per `enabledPlugins` che per `pluginConfigs`, in modo che l'avviso appaia una volta.1294* Se la voce punta a un nuovo nome, Claude Code carica il plugin con il suo nuovo nome e mostra un avviso di una riga come `Renamed to "code-formatter" in the "acme-tools" marketplace`. Quindi riscrive la vecchia chiave nella nuova chiave negli ambiti di impostazioni utente, progetto e locale sia per `enabledPlugins` che per `pluginConfigs`, quindi l'avviso appare una volta.

1263* Per una voce `null`, Claude Code elimina la vecchia chiave e l'avviso segnala che il plugin è stato rimosso dal marketplace.1295* Per una voce `null`, Claude Code elimina la vecchia chiave e l'avviso segnala che il plugin è stato rimosso dal marketplace.

1264* Se il plugin rinominato utilizza una fonte remota come `github` o `npm`, Claude Code segnala `plugin-cache-miss` dopo il rinomina e l'utente deve eseguire `/plugin install` una volta per recuperarlo con il nuovo nome.1296* Se il plugin rinominato utilizza un'origine remota come `github` o `npm`, Claude Code segnala `plugin-cache-miss` dopo la ridenominazione e l'utente deve eseguire `/plugin install` una volta per recuperarlo con il nuovo nome.

1265 1297

1266Tratta `renames` come una cronologia di sola aggiunta: mantieni le vecchie voci al loro posto anche dopo che ti aspetti che ogni utente abbia migrato. Claude Code segue le catene, quindi se in seguito rinomini `code-formatter` a `formatter-pro`, aggiungi una seconda voce piuttosto che modificare la prima. Un utente che ha ancora l'originale `formatter` abilitato si risolve quindi attraverso entrambe le voci a `formatter-pro`.1298Tratta `renames` come una storia di sola aggiunta: mantieni le vecchie voci al loro posto anche dopo che ti aspetti che ogni utente abbia migrato. Claude Code segue le catene, quindi se in seguito rinomini `code-formatter` a `formatter-pro`, aggiungi una seconda voce piuttosto che modificare la prima. Un utente che ha ancora l'originale `formatter` abilitato si risolve quindi attraverso entrambe le voci a `formatter-pro`.

1267 1299

1268Esegui `claude plugin validate .` dopo aver modificato la mappa; rifiuta qualsiasi voce la cui catena forma un ciclo o non termina a `null` o a un nome elencato in `plugins`.1300Esegui `claude plugin validate .` dopo aver modificato la mappa; rifiuta qualsiasi voce la cui catena forma un ciclo o non termina a `null` o a un nome elencato in `plugins`.

1269 1301

1270<Note>1302<Note>

1271 Le impostazioni gestite e di policy sono di sola lettura per Claude Code, quindi i plugin abilitati lì non possono essere riscritti automaticamente. Il plugin rinominato si carica ancora ogni sessione, ma l'avviso di rinomina ricorre fino a quando un amministratore non aggiorna `enabledPlugins` nel file di impostazioni gestite per usare il nuovo nome. Lo stesso vale per i plugin abilitati attraverso altre fonti di sola lettura come `--add-dir`.1303 Le impostazioni gestite e di politica sono di sola lettura per Claude Code, quindi i plugin abilitati lì non possono essere riscritti automaticamente. Il plugin rinominato continua a caricarsi ad ogni sessione, ma l'avviso di ridenominazione ricorre fino a quando un amministratore non aggiorna `enabledPlugins` nel file di impostazioni gestite per utilizzare il nuovo nome. Lo stesso si applica ai plugin abilitati attraverso altre origini di sola lettura come `--add-dir`.

1272</Note>1304</Note>

1273 1305

1274Le versioni precedenti di Claude Code ignorano il campo `renames` e segnalano `plugin-not-found` per il vecchio nome.1306Le versioni precedenti di Claude Code ignorano il campo `renames` e segnalano `plugin-not-found` per il vecchio nome.

1330**Opzioni:**1362**Opzioni:**

1331 1363

1333| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1365| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1334| `--scope <scope>` | Dove dichiarare il marketplace: `user`, `project` o `local`. Vedi [Plugin installation scopes](/docs/it/plugins-reference#plugin-installation-scopes) | `user` |1366| `--scope <scope>` | Dove dichiarare il marketplace: `user`, `project` o `local`. Vedi [Plugin installation scopes](/docs/it/plugins-reference#plugin-installation-scopes) | `user` |

1368| `--claudeai` | Leggi l'argomento come il nome di un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) invece di una fonte. Richiede Claude Code v2.1.273 o successivo | |

1336 1369

1337Aggiungi un marketplace da GitHub utilizzando la scorciatoia `owner/repo`:1370Aggiungi un marketplace da GitHub utilizzando la scorciatoia `owner/repo`:

1338 1371

1376claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins1409claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1377```1410```

1378 1411

1412Aggiungi un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) dal nome stampato nella sezione `From claude.ai:` di `claude plugin marketplace list`:

1413

1414```bash theme={null}

1415claude plugin marketplace add --claudeai claudeai-organization-library

1416```

1417

1418Con `--claudeai`, il comando rifiuta `--scope` e `--sparse`. Il marketplace è ospitato per il tuo account, non dichiarato in un file di impostazioni, quindi non puoi condividerlo tramite il `.claude/settings.json` di un progetto.

1419

1379<h3 id="plugin-marketplace-list">1420<h3 id="plugin-marketplace-list">

1380 Plugin marketplace list1421 Plugin marketplace list

1381</h3>1422</h3>

1394 1435

1395Con `--json`, ogni voce include `name`, `source`, un campo `installLocation` con il percorso della cache locale dove il marketplace è archiviato, e campi specifici della fonte: `repo` per le fonti GitHub, `url` per le fonti git e URL, e `path` per le fonti locali. Le fonti GitHub e git includono anche un campo `ref` quando il marketplace è stato aggiunto con un branch o tag fissato.1436Con `--json`, ogni voce include `name`, `source`, un campo `installLocation` con il percorso della cache locale dove il marketplace è archiviato, e campi specifici della fonte: `repo` per le fonti GitHub, `url` per le fonti git e URL, e `path` per le fonti locali. Le fonti GitHub e git includono anche un campo `ref` quando il marketplace è stato aggiunto con un branch o tag fissato.

1396 1437

1438Un marketplace [claude.ai](/docs/it/discover-plugins#add-from-claude-ai) aggiunto non ha un clone locale, quindi la sua voce contiene i suoi identificatori claude.ai, `marketplaceId` e `organizationUuid`, al posto di `installLocation`.

1439

1440In sessioni di terminale dove [i plugin si sincronizzano dal tuo account claude.ai](/docs/it/plugins-reference#synced-plugins), l'elenco di testo termina con una sezione `From claude.ai:` che nomina ciò che claude.ai elenca per il tuo account oltre ai marketplace che hai aggiunto. Per aggiungerne uno, vedi [Aggiungi da claude.ai](/docs/it/discover-plugins#add-from-claude-ai). L'output `--json` copre solo i marketplace configurati e lascia fuori quella sezione. Richiede Claude Code v2.1.273 o successivo.

1441

1397<h3 id="plugin-marketplace-remove">1442<h3 id="plugin-marketplace-remove">

1398 Plugin marketplace remove1443 Plugin marketplace remove

1399</h3>1444</h3>

1435Sia `remove` che `update` non riescono quando eseguiti su un marketplace gestito da seed, che è di sola lettura. Quando si aggiornano tutti i marketplace, le voci gestite da seed vengono saltate e gli altri marketplace si aggiornano comunque. Per modificare i plugin forniti da seed, chiedi al tuo amministratore di aggiornare l'immagine seed. Vedi [Pre-popola plugin per i container](#pre-populate-plugins-for-containers).1480Sia `remove` che `update` non riescono quando eseguiti su un marketplace gestito da seed, che è di sola lettura. Quando si aggiornano tutti i marketplace, le voci gestite da seed vengono saltate e gli altri marketplace si aggiornano comunque. Per modificare i plugin forniti da seed, chiedi al tuo amministratore di aggiornare l'immagine seed. Vedi [Pre-popola plugin per i container](#pre-populate-plugins-for-containers).

1436 1481

1437<h2 id="troubleshooting">1482<h2 id="troubleshooting">

1438 Troubleshooting1483 Risoluzione dei problemi

1439</h2>1484</h2>

1440 1485

1441<h3 id="marketplace-not-loading">1486<h3 id="marketplace-not-loading">

1442 Marketplace non carica1487 Marketplace non carica

1443</h3>1488</h3>

1444 1489

1445**Sintomi**: Non riesci ad aggiungere il marketplace o a vedere i plugin da esso1490**Sintomi**: Non è possibile aggiungere il marketplace o visualizzare i plugin da esso

1446 1491

1447**Soluzioni**:1492**Soluzioni**:

1448 1493

1449* Verifica che l'URL del marketplace sia accessibile1494* Verificare che l'URL del marketplace sia accessibile

1450* Controlla che `.claude-plugin/marketplace.json` esista nel percorso specificato1495* Controllare che `.claude-plugin/marketplace.json` esista nel percorso specificato

1451* Assicurati che la sintassi JSON sia valida utilizzando `claude plugin validate .` o `/plugin validate .` dalla directory del marketplace. Per verificare il frontmatter di skill, agente e comando, vedi [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest)1496* Assicurarsi che la sintassi JSON sia valida utilizzando `claude plugin validate .` o `/plugin validate .` dalla directory del marketplace. Per controllare il frontmatter di skill, agent e command, vedere [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest)

1452* Per i repository privati, conferma di avere i permessi di accesso1497* Per i repository privati, confermare di avere i permessi di accesso

1453 1498

1454<h3 id="marketplace-validation-errors">1499<h3 id="marketplace-validation-errors">

1455 Errori di validazione del marketplace1500 Errori di validazione del marketplace

1456</h3>1501</h3>

1457 1502

1458Esegui `claude plugin validate .` o `/plugin validate .` dalla directory del tuo marketplace per verificare i problemi. Quando puntato a una directory del marketplace, il validatore controlla `marketplace.json` per errori di schema, nomi di plugin duplicati e traversal del percorso di origine. Per ogni voce il cui `source` è un percorso locale, valida anche il `plugin.json` di quel plugin e avvisa quando la `version` della voce non corrisponde a quella in `plugin.json`. I problemi trovati nel `plugin.json` di un plugin sono preceduti dall'indice della voce, nella forma `plugins[2] plugin.json →`.1503Eseguire `claude plugin validate .` o `/plugin validate .` dalla directory del marketplace per verificare la presenza di problemi. Quando puntato a una directory del marketplace, il validatore controlla `marketplace.json` per errori di schema, nomi di plugin duplicati e traversal del percorso di origine. Per ogni voce il cui `source` è un percorso locale, valida anche il `plugin.json` di quel plugin e avvisa quando la `version` della voce non corrisponde a quella in `plugin.json`. I problemi trovati nel `plugin.json` di un plugin sono preceduti dall'indice della voce, nella forma `plugins[2] plugin.json →`.

1459 1504

1460A partire da Claude Code v2.1.196, il pass per voce include anche:1505A partire da Claude Code v2.1.196, il pass per voce include anche:

1461 1506

1462* plugin il cui `source` è `.`1507* plugin il cui `source` è `.`

1463* esecuzione quando `marketplace.json` è al di fuori di una directory `.claude-plugin`, risolvendo le origini rispetto alla directory del file stesso1508* viene eseguito quando `marketplace.json` è al di fuori di una directory `.claude-plugin`, risolvendo le origini rispetto alla directory del file stesso

1464* segnalazione dei problemi di ogni voce anche quando un'altra parte del file ha errori di schema1509* segnala i problemi di ogni voce anche quando un'altra parte del file ha errori di schema

1465 1510

1466Le versioni precedenti saltano i plugin alla radice del marketplace e scendono solo da un `.claude-plugin/marketplace.json`.1511Le versioni precedenti saltano i plugin nella radice del marketplace e scendono solo da `.claude-plugin/marketplace.json`.

1467 1512

1468Dalla directory di un marketplace, Claude Code non apre i file di skill, agente, comando o hook dei plugin. Per trovare errori in questi file, vedi [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest). La tabella seguente elenca gli errori più comuni da una directory del marketplace, con la causa e la soluzione per ciascuno:1513Da una directory del marketplace, Claude Code non apre i file skill, agent, command o hook dei plugin. Per trovare errori in questi file, vedere [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest). La tabella seguente elenca gli errori più comuni da una directory del marketplace, con la causa e la soluzione per ciascuno:

1469 1514

1471| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1516| :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1472| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory che hai denominato non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file di skill, agente o comando da verificare | Esegui dalla radice del marketplace, o crea `.claude-plugin/marketplace.json` con i campi obbligatori |1517| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory denominata non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file skill, agent o command da controllare | Eseguire dalla radice del marketplace, o creare `.claude-plugin/marketplace.json` con i campi obbligatori |

1473| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controlla le virgole mancanti, le virgole extra o le stringhe non quotate |1518| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controllare la presenza di virgole mancanti, virgole extra o stringhe non quotate |

1475| `plugins[0].source: Path contains ".."` | Il percorso di origine contiene `..` | Usa percorsi relativi alla radice del marketplace senza `..`. Vedi [Relative paths](#relative-paths) |1520| `plugins[0].source: Path contains ".."` | Un segmento del percorso di origine è `..` | Utilizzare percorsi relativi alla radice del marketplace senza segmenti `..`. Vedere [Relative paths](#relative-paths) |

1476| `Marketplace name cannot contain control or bidirectional-formatting characters` | Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |1521| `Marketplace name cannot contain control or bidirectional-formatting characters` | Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una nuova riga | Rimuovere il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |

1477| `Plugin name cannot contain control or bidirectional-formatting characters` | Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |1522| `Plugin name cannot contain control or bidirectional-formatting characters` | Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una nuova riga | Rimuovere il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |

1478 1523

1479**Avvisi** (non bloccanti):1524**Avvisi** (non bloccanti):

1480 1525

1481* `Marketplace has no plugins defined`: aggiungi almeno un plugin all'array `plugins`1526* `Marketplace has no plugins defined`: aggiungere almeno un plugin all'array `plugins`

1482* `No marketplace description provided`: aggiungi una `description` di livello superiore per aiutare gli utenti a comprendere il tuo marketplace1527* `No marketplace description provided`: aggiungere una `description` di livello superiore per aiutare gli utenti a comprendere il marketplace

1483* `Plugin name "x" is not kebab-case`: rinomina in lettere minuscole, cifre e trattini solo (ad esempio, `my-plugin`). Claude Code accetta altre forme, ma la sincronizzazione del marketplace claude.ai le rifiuta.1528* `Plugin name "x" is not kebab-case`: rinominare utilizzando solo lettere minuscole, cifre e trattini (ad esempio, `my-plugin`). Claude Code accetta altre forme, ma la sincronizzazione del marketplace claude.ai le rifiuta.

1484* `Marketplace name "x" is reserved in Claude Desktop`: il marketplace è denominato `org`, `org-provisioned`, o `unknown`, in qualsiasi maiuscola. Claude Code accetta questi nomi, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta l'intero marketplace. Rinomina il marketplace. Prima della v2.1.221, `claude plugin validate` non eseguiva questo controllo.1529* `Marketplace name "x" is reserved in Claude Desktop`: il marketplace è denominato `org`, `org-provisioned` o `unknown`, in qualsiasi maiuscola. Claude Code accetta questi nomi, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta l'intero marketplace. Rinominare il marketplace. Prima della v2.1.221, `claude plugin validate` non eseguiva questo controllo.

1485* `Marketplace name "x" is not accepted by Claude Desktop` o `Plugin name "x" is not accepted by Claude Desktop`: Claude Desktop accetta nomi di fino a 128 caratteri composti da lettere, cifre, `.`, `_`, e `-`, che iniziano con una lettera o una cifra. Claude Code accetta altre forme, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta un marketplace il cui nome non supera il controllo e scarta silenziosamente una voce di plugin il cui nome non lo fa. Rinomina il marketplace o il plugin. Prima della v2.1.221, `claude plugin validate` non eseguiva questi controlli.1530* `Marketplace name "x" is not accepted by Claude Desktop` o `Plugin name "x" is not accepted by Claude Desktop`: Claude Desktop accetta nomi di lunghezza fino a 128 caratteri composti da lettere, cifre, `.`, `_` e `-`, che iniziano con una lettera o una cifra. Claude Code accetta altre forme, ma la sincronizzazione del marketplace gestito di Claude Desktop rifiuta un marketplace il cui nome non supera il controllo e scarta silenziosamente una voce di plugin il cui nome non lo fa. Rinominare il marketplace o il plugin. Prima della v2.1.221, `claude plugin validate` non eseguiva questi controlli.

1486 1531

1487<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">1532<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1488 Validate a plugin or a directory without a manifest1533 Validate a plugin or a directory without a manifest

1489</h4>1534</h4>

1490 1535

1491Per trovare file di skill, agente e comando il cui frontmatter non viene analizzato, esegui `claude plugin validate` e denomina la directory che li contiene. Claude Code non guarda al di fuori della directory che denomini. Ogni esecuzione tranne una su un plugin che ha un `plugin.json` richiede Claude Code v2.1.233 o successivo.1536Per trovare file skill, agent e command il cui frontmatter non viene analizzato, eseguire `claude plugin validate` e denominare la directory che li contiene. Claude Code non guarda al di fuori della directory denominata. Ogni esecuzione tranne una rispetto a un plugin che ha un `plugin.json` richiede Claude Code v2.1.233 o successivo.

1492 1537

1493<h5 id="pick-the-directory-to-name">1538<h5 id="pick-the-directory-to-name">

1494 Pick the directory to name1539 Scegliere la directory da denominare

1495</h5>1540</h5>

1496 1541

1497Claude Code controlla file diversi a seconda di quale directory denomini. Trova quello che vuoi verificare nella prima colonna ed esegui il comando di quella riga:1542Claude Code controlla file diversi a seconda di quale directory denominate. Trovare ciò che si desidera controllare nella prima colonna ed eseguire il comando di quella riga:

1498 1543

1500| :------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1545| :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1501| Un plugin che ha un `plugin.json` | `claude plugin validate ./plugins/my-plugin` | `plugin.json`, `hooks/hooks.json`, e le directory `skills`, `agents`, e `commands` alla radice del plugin |1546| Un plugin che ha un `plugin.json` | `claude plugin validate ./plugins/my-plugin` | `plugin.json`, `hooks/hooks.json` e le directory `skills`, `agents` e `commands` nella radice del plugin |

1502| Una directory di skill, agenti o comandi, come un plugin che non ha ancora un `plugin.json` | `claude plugin validate .claude/skills`, `~/.claude/agents`, o `./my-plugin/agents` | Ogni file di skill, agente o comando in quella directory |1547| Una directory di skill, agent o command, come un plugin che non ha ancora un `plugin.json` | `claude plugin validate .claude/skills`, `~/.claude/agents` o `./my-plugin/agents` | Ogni file skill, agent o command in quella directory |

1503| Una cartella il cui skill è il suo `SKILL.md` radice | `claude plugin validate ./skills`, denominando la directory `skills` che contiene la cartella | Il `SKILL.md` radice di ogni cartella. La directory contenente deve essere denominata `skills`; una cartella sotto un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice |1548| Una cartella il cui skill è il suo `SKILL.md` radice | `claude plugin validate ./skills`, denominando la directory `skills` che contiene la cartella | Il `SKILL.md` radice di ogni cartella. La directory contenente deve essere denominata `skills`; una cartella con un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice |

1504| Le tre directory di un progetto contemporaneamente | `claude plugin validate .claude`, o la radice del progetto quando non ha un manifest `.claude-plugin/` | `.claude/skills`, `.claude/agents`, e `.claude/commands` |1549| Le tre directory di un progetto contemporaneamente | `claude plugin validate .claude`, o la radice del progetto quando non ha un manifest `.claude-plugin/` | `.claude/skills`, `.claude/agents` e `.claude/commands` |

1506 1551

1507<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">1552<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

1508 Check a plugin whose skill is its root `SKILL.md`1553 Controllare un plugin il cui skill è il suo `SKILL.md` radice

1509</h5>1554</h5>

1510 1555

1511Quando esegui `claude plugin validate` su una directory di plugin, Claude Code non controlla un `SKILL.md` alla radice del plugin. Quando il plugin si trova in una directory denominata `skills`, esegui il comando due volte:1556Quando si esegue `claude plugin validate` rispetto a una directory di plugin, Claude Code non controlla un `SKILL.md` nella radice del plugin. Quando il plugin si trova in una directory denominata `skills`, eseguire il comando due volte:

1512 1557

1513* Denomina quella directory `skills` per verificare il `SKILL.md` radice del plugin.1558* Denominare quella directory `skills` per controllare il `SKILL.md` radice del plugin.

1514* Denomina la directory del plugin per verificare il resto.1559* Denominare la directory del plugin per controllare il resto.

1515 1560

1516Quando il plugin si trova sotto un altro nome, come `plugins/`, l'esecuzione della directory `skills` non è disponibile, e nessuna esecuzione controlla il suo `SKILL.md` radice.1561Quando il plugin si trova con un altro nome, come `plugins/`, l'esecuzione della directory skills non è disponibile e nessuna esecuzione controlla il suo `SKILL.md` radice.

1517 1562

1518<h5 id="check-files-behind-symlinks">1563<h5 id="check-files-behind-symlinks">

1519 Check files behind symlinks1564 Controllare file dietro symlink

1520</h5>1565</h5>

1521 1566

1522Quando esegui `claude plugin validate`, Claude Code non segue i symlink all'interno della directory che denomini. Quello che fa dipende da dove si trova il link:1567Quando si esegue `claude plugin validate`, Claude Code non segue i symlink all'interno della directory denominata. Ciò che fa dipende da dove si trova il collegamento:

1523 1568

1524* **Una directory `skills`, `agents`, o `commands` collegata sotto la radice del plugin o `.claude`**: Claude Code avverte che nulla in essa è stato letto.1569* **Una directory `skills`, `agents` o `commands` collegata sotto la radice del plugin o `.claude`**: Claude Code avverte che nulla in essa è stato letto.

1525* **Una voce collegata all'interno di una directory `skills`, `agents`, o `commands`**: Claude Code la salta e avvisa, per directory, quante voci ha saltato che una sessione caricherà.1570* **Una voce collegata all'interno di una directory `skills`, `agents` o `commands`**: Claude Code la salta e avvisa, per directory, quante voci ha saltato che una sessione caricherà.

1526* **La directory `skills`, `agents`, o `commands` che denomini è essa stessa un symlink, o la sua directory padre `.claude` è**: Claude Code segnala un errore e non controlla nulla in essa. Denomina invece la directory reale.1571* **La directory `skills`, `agents` o `commands` denominata è essa stessa un symlink, o la sua directory padre `.claude` è**: Claude Code segnala un errore e non controlla nulla in essa. Denominare invece la directory reale.

1527 1572

1528In due casi di skill, l'esecuzione passa con avvisi. Per verificare i file collegati, esegui di nuovo e denomina una directory che li contiene direttamente:1573In due casi di skill, l'esecuzione passa con avvisi. Per controllare i file collegati, eseguire di nuovo e denominare una directory che li contiene direttamente:

1529 1574

1530* **Un plugin il cui directory `skills` [collega a una directory skills di un plugin fratello](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks)**: denomina la directory del plugin fratello.1575* **Un plugin il cui directory `skills` [si collega a una directory skills di un plugin sibling](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks)**: denominare la directory del plugin sibling.

1531* **Una [voce di skill collegata](/docs/it/skills#where-skills-live) in `~/.claude/skills` o `.claude/skills`**: Claude Code segue la voce in una sessione. Per verificarla, denomina una directory chiamata `skills` che contiene la cartella reale.1576* **Una [voce skill collegata](/docs/it/skills#where-skills-live) in `~/.claude/skills` o `.claude/skills`**: Claude Code segue la voce in una sessione. Per controllarla, denominare una directory chiamata `skills` che contiene la cartella reale.

1532 1577

1533<h5 id="read-the-validation-results">1578<h5 id="read-the-validation-results">

1534 Read the validation results1579 Leggere i risultati della validazione

1535</h5>1580</h5>

1536 1581

1537Un'esecuzione pulita termina con `Validation passed`.1582Un'esecuzione pulita termina con `Validation passed`.

1538 1583

1539`No manifest found in directory` significa che Claude Code non ha trovato `plugin.json` o `marketplace.json` lì, e nessun file di skill, agente o comando nelle directory che sonda sotto di essa. Denomina invece la directory `skills`, `agents`, o `commands` che contiene i tuoi file.1584`No manifest found in directory` significa che Claude Code non ha trovato `plugin.json` o `marketplace.json` lì, e nessun file skill, agent o command nelle directory che sonda sotto di essa. Denominare invece la directory `skills`, `agents` o `commands` che contiene i file.

1540 1585

1541Due degli errori che Claude Code segnala da queste esecuzioni, con la soluzione per ciascuno:1586Due degli errori che Claude Code segnala da queste esecuzioni, con la soluzione per ciascuno:

1542 1587

1543* `YAML frontmatter failed to parse: ...`: correggi lo YAML nel blocco frontmatter del file di skill, agente o comando. Finché non lo fai, una sessione non legge alcun campo frontmatter dal file1588* `YAML frontmatter failed to parse: ...`: correggere lo YAML nel blocco frontmatter del file skill, agent o command. Fino a quando non lo farete, una sessione non legge alcun campo frontmatter dal file

1544* `Invalid JSON syntax: ...` su `hooks/hooks.json`: correggi la sintassi JSON. Finché non lo fai, una sessione carica il plugin senza gli hook in quel file. Claude Code segnala questo errore solo in un'esecuzione di plugin1589* `Invalid JSON syntax: ...` su `hooks/hooks.json`: correggere la sintassi JSON. Fino a quando non lo farete, una sessione carica il plugin senza gli hook in quel file. Claude Code segnala questo errore solo in un'esecuzione di plugin

1545 1590

1546In un'esecuzione di plugin, Claude Code avverte anche di un `CLAUDE.md` alla radice del plugin. Per i percorsi che imposti attraverso i [component path fields](/docs/it/plugins-reference#component-path-fields) in `plugin.json`, Claude Code controlla che ogni percorso esista ma non legge i file lì.1591In un'esecuzione di plugin, Claude Code avverte anche di un `CLAUDE.md` nella radice del plugin. Per i percorsi impostati tramite i [component path fields](/docs/it/plugins-reference#component-path-fields) in `plugin.json`, Claude Code controlla che ogni percorso esista ma non legge i file lì.

1547 1592

1548<h3 id="plugin-installation-failures">1593<h3 id="plugin-installation-failures">

1549 Errori di installazione del plugin1594 Errori di installazione del plugin

1553 1598

1554**Soluzioni**:1599**Soluzioni**:

1555 1600

1556* Verifica che gli URL di origine del plugin siano accessibili1601* Verificare che gli URL di origine del plugin siano accessibili

1557* Controlla che le directory dei plugin contengano i file richiesti1602* Controllare che le directory dei plugin contengano i file obbligatori

1558* Per le origini GitHub, assicurati che i repository siano pubblici o che tu abbia accesso1603* Per le origini GitHub, assicurarsi che i repository siano pubblici o che si abbia accesso

1559* Testa manualmente le origini dei plugin clonando/scaricando1604* Testare manualmente le origini dei plugin clonando/scaricando

1560* Se l'origine fissa sia `ref` che `sha`, un ramo o un tag upstream eliminato non blocca l'installazione sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket. Su server che non supportano il recupero dei commit per SHA, come AWS CodeCommit, il `ref` deve ancora esistere e il commit fissato deve essere raggiungibile da esso. Se l'installazione continua a non riuscire, conferma che il commit fissato esiste ancora nel repository1605* Se l'origine fissa sia `ref` che `sha`, un ramo o un tag upstream eliminato non blocca l'installazione sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket. Su server che non supportano il recupero di commit per SHA, come AWS CodeCommit, il `ref` deve ancora esistere e il commit bloccato deve essere raggiungibile da esso. Se l'installazione continua a non riuscire, confermare che il commit bloccato esiste ancora nel repository

1561 1606

1562<h3 id="private-repository-authentication-fails">1607<h3 id="private-repository-authentication-fails">

1563 L'autenticazione del repository privato non riesce1608 L'autenticazione del repository privato non riesce

1569 1614

1570Per l'installazione manuale e gli aggiornamenti:1615Per l'installazione manuale e gli aggiornamenti:

1571 1616

1572* Verifica di essere autenticato con il tuo provider git (ad esempio, esegui `gh auth status` per GitHub)1617* Verificare di essere autenticati con il provider git (ad esempio, eseguire `gh auth status` per GitHub)

1573* Controlla che il tuo helper di credenziali sia configurato: `git config --global credential.helper`1618* Controllare che il helper delle credenziali sia configurato: `git config --global credential.helper`

1574* Esegui `git ls-remote <marketplace-url>` per verificare se git può autenticarsi da solo. Se git chiede un nome utente o una password, archivia prima la credenziale: per GitHub su HTTPS, esegui `gh auth setup-git`, e per i remote SSH, carica la tua chiave in `ssh-agent`1619* Eseguire `git ls-remote <marketplace-url>` per verificare se git può autenticarsi da solo. Se git chiede un nome utente o una password, archiviare prima la credenziale: per GitHub su HTTPS, eseguire `gh auth setup-git`, e per i remote SSH, caricare la chiave in `ssh-agent`

1575 1620

1576Per gli aggiornamenti automatici in background:1621Per gli aggiornamenti automatici in background:

1577 1622

1578* Per impostazione predefinita, gli aggiornamenti in background disabilitano gli helper di credenziali git per il pull, quindi il pull non può autenticarsi su HTTPS. I remote SSH con una chiave caricata in `ssh-agent` si autenticano ancora. Un pull non riuscito attiva una ri-clonazione da zero, che utilizza le tue credenziali archiviate ma potrebbe scadere su repository di grandi dimensioni1623* Per impostazione predefinita, gli aggiornamenti in background disabilitano gli helper delle credenziali git quando controllano il remote per nuovi commit, quindi il controllo non può autenticarsi su HTTPS. I remote SSH con una chiave caricata in `ssh-agent` si autenticano ancora

1579* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il clone esistente quando il pull in background non riesce1624* Quando il controllo non può autenticarsi, Claude Code ri-clona il marketplace con le credenziali archiviate, ma il ri-clone potrebbe scadere su repository di grandi dimensioni

1580* Configura un helper di credenziali git, ad esempio `gh auth setup-git`, in modo che il fallback di ri-clonazione possa autenticarsi1625* Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il clone esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote

1581* Se la ri-clonazione scade su un repository di grandi dimensioni, aumenta il limite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)1626* Configurare un helper delle credenziali git, ad esempio `gh auth setup-git`, in modo che il ri-clone possa autenticarsi

1582* Configura una [riscrittura dell'URL git](#private-repositories) limitata al repository del marketplace in modo che il pull in background si autentichi direttamente1627* Se il re-clone scade su un repository di grandi dimensioni, aumentare il limite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)

1583* Oppure aggiorna i marketplace privati manualmente con `/plugin marketplace update <name>`, che utilizza le tue credenziali1628* Configurare una [riscrittura dell'URL git](#private-repositories) limitata al repository del marketplace in modo che il controllo in background si autentichi direttamente

1629* Oppure aggiornare i marketplace privati manualmente con `/plugin marketplace update <name>`, che utilizza le credenziali

1584 1630

1585<h3 id="marketplace-updates-fail-in-offline-environments">1631<h3 id="marketplace-updates-fail-in-offline-environments">

1586 Gli aggiornamenti del marketplace non riescono in ambienti offline1632 Gli aggiornamenti del marketplace non riescono in ambienti offline

1587</h3>1633</h3>

1588 1634

1589**Sintomi**: Il `git pull` del marketplace non riesce in background e Claude Code tenta ripetutamente una ri-clonazione che non può avere successo.1635**Sintomi**: In un ambiente offline o airgapped, l'aggiornamento in background del marketplace non riesce a raggiungere il remote e Claude Code tenta ripetutamente un ri-clone che non può avere successo.

1636

1637**Causa**: L'aggiornamento in background controlla il remote del marketplace per nuovi commit, e quando il controllo non riesce a raggiungere il remote, Claude Code tenta di clonare di nuovo il marketplace. Offline, il clone non riesce allo stesso modo e il clone esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva `git pull` nel clone esistente, spostava il clone da parte per ri-clonare quando il pull non riusciva, e lo ripristinava in seguito su base best-effort.

1590 1638

1591**Causa**: Per impostazione predefinita, quando un `git pull` non riesce, Claude Code tenta una ri-clonazione da zero. In ambienti offline o airgapped, la ri-clonazione non riesce allo stesso modo, e il ripristino della cache precedente successivamente è best-effort. L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio, ma ogni sessione ripete i tentativi non riusciti e ogni operazione git può attendere il [timeout di 120 secondi](#git-operations-time-out).1639L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio. Ogni sessione ripete comunque il tentativo non riuscito, e ogni operazione git può attendere il [timeout di 120 secondi](#git-operations-time-out).

1592 1640

1593**Soluzione**: Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per saltare il tentativo di ri-clonazione e continuare a utilizzare la cache esistente quando il pull non riesce:1641**Soluzione**: Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per saltare il tentativo di ri-clone e continuare a utilizzare il clone esistente quando il controllo non riesce a raggiungere il remote:

1594 1642

1595```bash theme={null}1643```bash theme={null}

1596export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11644export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1597```1645```

1598 1646

1599Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizza [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) per pre-popolare la directory dei plugin al momento della compilazione.1647Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizzare [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) per pre-popolare la directory dei plugin al momento della compilazione.

1600 1648

1601<h3 id="git-operations-time-out">1649<h3 id="git-operations-time-out">

1602 Le operazioni Git scadono1650 Le operazioni Git scadono

1603</h3>1651</h3>

1604 1652

1605**Sintomi**: L'installazione del plugin o gli aggiornamenti del marketplace non riescono con un errore di timeout come "Git clone timed out after 120s" o "Git pull timed out after 120s".1653**Sintomi**: L'installazione del plugin o gli aggiornamenti del marketplace non riescono con un errore di timeout come `Git clone timed out after 120s`.

1606 1654

1607**Causa**: Claude Code utilizza un timeout di 120 secondi per tutte le operazioni git, inclusa la clonazione dei repository dei plugin e il pull degli aggiornamenti del marketplace. I repository di grandi dimensioni o le connessioni di rete lente possono superare questo limite.1655**Causa**: Claude Code utilizza un timeout di 120 secondi per tutte le operazioni git, inclusa la clonazione di repository di plugin e il ri-clone di un marketplace per aggiornarlo. I repository di grandi dimensioni o le connessioni di rete lente potrebbero superare questo limite.

1608 1656

1609**Soluzione**: Aumenta il timeout utilizzando la variabile di ambiente `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. Il valore è in millisecondi:1657**Soluzione**: Aumentare il timeout utilizzando la variabile di ambiente `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. Il valore è in millisecondi:

1610 1658

1611```bash theme={null}1659```bash theme={null}

1612export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minuti1660export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutes

1613```1661```

1614 1662

1615<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">1663<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">

1616 I plugin con percorsi relativi non riescono nei marketplace basati su URL1664 I plugin con percorsi relativi non riescono nei marketplace basati su URL

1617</h3>1665</h3>

1618 1666

1619**Sintomi**: Hai aggiunto un marketplace tramite URL (come `https://example.com/marketplace.json`), ma i plugin con origini di percorso relativo come `"./plugins/my-plugin"` non riescono a installare con `its marketplace entry path does not stay inside the marketplace directory`. I plugin già installati non riescono a caricare con `Plugin source path refused`. Entrambi i messaggi hanno una [voce di riferimento errore](/docs/it/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).1667**Sintomi**: È stato aggiunto un marketplace tramite un URL come `https://example.com/marketplace.json`, ma i plugin con origini di percorso relativo come `"./plugins/my-plugin"` non riescono a installarsi con `its marketplace entry path does not stay inside the marketplace directory`. I plugin già installati non riescono a caricarsi con `Plugin source path refused`. Entrambi i messaggi hanno una [voce di riferimento dell'errore](/docs/it/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).

1620 1668

1621**Causa**: L'aggiunta di un marketplace basato su URL scarica solo il file `marketplace.json` stesso, e Claude Code non recupera i file dei plugin per percorso relativo da quel server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.1669**Causa**: l'aggiunta di un marketplace basato su URL scarica solo il file `marketplace.json` stesso, e Claude Code non recupera i file dei plugin per percorso relativo da quel server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.

1622 1670

1623**Soluzioni**:1671**Soluzioni**:

1624 1672

1625* **Usa origini esterne**: cambia le voci dei plugin per usare qualsiasi [plugin source](#plugin-sources) diverso da un percorso relativo:1673* **Utilizzare origini esterne**: modificare le voci dei plugin in qualsiasi [plugin source](#plugin-sources) diverso da un percorso relativo:

1626 ```json theme={null}1674 ```json theme={null}

1627 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }1675 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

1628 ```1676 ```

1629* **Usa un marketplace basato su Git**: Ospita il tuo marketplace in un repository Git e aggiungilo con l'URL git. I marketplace basati su Git clonano l'intero repository, rendendo i percorsi relativi funzionanti correttamente.1677* **Utilizzare un marketplace basato su Git**: ospitare il marketplace in un repository Git e aggiungerlo con l'URL git. I marketplace basati su Git clonano l'intero repository, rendendo i percorsi relativi funzionanti correttamente.

1630 1678

1631<h3 id="files-not-found-after-installation">1679<h3 id="files-not-found-after-installation">

1632 File non trovati dopo l'installazione1680 File non trovati dopo l'installazione

1634 1682

1635**Sintomi**: Il plugin si installa ma i riferimenti ai file non riescono, specialmente i file al di fuori della directory del plugin1683**Sintomi**: Il plugin si installa ma i riferimenti ai file non riescono, specialmente i file al di fuori della directory del plugin

1636 1684

1637**Causa**: I plugin vengono copiati in una directory cache piuttosto che utilizzati in-place, tranne per una [`command` source in link mode](#copy-mode-and-link-mode). I percorsi che fanno riferimento a file al di fuori della directory del plugin copiato (come `../shared-utils`) non funzioneranno perché quei file non vengono copiati.1685**Causa**: Claude Code copia i plugin installati in una directory cache, a meno che il plugin non si carichi in place. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica in place, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. I percorsi che fanno riferimento a file al di fuori della directory di un plugin copiato (come `../shared-utils`) non funzioneranno perché questi file non vengono copiati.

1638 1686

1639**Soluzioni**: Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per le soluzioni alternative inclusi symlink e ristrutturazione delle directory.1687**Soluzioni**: Vedere [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per soluzioni alternative inclusi symlink e ristrutturazione delle directory.

1640 1688

1641Per ulteriori strumenti di debug e problemi comuni, vedi [Debugging and development tools](/docs/it/plugins-reference#debugging-and-development-tools).1689Per ulteriori strumenti di debug e problemi comuni, vedere [Debugging and development tools](/docs/it/plugins-reference#debugging-and-development-tools).

1642 1690

1643<h2 id="see-also">1691<h2 id="see-also">

1644 Vedi anche1692 Vedi anche

plugin-marketplaces.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

Creare e distribuire un marketplace di plugin

Panoramica

Procedura dettagliata: creare un marketplace locale

Crea la struttura delle directory

Crea la skill

Crea il manifest del plugin

Crea il file marketplace

Aggiungi e installa

Provalo

Crea il file marketplace

Schema del marketplace

Campi obbligatori

Campi del proprietario

Campi opzionali

Voci di plugin

Campi obbligatori

Campi di plugin opzionali

Origini dei plugin

Percorsi relativi

Repository GitHub

Repository Git

Sottodirectory Git

Pacchetti npm

Archivi zip

Autentica i download dell'archivio

Aggiungi un headersHelper a una voce di plugin

Scrivi il comando headersHelper

Quando Claude Code salta un comando headersHelper o scarta il suo output

Come gli utenti accettano un comando headersHelper

Installazioni e aggiornamenti che rifiutano il comando invece di chiedere

Quando viene eseguito il comando di un'origine `url` del marketplace

Origini dei comandi

Modalità copia e modalità link

Come gli utenti accettano il comando

Quando Claude Code riesegue il comando

Voci di plugin avanzate

Modalità strict

Ospitare e distribuire marketplace

Ospitare su GitHub (consigliato)

Ospitare su altri servizi git

Repository privati

Comandi che esegui

Aggiornamenti automatici in background

Distribuire attraverso le impostazioni dell'organizzazione

Sincronizzare un marketplace ospitato su GitLab

Mantenere gli eseguibili fuori dalla directory bin di primo livello

Richiedere marketplace per il tuo team

Pre-popolare plugin per i container

Restrizioni del marketplace gestito

Configurazioni comuni

Come funzionano le restrizioni

Risoluzione della versione e canali di rilascio

Configurare i canali di rilascio

Esempio

Assegnare i canali ai gruppi di utenti

Fissare le versioni delle dipendenze

Rinominare o rimuovere un plugin

Validazione e test

Gestisci marketplace dalla CLI

Plugin marketplace add

Plugin marketplace list

Plugin marketplace remove

Plugin marketplace update

Risoluzione dei problemi

Marketplace non carica

Errori di validazione del marketplace

Validate a plugin or a directory without a manifest

Scegliere la directory da denominare

Controllare un plugin il cui skill è il suo `SKILL.md` radice

Controllare file dietro symlink

Leggere i risultati della validazione

Errori di installazione del plugin

L'autenticazione del repository privato non riesce

Gli aggiornamenti del marketplace non riescono in ambienti offline

Le operazioni Git scadono

I plugin con percorsi relativi non riescono nei marketplace basati su URL

File non trovati dopo l'installazione

Vedi anche