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.

Plugin sources

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

Claude 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, che Claude Code utilizza al suo posto. Claude Code inoltre installa le dipendenze del pacchetto Node.js idonee del plugin nella copia memorizzata nella cache.

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

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

Se distribuisci plugin tramite Organization settings > Plugins, solo alcuni tipi di source sono consentiti. Vedi Distribute through organization settings.

Percorsi relativi

Per i plugin nello stesso repository, usa 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 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.

Un bare name è un singolo nome di directory senza /, come "formatter". Per scrivere bare names invece di percorsi ./, imposta metadata.pluginRoot 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.

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.

Repository GitHub

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

Puoi fissare 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 fissare 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

Usa 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 fissare 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

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

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

Per fissare 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

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

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

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 riesce a installarsi. Claude Code rifiuta gli archivi più grandi di 256 MiB.

Per fissare 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 pin, Claude Code rifiuta l'install e segnala Plugin archive integrity check failed.

Le archive sources 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 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.

Autentica i download degli archivi

Per 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. Su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce del plugin invece, accanto a source.

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

Il posto che scegli decide quali download ottengono 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 è la definizione completa 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 lo zip dopo che accetti.

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

Scrivi il comando headersHelper

Che tu imposti headersHelper su una url source 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 una sequenza 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 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.
• 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.

Un comando che conia 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 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.
• 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.
• 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.
• 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 a seconda di quale file la dichiara.
• 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 allo stesso modo, e invia solo le headers di quel file.
• Le impostazioni gestite bloccano il comando: impostare disableCommandPluginSources a 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 ancora 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 accettarlo.

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'install o l'aggiornamento. Un cambio nella stringa di query da solo non conta.

Install e aggiornamenti che rifiutano il comando invece di chiedere

Su 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:

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

Quando il comando headersHelper di una marketplace `url` source viene eseguito

Un headersHelper di una marketplace url source è 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 install 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 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.

Per una voce di plugin inline 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.

Command sources

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

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 in cui il comando esce, e il percorso può cambiare tra le esecuzioni.

Claude 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:

• 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 padre
• Su Windows, il percorso è un percorso UNC

Le command sources accettano questi campi:

Copy mode and link mode

Con il predefinito "mode": "copy", Claude Code copia la directory stampata nella cache del plugin con versione e deriva la plugin version 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.

Imposta "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 per un plugin in link mode, quindi stampa una directory che contiene già qualsiasi node_modules di cui il plugin ha bisogno.

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

Claude Code non supporta link mode su Windows e rifiuta di installare un plugin in link mode 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 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.
• 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. 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.
• 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>.

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

Quando Claude Code riesegue il comando

La 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:

• Ogni volta che l'utente installa o aggiorna il plugin
• 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 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 install e gli aggiornamenti 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 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.

Voci di plugin avanzate

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

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Strumenti di automazione del flusso di lavoro aziendale",
  "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 importanti da notare:

• 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.
  • 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}: 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.
  • 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 dei plugin, usa ${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 Strict mode di seguito.

Per 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:

"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 skills:

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

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

Strict mode

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

Quando usare ogni modalità:

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

Ospita e distribuisci marketplace

Ospita su GitHub (consigliato)

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

1. Crea un repository: configura un nuovo repository per il tuo marketplace
2. Aggiungi il file marketplace: crea .claude-plugin/marketplace.json con le tue definizioni di plugin
3. Condividi con i team: gli utenti aggiungono il tuo marketplace con /plugin marketplace add owner/repo

Vantaggi: controllo della versione integrato, tracciamento dei problemi e funzionalità di collaborazione del team.

Ospita 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 tramite Organization 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 per le regole complete.

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 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 per clonare su HTTPS invece.

Aggiornamenti automatici in background

Per 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, quindi gli aggiornamenti automatici del marketplace privato possono non riuscire intermittentemente.

Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:

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

Impostare 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 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:

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

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

Distribuisci tramite impostazioni dell'organizzazione

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

• 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.
• 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, ad esempio ./plugins/deploy-tools.
• Un'origine di plugin può essere privata in due 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
• 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.

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

Mantieni gli eseguibili fuori dalla directory bin di livello superiore

Non 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:

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

Richiedi 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-popola plugin per i container

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

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

Dettagli del comportamento:

• 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.
• 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.
• 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.
• 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.
• 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 fonti dei plugin, gli amministratori possono limitare quali marketplace di plugin gli utenti possono aggiungere utilizzando l'impostazione strictKnownMarketplaces nelle impostazioni gestite. Per anche rifiutare 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 contestuali, imposta pluginSuggestionMarketplaces.

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 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 tutti gli aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:

{
  "strictKnownMarketplaces": []
}

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

Su queste macchine, aggiungi il marketplace a extraKnownMarketplaces nello stesso managed-settings.json in modo che Claude Code lo registri automaticamente, o 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/"
    }
  ]
}

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

