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:

1. 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.
2. Creazione di un file marketplace: definisci un marketplace.json che elenca i tuoi plugin e dove trovarli. Vedi Crea il file marketplace.
3. Ospita il marketplace: esegui il push su GitHub, GitLab o un altro host git. Vedi Ospita e distribuisci marketplace.
4. 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.

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

---
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.

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

{
"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"
}
]
}

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

/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

Campi del proprietario

Campi opzionali

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

Campi di plugin opzionali

Campi di metadati standard:

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:

Campi di autenticazione dell'archivio:

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

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.

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"
  }
}

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"
  }
}

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).

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"
  }
}

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:

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:

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:

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:

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).

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:

1. Creare un repository: configurare un nuovo repository per il tuo marketplace
2. Aggiungere il file marketplace: creare .claude-plugin/marketplace.json con le definizioni dei tuoi plugin
3. 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

Il controllo di aggiornamento in background verifica il remote del marketplace per i nuovi commit con i tuoi helper di credenziali git configurati, allo stesso modo dei comandi che esegui. Per i remote SSH, una chiave caricata in ssh-agent autentica il controllo. Claude Code esegue il controllo in modo non interattivo: disattiva i prompt del terminale di git e i programmi askpass, e dice agli helper di credenziali di non richiedere. Se il controllo può autenticarsi a un repository privato su HTTPS dipende dal tuo helper:

• Un helper che può fornire una credenziale memorizzata senza richiedere autentica il controllo. Git Credential Manager, l'helper Keychain di macOS e git-credential-store funzionano in questo modo una volta che contengono una credenziale per l'host.
• Un helper che ha bisogno di richiedere non può rispondere in background. L'aggiornamento fallisce silenziosamente e il checkout esistente rimane al suo posto, quindi i tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione. Esegui /plugin marketplace update <name> per aggiornare il marketplace con le tue credenziali.

Quando il controllo trova il checkout aggiornato, Claude Code lo lascia così com'è. 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 può scadere su repository di grandi dimensioni.

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 il controllo in background e la re-clonazione possano 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.

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:

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.

Dove i due elenchi vengono applicati dipende da dove li imposti:

• La console di amministrazione claude.ai: Claude Code applica entrambi gli elenchi nelle sessioni che leggono le impostazioni gestite dal server. claude.ai li controlla anche quando chiunque nella tua organizzazione aggiunge un nuovo marketplace da un repository git su claude.ai, o da Customize nell'app Claude Desktop al di fuori della sua scheda Code. Questo copre un marketplace che un membro aggiunge per il proprio account e uno aggiunto per l'intera organizzazione in Organization settings > Plugins. claude.ai rifiuta un repository che l'allowlist non ammette o che la blocklist nomina. Non ri-controlla un marketplace che è stato aggiunto in entrambi i posti prima che tu imposti gli elenchi, e non controlla i plugin caricati.
• Un file di impostazioni gestite, una politica a livello di sistema operativo o un'altra origine gestita: Claude Code applica entrambi gli elenchi dove legge quella fonte. claude.ai non la legge.

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.

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:

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:

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:

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:

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:

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:

• Il controllo in background utilizza gli helper delle credenziali git configurati ma non richiede mai, quindi l'helper deve essere in grado di rispondere con una credenziale archiviata. I remote SSH con una chiave caricata in ssh-agent si autenticano anche
• Se l'helper deve richiedervi, l'aggiornamento in background non riesce silenziosamente e il checkout esistente rimane in place. Accedere all'helper prima in modo che contenga una credenziale per l'host. Per GitHub, eseguire gh auth login, quindi gh auth setup-git
• Quando il controllo trova nuovi commit, o non riesce a raggiungere o autenticarsi al remote, Claude Code ri-clona il marketplace con le stesse credenziali. Il ri-clone potrebbe scadere su repository di grandi dimensioni
• Impostare CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il checkout esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote
• Se il ri-clone scade su un repository di grandi dimensioni, aumentare il limite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Oppure aggiornare i marketplace privati manualmente con /plugin marketplace update <name>, che utilizza le credenziali

Prima della v2.1.280, il controllo in background veniva eseguito senza gli helper delle credenziali e non poteva autenticarsi ai repository privati su HTTPS.

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 il marketplace di nuovo. Offline, il clone non riesce allo stesso modo e il checkout esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva git pull nel checkout esistente, spostava il checkout 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 checkout 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