Ospitare e mantenere un marketplace

​

Host your marketplace

​

Register the marketplace for everyone in a repository

​

Avoid relative-path entries in a URL-hosted marketplace

​

Edit plugins in place on a shared directory

​

Keep plugin files out of Git LFS

​

Share files within a marketplace with symlinks

• All’interno della directory del plugin stesso: il symlink viene preservato come symlink relativo nella cache, quindi continua a risolvere il target copiato al runtime.
• Altrove all’interno dello stesso marketplace: il symlink viene dereferenziato. Il contenuto del target viene copiato nella cache al suo posto. Questo consente alla directory skills/ di un meta-plugin di collegarsi a skill definite da altri plugin nel marketplace.
• Fuori dal marketplace: il symlink viene saltato per motivi di sicurezza.

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

​

Distribute through organization settings

• Repository marketplace: su github.com e gitlab.com, deve essere privato o interno
• Plugin sources: ogni plugin source deve essere di tipo github, url, o git-subdir, o un relative path che inizia con ./
• Directory bin/ di primo livello: claude.ai rifiuta un plugin che ne ha una e sincronizza il resto del marketplace. Il messaggio di errore inizia con Plugin contains a top-level bin/ directory. Mantieni gli eseguibili in un’altra directory, come scripts/, e fai riferimento ad essi come ${CLAUDE_PLUGIN_ROOT}/scripts/<name> dai tuoi hooks o dalle configurazioni del server MCP

​

Grant access to a private marketplace

• GitHub owner/repo: Claude Code verifica ssh -T git@github.com e clona su SSH quando la verifica ha successo. Se la verifica fallisce, o il clone SSH stesso fallisce, clona su HTTPS. Gli utenti su macchine senza una chiave SSH GitHub possono impostare CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 per saltare la verifica e clonare su HTTPS.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

• SSH: la chiave deve funzionare senza un prompt di passphrase, ad esempio perché è caricata in ssh-agent. L’host deve già essere in known_hosts.
• HTTPS: Claude Code lascia abilitato l’helper di credenziali git dell’utente ma gli vieta di chiedere. Una credenziale che l’helper già memorizza funziona; una che dovrebbe chiedere fallisce. Su GitHub, gh auth login seguito da gh auth setup-git ne memorizza una.

​

Serve users who have no git-host account

• archive: uno zip scaricato su HTTPS. Gli utenti non hanno bisogno né di git né di un account, solo accesso di rete all’URL. Richiede Claude Code v2.1.224 o successivo. Fissa ogni archive con sha256 in modo che Claude Code rifiuti un download modificato. Per inviare credenziali con il download, vedi Authenticate archive downloads.
• Un repository git pubblico: Claude Code clona una source url o git-subdir pubblica su HTTPS senza credenziali quando la voce fornisce un URL https://. Per una source github, o una source git-subdir scritta come owner/repo, gli utenti senza una chiave SSH GitHub impostano CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

​

What background auto-update does with credentials

• SSH remotes: una chiave caricata in ssh-agent autentica il controllo.
• HTTPS remotes con una credenziale memorizzata: un helper che può fornire una credenziale memorizzata senza chiedere autentica il controllo. Git Credential Manager, l’helper Keychain di macOS, e git-credential-store funzionano in questo modo una volta che detengono una credenziale per l’host.
• HTTPS remotes con un helper che ha bisogno di chiedere: l’helper non può rispondere in background. L’aggiornamento fallisce silenziosamente e il checkout esistente rimane in posizione, quindi i plugin dell’utente continuano a funzionare dallo stato sincronizzato per ultimo.

• Il checkout è aggiornato: Claude Code lo lascia come è.
• Il controllo trova nuovi commit, o fallisce perché non può raggiungere o autenticarsi al remote: Claude Code clona il marketplace di nuovo e sostituisce il checkout esistente con il nuovo clone. Se quel clone fallisce, il checkout esistente rimane in posizione. Il re-clone può time out on large repositories.

• Memorizzare una credenziale: accedi all’helper di credenziali per primo in modo che memorizzi una credenziale per l’host. Per GitHub, esegui gh auth login, quindi gh auth setup-git.
• Mantenere il checkout al fallimento: se l’utente imposta CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code mantiene il checkout esistente senza tentare il re-clone quando il controllo di background non può raggiungere o autenticarsi al remote. I plugin continuano a funzionare dallo stato sincronizzato per ultimo.