Come funzionano le restrizioni

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

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

Quando un utente aggiunge un URL di repository https:// che Claude Code clona piuttosto che recupera, 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.

L'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:

• 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. 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
• Per le fonti URL: l'URL completo deve corrispondere esattamente
• Per le fonti hostPattern: l'host del marketplace viene confrontato con il modello regex
• Per le fonti pathPattern: il percorso del filesystem del marketplace viene confrontato con il modello regex

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

Poiché strictKnownMarketplaces è impostato nelle impostazioni gestite, le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.

Per i dettagli di configurazione completi inclusi tutti i tipi di fonte 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 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 per l'ordine di risoluzione completo, incluse le fonti archive.

Configura i canali di rilascio

Per 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:

• 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 fonti gestite dice se il file per gruppo o il profilo si applica su un dispositivo che ha anche una fonte a livello di organizzazione.
• Definisci una policy del gateway delle app Claude 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.

Le impostazioni gestite dal server dalla console di amministrazione si applicano a ogni utente nella 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"
      }
    }
  ]
}

Assegna i canali ai gruppi di utenti

Assegna 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. Ad esempio, il gruppo stabile riceve:

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

Il gruppo early-access riceve invece latest-tools:

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

Fissa le versioni delle dipendenze

Un 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 per la convenzione del tag git {plugin-name}--v{version}, la sintassi dell'intervallo e come più vincoli sulla stessa dipendenza vengono combinati.

Rinomina o rimuovi un plugin

Il 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 e mantieni name invariato.

Se 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:

{
  "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 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.
• 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 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.

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

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

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.

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.

Troubleshooting

Marketplace non carica

Sintomi: Non riesci ad aggiungere il marketplace o a vedere i plugin da esso

Soluzioni:

• Verifica che l'URL del marketplace sia accessibile
• Controlla che .claude-plugin/marketplace.json esista nel percorso specificato
• 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
• Per i repository privati, conferma di avere i permessi di accesso

Errori di validazione del marketplace

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

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

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

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

Dalla 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. 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: aggiungi almeno un plugin all'array plugins
• No marketplace description provided: aggiungi una description di livello superiore per aiutare gli utenti a comprendere il tuo marketplace
• 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.
• 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.
• 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.

Validate a plugin or a directory without a manifest

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

Pick the directory to name

Claude 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:

Check a plugin whose skill is its root `SKILL.md`

Quando 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:

• Denomina quella directory skills per verificare il SKILL.md radice del plugin.
• Denomina la directory del plugin per verificare il resto.

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

Check files behind symlinks

Quando 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:

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

In 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:

• Un plugin il cui directory skills collega a una directory skills di un plugin fratello: denomina la directory del plugin fratello.
• Una voce di skill collegata 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.

Read the validation results

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

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

• 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 file
• 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 plugin

In 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 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:

• Verifica che gli URL di origine del plugin siano accessibili
• Controlla che le directory dei plugin contengano i file richiesti
• Per le origini GitHub, assicurati che i repository siano pubblici o che tu abbia accesso
• Testa 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 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 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:

• Verifica di essere autenticato con il tuo provider git (ad esempio, esegui gh auth status per GitHub)
• Controlla che il tuo helper di credenziali sia configurato: git config --global credential.helper
• 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

Per gli aggiornamenti automatici in background:

• 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 dimensioni
• Imposta CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il clone esistente quando il pull in background non riesce
• Configura un helper di credenziali git, ad esempio gh auth setup-git, in modo che il fallback di ri-clonazione possa autenticarsi
• Se la ri-clonazione scade su un repository di grandi dimensioni, aumenta il limite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configura una riscrittura dell'URL git limitata al repository del marketplace in modo che il pull in background si autentichi direttamente
• Oppure aggiorna i marketplace privati manualmente con /plugin marketplace update <name>, che utilizza le tue credenziali

Gli aggiornamenti del marketplace non riescono in ambienti offline

Sintomi: Il git pull del marketplace non riesce in background e Claude Code tenta ripetutamente una ri-clonazione che non può avere successo.

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.

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:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizza 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" o "Git pull timed out after 120s".

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.

Soluzione: Aumenta 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 minuti

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

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.

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:

• Usa origini esterne: cambia le voci dei plugin per usare qualsiasi plugin source diverso da un percorso relativo:

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

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

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: I plugin vengono copiati in una directory cache piuttosto che utilizzati in-place, tranne per una command source in 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.

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

Per ulteriori strumenti di debug e problemi comuni, vedi 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