Marketplace reference

Riferimento completo per i campi marketplace.json, le voci dei plugin e gli oggetti sorgente del plugin e del marketplace, con indicazione di dove ciascuno è valido.

marketplace.json è il file che definisce un marketplace di plugin. Contiene il nome del marketplace, il suo proprietario e una voce per ogni plugin. La sorgente del plugin di ogni voce indica da dove Claude Code recupera quel plugin.

Una sorgente marketplace è un oggetto separato che indica da dove Claude Code recupera il file marketplace stesso. Si scrive nelle impostazioni, oppure Claude Code ne crea una quando si esegue claude plugin marketplace add.

Questo riferimento è per i manutentori di marketplace che hanno bisogno di un nome di campo o di un valore esatto, e per gli amministratori che hanno bisogno di sapere quali valori source sono validi in extraKnownMarketplaces, strictKnownMarketplaces e blockedMarketplaces.

Trovare la sezione per quello che si sta scrivendo o leggendo:

• Il file marketplace: Top-level fields e Plugin entries
• La source di una voce: Plugin sources
• Un oggetto source nelle impostazioni: Marketplace sources
• Output da claude plugin validate <path>: Validation messages, che mappa ogni messaggio al campo che nomina

Marketplace file

Salvare il file marketplace in .claude-plugin/marketplace.json nella directory del marketplace. Se si mantiene il file altrove nel repository, gli utenti devono dichiarare il marketplace in extraKnownMarketplaces con path impostato sulla sua sorgente, perché claude plugin marketplace add non ha un'opzione per questo.

La directory che contiene .claude-plugin/ è chiamata marketplace root, e ogni sorgente di plugin relativa si risolve da essa, non da .claude-plugin/.

Ogni utente registra un marketplace per name, quindi un utente non può avere due marketplace con lo stesso nome registrati contemporaneamente.

Claude Code ignora una chiave di primo livello sconosciuta o una chiave di voce di plugin piuttosto che rifiutarla, quindi un errore di battitura si carica silenziosamente. claude plugin validate segnala ogni chiave sconosciuta come un avviso.

Reserved names

Non è possibile assegnare al marketplace nessuno dei seguenti nomi:

• Nomi ufficiali del marketplace: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins e claude-tag-plugins. Riservati a meno che il marketplace non provenga da una sorgente marketplace github o git sotto github.com/anthropics/.
• Nomi del marketplace della comunità: claude-community, claude-plugins-community e healthcare. Riservati secondo la stessa regola dei nomi ufficiali.
• Nomi della directory dei plugin: anthropic-plugin-directory e claude-plugin-directory. Riservati secondo la stessa regola dei nomi ufficiali.
• Nomi che impersonano un marketplace ufficiale: nomi come official-claude-plugins o claude-plugins-v2, e qualsiasi nome contenente un carattere non ASCII. L'errore è Marketplace name impersonates an official Anthropic/Claude marketplace. Un carattere di controllo o di formattazione bidirezionale in un nome segnala anche Marketplace name cannot contain control or bidirectional-formatting characters.
• Un'altra ortografia di un nome riservato: un nome che differisce da un nome riservato solo per un punto finale, o per un simbolo diverso da un trattino al posto di un trattino, quindi claude.code.plugins conta come claude-code-plugins. claude plugin validate accetta tale nome; l'aggiunta del marketplace non riesce con is another spelling of "<reserved>", a reserved marketplace name, e un marketplace già registrato sotto uno smette di caricarsi. Questo controllo richiede Claude Code v2.1.280 o successivo.
• Nomi che Claude Code utilizza per i plugin che non provengono da un marketplace: inline per i plugin caricati con --plugin-dir, builtin per i plugin integrati, skills-dir per i plugin caricati automaticamente da .claude/skills/ e synced per i plugin sincronizzati dal proprio account claude.ai. Anche claude-plugin-test è riservato. skills-dir appare anche come {"source": "skills-dir"} in strictKnownMarketplaces e blockedMarketplaces, descritto in Source values valid only in policy lists.
• npm, pip, uv, cargo, github e gh: riservati in qualsiasi maiuscola. Questo controllo richiede Claude Code v2.1.275 o successivo.
• Nomi che iniziano con claudeai-: riservati per i marketplace ospitati su claude.ai. claude plugin marketplace add rifiuta qualsiasi altro marketplace che ne utilizzi uno con Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.

Top-level fields

La tabella elenca ogni chiave che Claude Code legge da marketplace.json. name, owner e plugins sono obbligatori.

Plugin entries

Ogni oggetto nell'array plugins di primo livello di marketplace.json nomina un plugin e dice dove recuperarlo. name e source sono obbligatori.

Una voce accetta anche ogni campo plugin.json, come description, version, author, commands e hooks. Per quando questi campi si applicano, vedere How an entry combines with plugin.json.