​

Roll out to a whole company

• Entry sources che non hanno bisogno di un account git: Serve users who have no git-host account
• Una directory di plugin pre-popolata: Seed containers and CI, che serve anche gli utenti che non hanno un account su un host git
• Impostazioni dell’organizzazione claude.ai: Distribute through organization settings, dove le credenziali git dei tuoi utenti non sono coinvolte

​

Keep users up to date

​

Turn on auto-update

• Comunica agli utenti di attivarlo: ogni utente va a Marketplaces in /plugin, seleziona il tuo marketplace, e seleziona Enable auto-update.
• Chiedi a un amministratore di impostarlo: se un amministratore imposta "autoUpdate": true sulla voce extraKnownMarketplaces del tuo marketplace nelle impostazioni gestite, è attivato per tutti coloro che ricevono quelle impostazioni. Vedi Set update policy.

​

Release a new version

• Bump version a ogni rilascio: gli utenti rimangono sulla loro copia in cache finché la stringa non cambia. Se imposti "version": "1.0.0" e spingi nuovi commit senza cambiarlo, gli utenti non li ricevono.
• Ometti version: gli utenti tracceranno i tuoi commit invece. Lascia version fuori sia da plugin.json che dalla voce del marketplace.

​

Hold users on one version

• ref e sha sulla voce del plugin: ref nomina un branch o un tag e sha nomina un commit per una source github, url, o git-subdir. Vedi Plugin sources.
• #<ref> sul comando add: gli utenti che aggiungono your-org/your-marketplace#stable ottengono quel branch o tag del catalogo. Per due linee di rilascio contemporaneamente, vedi Run release channels.
• Tag <plugin>--v<version>: un intervallo di versione di una dipendenza si risolve rispetto a questi tag. Vedi Release a plugin that others depend on.

​

Change the command of a command source

• Nessuna più esecuzione di background: l’esecuzione una volta per sessione del comando si ferma per quell’utente, quindi l’output nuovo dello strumento non li raggiunge.
• Una voce nella scheda /plugin Errors: la voce mostra il nuovo comando e il comando claude plugin update da eseguire.

​

Run release channels

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

Rename or remove a plugin

​

Migrate users with a renames map

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Voce rinominata: il plugin carica con il suo nuovo nome. claude plugin list e i dettagli del plugin in /plugin mostrano Renamed to "code-formatter" in the "your-marketplace" marketplace una volta, e Claude Code riscrive la vecchia chiave a quella nuova in enabledPlugins e pluginConfigs negli ambiti di impostazioni utente, progetto e locale.
• Voce null: la vecchia chiave viene eliminata da quegli ambiti e l’utente vede Removed from the "your-marketplace" marketplace.
• Abilitato nelle impostazioni gestite: il plugin continua a caricare con il suo nuovo nome, ma Claude Code non può riscrivere le impostazioni gestite, quindi l’avviso ricorre finché un amministratore non aggiorna enabledPlugins lì.

​

Uninstall removed plugins from users’ machines

1. Confronta cosa gli utenti hanno installato dal tuo marketplace rispetto alle voci e alla mappa renames, e tratta qualsiasi plugin che non è né elencato né rinominato come rimosso.
2. Disinstalla ogni plugin rimosso dagli ambiti utente, progetto e locale. I plugin che solo le impostazioni gestite hanno installato rimangono in posizione.
3. Elenca ogni plugin rimosso sotto un’intestazione Flagged in /plugin con lo stato Removed from marketplace.

​

Authenticate archive downloads

• La source url del marketplace: la source url da cui hai registrato il marketplace, come una voce extraKnownMarketplaces.
• La voce del plugin: su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce marketplace.json del plugin invece, accanto a source.

​

Add a headersHelper to a plugin entry

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

​

Write the headersHelper command

• 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 0 entro 10 secondi.
• Shell e directory di lavoro: Claude Code esegue il comando attraverso sh, o attraverso cmd.exe su Windows. La directory di lavoro è la directory di configurazione, che è ~/.claude o CLAUDE_CONFIG_DIR. Dai 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: quando il comando è impostato in una voce marketplace.json, o nel .claude/settings.json o .claude/settings.local.json di un progetto, Claude Code rimuove dall’ambiente ogni variabile il cui nome sembra una credenziale, per la stessa regola che applica a un MCP headersHelper. ANTHROPIC_API_KEY e MY_REGISTRY_TOKEN sono entrambi rimossi, quindi fai leggere la credenziale al comando da un file o da un archivio di credenziali. Questa rimozione non si applica 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 source 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 fetch dopo che un utente aggiunge un marketplace per URL, perché quel fetch è quello che fornisce il nome.

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