La tabella elenca i campi propri della voce e i campi del manifesto il cui significato cambia in una voce.

How an entry combines with plugin.json

I campi della voce si applicano diversamente a un plugin recuperato che ha il suo .claude-plugin/plugin.json e a uno che non lo ha:

• No plugin.json: la voce è il manifesto indipendentemente da strict. Ogni campo del manifesto nella voce si applica, inclusi mcpServers, lspServers, userConfig e channels.
• plugin.json presente: plugin.json è il manifesto. Strict mode decide se i sei campi componenti della voce, commands, agents, skills, hooks, outputStyles e themes, sono combinati con esso o rifiutati come conflitto. La voce mcpServers, lspServers, userConfig e channels non si applicano. Dichiararli in plugin.json.

Hooks in an entry

Scrivere hooks della voce come un oggetto inline che mappa i nomi degli eventi hook agli array di matcher. Se si scrive un percorso di file o un array, claude plugin validate lo passa. Questi hook non vengono mai eseguiti e Claude Code segnala un errore not yet supported in a marketplace entry per il plugin. Mettere gli hook basati su file nel hooks/hooks.json del plugin stesso o in plugin.json.

Display fields

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

• Per un campo impostato 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 sorgente relativa, i cui file di plugin si trovano all'interno del marketplace stesso. Per una voce con qualsiasi altro tipo di sorgente, gli utenti vedono solo i campi propri della voce fino a quando non installano il plugin.

Strict mode

strict decide cosa succede quando il plugin recuperato ha il suo plugin.json e la voce dichiara anche uno dei campi componenti: commands, agents, skills, hooks, outputStyles o themes. Con strict: true, il predefinito, Claude Code aggiunge i campi componenti della voce a plugin.json, tranne hooks, i cui matcher sostituiscono quelli del manifesto per evento. Con strict: false, una voce che dichiara un campo componente è un conflitto e il plugin non riesce a caricarsi. La tabella mostra ogni combinazione di strict, plugin.json e i campi componenti della voce.

Plugin sources

La source di una voce di plugin dice da dove Claude Code recupera quel plugin. È una stringa di percorso relativo o un oggetto la cui chiave source nomina il tipo, quindi una voce assomiglia a "source": { "source": "github", "repo": "your-org/formatter" }.

La tabella elenca ogni tipo di sorgente di plugin e i suoi campi.

I nomi url e github sono anche tipi di sorgente marketplace, dove url significa un collegamento diretto a un file marketplace.json piuttosto che a un repository git. git esiste solo come sorgente marketplace e npm esiste come entrambi. git-subdir, archive e command esistono solo come sorgenti di plugin.

Utilizzare un percorso relativo per un plugin in una sottodirectory del repository del marketplace stesso. Utilizzare git-subdir per una sottodirectory di un altro repository.

Le sorgenti github, url e git-subdir condividono i campi ref e sha:

• ref: un ramo o un tag. Predefinito al ramo predefinito del repository.
• sha: un SHA di commit completo di 40 caratteri in minuscolo. Quando si impostano sia ref che sha, Claude Code estrae sha. Sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket, ciò significa che l'installazione ha successo anche se il ramo 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 di commit per SHA. Su questi server il ref deve ancora esistere e il commit bloccato deve essere raggiungibile da esso.

Per come ogni tipo viene recuperato, memorizzato nella cache e versionato, vedere Plugin loading reference.

Relative path plugin source

Il percorso si risolve dalla radice del marketplace. ./plugins/formatter è <root>/plugins/formatter anche se il file marketplace è in <root>/.claude-plugin/.

Un percorso contenente .. non supera la convalida. Su macOS e Linux, Claude Code rifiuta un percorso di voce che contiene una barra rovesciata in qualsiasi punto dopo il ./ iniziale, quindi scrivere il percorso con barre in avanti.

{ "name": "formatter", "source": "./plugins/formatter" }

Un percorso relativo si risolve solo quando Claude Code ha i file del marketplace, quindi controllare il tipo di sorgente marketplace:

• github, git, file e directory: Claude Code ha i file del marketplace.
• url: Claude Code recupera solo marketplace.json, quindi i percorsi relativi non possono risolversi. Dare a ogni plugin una sorgente di oggetto, come github o git-subdir.
• settings: i percorsi relativi sono rifiutati completamente.

Bare names under pluginRoot

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

metadata.pluginRoot ha questi limiti:

• Deve essere esso stesso un percorso relativo all'interno del marketplace.
• Non ha effetto su una sorgente che inizia già con ./.
• Una sorgente che contiene un /, come team-a/formatter, non è un nome bare e ha ancora bisogno del prefisso ./, anche quando metadata.pluginRoot è impostato.

github plugin source

repo accetta owner/repo. ref e sha sono facoltativi.

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url plugin source