When Claude Code skips a headersHelper command or drops its output

• Il comando fallisce: se il comando esce non-zero, viene eseguito oltre 10 secondi, o stampa qualcosa di diverso da un oggetto JSON di valori di stringa, il fetch o il download per il quale il comando è stato eseguito non accade.
• L’URL del marketplace non inizia con https://: il comando di quella source url non viene eseguito, e le richieste portano solo le intestazioni elencate nel suo campo headers.
• Il reindirizzamento lascia l’origine: quando un download viene reindirizzato fuori dall’origine dell’URL dell’archive, la richiesta reindirizzata non porta valori headers o output del comando da nessuno della source url del marketplace o della voce del plugin.
• La voce imposta un’intestazione di routing o identità: Claude Code elimina i nomi di routing di richiesta 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. Ogni voce marketplace.json viene filtrata in questo modo. Per una voce di plugin inline nelle impostazioni, vedi extraKnownMarketplaces.
• Il comando è impostato nelle impostazioni di una directory --add-dir: il comando viene ignorato, su una source url e su una voce di plugin inline allo stesso modo, e solo le headers di quel file vengono inviate.
• 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 continua a eseguire il comando per un marketplace che le impostazioni gestite stesse dichiarano.

​

How users accept a headersHelper command

​

Installs and updates that refuse a command instead of asking

• Installazione di diversi 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 propria di quel plugin in /plugin. Gli altri plugin in un’installazione in blocco continuano a installare. Un plugin che dipende dal plugin rifiutato non riesce a installare finché l’utente non installa il plugin rifiutato da solo.
• Background auto-update, o avvio della sessione per un plugin il cui archive non è mai stato scaricato: Claude Code elenca il plugin nella scheda /plugin Errors in modo che l’utente sappia di installarlo o aggiornarlo da solo.

​

When a marketplace url source’s command runs

​

Depend on and recommend other plugins

• Intervalli di versione: una dipendenza può portare un intervallo semver.
• Dipendenze cross-marketplace: una dipendenza da un altro marketplace installa solo quando il tuo marketplace elenca quel marketplace in allowCrossMarketplaceDependenciesOn.

​

Work around what a marketplace can’t do

• Limitare cosa altro gli utenti installano: l’allowlist del marketplace è un’impostazione gestita, strictKnownMarketplaces. Vedi Restrict what users can install.
• Installare o abilitare un plugin senza che l’utente chieda: nessun campo di voce installa un plugin. enabledPlugins gestito lo fa per una flotta; vedi Pre-install and require plugins.
• Mostrare voci diverse a utenti diversi: le voci non portano un campo di audience, e ogni utente che aggiunge il marketplace vede l’intero catalogo. Ospita marketplace separati per audience separate.
• Contrassegnare un plugin come deprecato: non c’è uno stato di deprecazione. L’opzione è rimuovere la voce, mappare il suo nome a null in renames, e opzionalmente impostare forceRemoveDeletedPlugins.
• Attivare auto-update per i tuoi utenti: ogni utente lo attiva in Marketplaces in /plugin, o un amministratore imposta autoUpdate nelle impostazioni gestite. Vedi Turn on auto-update.
• Portare credenziali git: nessun campo di marketplace contiene un token git. L’accesso a un marketplace o plugin ospitato su git segue la configurazione git dell’utente, per Grant access to a private marketplace. Per le source archive, una voce può impostare headers o headersHelper invece.

​

Next steps

• Marketplace reference: campi marketplace.json, tipi di source, e messaggi di convalida
• Manage plugins for your organization: richiedi, limita, o semina il tuo marketplace su tutte le macchine della tua organizzazione
• Plugin dependencies: etichetta i rilasci in modo che i plugin che dipendono dal tuo possano risolvere le versioni
• Troubleshoot plugins: gli errori che i tuoi utenti vedono quando aggiungono o aggiornano dal tuo marketplace