url è un URL git completo: https://, http://, file:// o git@. Un suffisso .git non è obbligatorio, quindi gli URL di Azure DevOps e AWS CodeCommit funzionano come scritti. Questo tipo non accetta la scorciatoia owner/repo.

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

git-subdir plugin source

url accetta un URL git completo o la scorciatoia GitHub owner/repo. path è la sottodirectory che contiene il plugin e Claude Code scarica solo quella sottodirectory.

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

npm plugin source

Una sorgente npm accetta questi campi:

• package: un nome di pacchetto, o un nome con scope come @your-org/formatter
• version: una versione o un intervallo
• registry: un URL di registro per un pacchetto che non è nel registro predefinito

Claude Code recupera il pacchetto con il client npm. 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 ha 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.

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

archive plugin source

url deve utilizzare https:// e non può puntare a un host loopback, link-local o cloud-metadata.

La radice del plugin può essere in cima al zip o una directory in basso.

sha256 è il digest dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Quando lo si imposta, Claude Code rifiuta un download che non corrisponde.

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

command plugin source

Utilizzare una sorgente command quando uno strumento installato sulla macchina dell'utente produce la directory del plugin, come un IDE che renderizza il suo plugin per la toolchain che l'utente ha selezionato. Claude Code esegue il comando quando l'utente installa o aggiorna il plugin e di nuovo una volta per sessione, quindi gli utenti ottengono l'output modificato dello strumento senza reinstallare.

Una sorgente command accetta questi campi:

• command: un comando shell che stampa il percorso assoluto della directory del plugin come una riga e esce 0. Claude Code mostra agli utenti l'intera stringa per la revisione prima di eseguirla. Scriverla come ASCII stampabile, al massimo 500 caratteri, senza una sequenza di quattro o più spazi.
• timeout: un numero intero di secondi da 1 a 600. Predefinito a 60.
• mode: copy, il predefinito, o link. Vedere Copy mode and link mode.

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

Per come gli utenti accettano il comando, vedere Install from your shell. Per cosa vedono gli utenti dopo averlo modificato, vedere Change the command of a command source. Gli amministratori disattivano le sorgenti di comando con disableCommandPluginSources.

What the command must do

Scrivere il comando per soddisfare questi requisiti:

• Shell e directory di lavoro: Claude Code esegue il comando attraverso sh, o attraverso cmd.exe su Windows, dalla directory home dell'utente. Fornire un percorso assoluto o un comando su PATH.
• Output: stampare esattamente una riga su stdout, il percorso assoluto della directory del plugin, e uscire 0 entro timeout secondi.
• Contenuti della directory: la directory contiene il plugin completo al momento dell'uscita del comando. Il percorso può differire da un'esecuzione all'altra.

Output that fails the install or update

L'installazione o l'aggiornamento non riesce quando il comando esce non-zero, viene eseguito più a lungo di timeout, o stampa qualcosa di diverso da un percorso assoluto. Fallisce anche quando la directory stampata è una di queste:

• Nessun contenuto di plugin: la directory stampata non ha contenuto di plugin al suo livello superiore, come una directory .claude-plugin/ o una directory skills/, commands/, agents/ o hooks/.
• La directory della sessione stessa: la directory stampata è quella in cui Claude Code è stato avviato, o una dei suoi genitori.
• Un percorso di rete: su Windows, il percorso stampato è un percorso UNC.
• Troppo grande da copiare: in modalità copia, la directory è più grande di 256 MiB o ha più di 20.000 voci.

Copy mode and link mode

mode decide se Claude Code copia la directory stampata o la utilizza in posizione:

• copy: Claude Code copia la directory nella cache del plugin e deriva la versione del plugin da un hash dei file copiati. Lo strumento può eliminare o riscrivere la directory dopo l'uscita del comando. Una ri-esecuzione che produce file identici conta come aggiornato.
• link: Claude Code riempie la voce della cache del plugin con un collegamento a ogni voce di primo livello della directory stampata e carica i file in posizione. Nulla viene copiato, i contenuti dei file non vengono sottoposti a hash e i limiti di dimensione non si applicano. Utilizzarlo per una directory troppo grande da copiare, come un'esportazione SDK renderizzata.

Un plugin in modalità link ha questi requisiti:

• Mantenere la directory in posizione: Claude Code carica il plugin attraverso i link ad ogni avvio, quindi la directory stampata deve rimanere dove si trova finché il plugin rimane installato.
• Stampare un percorso diverso per segnalare nuovo contenuto: la versione proviene dal percorso reale della directory stampata e dalle sue voci di primo livello, non dai file al loro interno.
• Mantenere i symlink di primo livello all'interno della directory: l'installazione non riesce se una voce di primo livello è un symlink che punta al di fuori della directory stampata.
• Includere node_modules: Claude Code salta l'installazione della dipendenza del pacchetto Node.js per un plugin in modalità link, quindi stampare una directory che contiene già i pacchetti di cui il plugin ha bisogno.
• Sessioni avviate all'interno della directory: una sessione avviata nella directory stampata o in qualsiasi punto al di sotto di essa non carica il plugin.
• Non su Windows: Claude Code rifiuta di installare un plugin in modalità link su Windows. Dichiarare "mode": "copy" lì.

Marketplace sources

Una sorgente marketplace dice da dove Claude Code recupera un marketplace.json. La CLI ne crea una per voi quando aggiungete un marketplace, e ne scrivete una voi stessi nelle impostazioni:

• claude plugin marketplace add: Claude Code crea la sorgente dalla stringa che passate.
• extraKnownMarketplaces: scrivete la sorgente voi stessi come oggetto source.
• strictKnownMarketplaces e blockedMarketplaces: gli amministratori scrivono le sorgenti in questi due elenchi di policy. strictKnownMarketplaces è l'allowlist e blockedMarketplaces è la blocklist.

I nomi di tipo url, git e github significano qualcosa di diverso in una sorgente marketplace rispetto a una sorgente di plugin:

La tabella elenca ogni tipo di sorgente marketplace con i suoi campi, l'input claude plugin marketplace add che lo produce e cosa fa in ciascuna delle tre chiavi di impostazioni.

Fields by type

La tabella elenca ogni campo della sorgente marketplace che ha un predefinito, un vincolo o un significato specifico del tipo.

Source values valid only in policy lists

hostPattern, pathPattern, skills-dir e la forma owner/* di repo sono validi solo nei due elenchi di policy, strictKnownMarketplaces e blockedMarketplaces:

• hostPattern e pathPattern: espressioni regolari che Claude Code testa rispetto a una sorgente prima di recuperare da essa.
• skills-dir: non una sorgente. Se si imposta strictKnownMarketplaces affatto, i plugin della directory delle competenze smettono di caricarsi fino a quando non si aggiunge {"source": "skills-dir"} a quell'elenco.
• owner/*: come valore repo di github, corrisponde a ogni repository esattamente sotto quel proprietario GitHub. Richiede Claude Code v2.1.223 o successivo.

Per l'ordine di corrispondenza, la semantica esatta di ref e le ricette, vedere Manage plugins for your organization.

Source objects in settings

Un valore extraKnownMarketplaces è una mappa dal nome del marketplace a un oggetto con source. Questa voce registra un marketplace da un repository git al suo ramo main:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

strictKnownMarketplaces e blockedMarketplaces sono array di oggetti sorgente. Questa allowlist ammette un proprietario GitHub e un host interno:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

Validation messages

claude plugin validate <path> accetta la radice del marketplace o il file marketplace stesso. Stampa errori e avvisi. Per i codici di uscita e --strict, vedere plugin validate.

Un messaggio nomina una voce di plugin per il suo indice, scritto come plugins.1.source o plugins[1].source.

Un messaggio con prefisso di un indice di voce e plugin.json →, come plugins[2] plugin.json →, riguarda i file propri di quel plugin. claude plugin validate segnala errori elenca quei messaggi con le loro correzioni.

Gli avvisi che menzionano i nomi dei flag di Claude Desktop segnalano i nomi che Claude Code accetta ma Claude Desktop rifiuta, perché le regole dei nomi di Claude Desktop sono più rigorose.

La tabella mappa i messaggi a livello di marketplace al campo di cui ciascuno parla.

Invalid input on a source

Invalid input su una source significa che l'oggetto non ha corrisposto a nessun tipo di sorgente. Controllare queste cause:

• Un percorso relativo che non inizia con ./, diverso da "." o un nome bare sotto metadata.pluginRoot
• Un package npm contenente ..
• Un tipo di source che non è uno delle sorgenti di plugin
• Un tipo noto con un campo obbligatorio mancante o di tipo errato, come github senza repo

Failures that validation doesn't catch

claude plugin validate non segnala ogni fallimento. Una hooks di voce scritta come percorso di file o array passa la convalida e l'errore appare solo quando il plugin si carica, come Hooks in an entry descrive. Gli errori di recupero di una source appaiono anche solo dopo l'installazione, non nella convalida.

claude plugin list mostra un plugin che non è riuscito a caricarsi con il suo errore e Troubleshoot plugins copre le stringhe di caricamento.

Next steps

• Create a marketplace: costruire un marketplace da questi campi e installare da esso localmente
• Host and maintain a marketplace: dove mettere il file e come gli utenti ricevono i cambiamenti
• Plugin manifest reference: i campi plugin.json che una voce può sovrascrivere
• Manage plugins for your organization: ricette di allowlist e blocklist che utilizzano questi valori di sorgente