SpyBara
Go Premium

plugins/marketplace-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 533 additions and 0 deletions.

2026
Fri 25 23:58

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:

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.

Field Type Description
name string Identificatore del marketplace. Nessuno spazio, caratteri di controllo o caratteri di formattazione bidirezionale, nessun / o \, nessun .. e non .. Vedere Reserved names. Gli utenti lo digitano dopo @ quando installano un plugin
owner object Informazioni del manutentore. name è obbligatorio; email e url sono facoltativi
plugins array Plugin entries. Ogni voce è convalidata da sola, quindi una voce non valida non fa fallire il marketplace
$schema string URL dello schema JSON per l'autocompletamento dell'editor. Ignorato al momento del caricamento
description string Descrizione del marketplace mostrata agli utenti. claude plugin validate avverte quando manca
version string Versione del manifesto del marketplace
metadata.description, metadata.version string Posizione alternativa per description e version
metadata.pluginRoot string Directory in cui i nomi di sorgente di plugin bare si risolvono. Vedere Relative path plugin source. Richiede Claude Code v2.1.239 o successivo
forceRemoveDeletedPlugins boolean Quando true, un plugin che si rimuove da plugins viene disinstallato sulle macchine degli utenti. Vedere Host and maintain a marketplace
allowCrossMarketplaceDependenciesOn array of strings Nomi di marketplace i cui plugin possono essere installati come dipendenze dei plugin di questo marketplace. Quando si installa un plugin, si applica solo l'elenco nel marketplace del plugin stesso, per l'intera catena di dipendenze. Vedere Plugin dependencies
renames object Mappa da un precedente name del plugin al suo nome attuale, o a null per un plugin rimosso. Richiede Claude Code v2.1.193 o successivo. Vedere Host and maintain a marketplace

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.

Field Type Description
name string Identificatore del plugin, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Gli utenti lo digitano prima di @ quando installano, anche quando il plugin.json del plugin stesso imposta un name diverso
source string or object Dove recuperare il plugin. Vedere Plugin sources
description string Mostrato negli elenchi e nei dettagli di /plugin
version string Stringa di versione per il plugin. Quando plugin.json imposta anche version, plugin.json ha la precedenza e claude plugin validate avverte. Vedere Plugin loading reference
category string Categoria libera per organizzare il catalogo
tags array of strings Tag liberi per la ricerca
strict boolean Predefinito true. Se plugin.json è la fonte definitiva per i componenti del plugin. Vedere Strict mode
relevance object Segnali che dicono a Claude Code quando suggerire il plugin. Vedere Recommend plugins for your org
dependencies array Plugin che devono essere abilitati affinché questo funzioni. Ogni elemento è "name", "name@marketplace" o un oggetto. Vedere Plugin dependencies
defaultEnabled boolean Predefinito true. Se il plugin inizia abilitato quando l'utente non lo ha impostato in enabledPlugins. Il valore della voce ha la precedenza su plugin.json
displayName string Nome leggibile mostrato nell'interfaccia utente. Quando né la voce né il plugin.json del plugin ne impostano uno, gli utenti vedono il name del plugin
metadata object Oggetto libero per i propri campi. Claude Code non lo legge. Richiede Claude Code v2.1.222 o successivo
headers object Intestazioni HTTP che Claude Code invia quando scarica l'archivio di questa voce. Un'intestazione impostata qui sostituisce un'intestazione con lo stesso nome dalla headers della sorgente del marketplace. Richiede Claude Code v2.1.238 o successivo
headersHelper string Comando che stampa le intestazioni di download dell'archivio di questa voce come un oggetto JSON, per una credenziale che scade. La voce deve anche impostare "strict": false. Richiede Claude Code v2.1.238 o successivo. Vedere Authenticate archive downloads

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.

strict plugin.json Entry component fields Result
any absent any La voce è il manifesto
true, il predefinito present any plugin.json è l'autorità. Claude Code aggiunge i campi componenti della voce a esso, tranne hooks, i cui matcher sostituiscono quelli del manifesto per evento
false present none plugin.json è il manifesto, come con true
false present one or more Conflitto. Il plugin non riesce a caricarsi con Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components

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.

Type Fields Notes
Relative path the string itself Una directory all'interno del marketplace, risolta dalla radice del marketplace. Deve iniziare con ./, a meno che non si scriva un nome bare sotto metadata.pluginRoot. "." da solo significa la radice stessa
github repo, ref, sha Repository GitHub in forma owner/repo
url url, ref, sha Qualsiasi repository git per URL
git-subdir url, path, ref, sha Una sottodirectory di un repository git, recuperata con un clone parziale sparse
npm package, version, registry Pacchetto npm, recuperato con il client npm e decompresso senza eseguire script di installazione
archive url, sha256 Archivio Zip su HTTPS. Richiede Claude Code v2.1.224 o successivo
command command, timeout, mode Directory stampata da un comando che Claude Code esegue sulla macchina dell'utente. Richiede Claude Code v2.1.229 o successivo

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.

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:

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

Type name As a marketplace source As a plugin source
url Un collegamento diretto a un file marketplace.json, con campi url, headers e headersHelper Un repository git da clonare, con campi url, ref e sha
git Un repository git da clonare, con campi url, ref, path e sparsePaths Non esiste
github Un repository GitHub, con campi repo, ref, path e sparsePaths Un repository GitHub, con campi repo, ref e sha, e nessun path

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.

Type Fields marketplace add input extraKnownMarketplaces strictKnownMarketplaces blockedMarketplaces
url url, headers, headersHelper Un URL http:// o https:// che non corrisponde a una forma git Carica Consente lo stesso URL Blocca lo stesso URL
github repo, ref, path, sparsePaths owner/repo, owner/repo@ref o owner/repo#ref Carica Consente lo stesso repo, ref e path. repo può essere owner/* Blocca lo stesso e un URL git allo stesso repository
git url, ref, path, sparsePaths Un URL user@host:path, o un URL https:// che termina in .git, contiene /_git/ o nomina un repository github.com o gitlab.com. #ref fissa un ref Carica Consente lo stesso URL, ref e path Blocca lo stesso e altre ortografie dello stesso repository github.com
npm package Non prodotto Non riesce a caricarsi: NPM marketplace sources not yet implemented Analizza ma non corrisponde a nulla, perché nulla registra un marketplace npm Analizza ma non corrisponde a nulla
file path Un percorso a un file .json Carica Consente lo stesso percorso Blocca lo stesso percorso
directory path Un percorso a una directory Carica Consente lo stesso percorso Blocca lo stesso percorso
settings name, plugins, owner Non prodotto Carica Consente una voce con lo stesso name e plugins identici Blocca lo stesso name
skills-dir none Non prodotto Non riesce a caricarsi: Unsupported marketplace source type Mantiene il caricamento dei plugin della directory delle competenze mentre è impostata un'allowlist. Vedere Source values valid only in policy lists Interrompe il caricamento dei plugin della directory delle competenze
hostPattern hostPattern Non prodotto Non riesce a caricarsi: Unsupported marketplace source type Consente sorgenti github, git e url il cui host corrisponde Blocca quelle sorgenti
pathPattern pathPattern Non prodotto Non riesce a caricarsi: Unsupported marketplace source type Consente sorgenti file e directory il cui path corrisponde Blocca quelle sorgenti

Fields by type

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

Field Types Description
url url Collegamento al file marketplace.json. Claude Code scarica solo quel file, quindi i plugin del marketplace non possono utilizzare sorgenti di percorso relativo
url git Il repository git da clonare
headers url Mappa di intestazioni HTTP che Claude Code invia con il recupero, per host autenticati
headersHelper url Comando che stampa intestazioni i cui valori sono troppo brevi per essere elencati in headers. Richiede Claude Code v2.1.238 o successivo. Vedere Authenticate archive downloads
repo github In marketplace add e extraKnownMarketplaces, repo deve nominare un repository. marketplace add rifiuta owner/* come scorciatoia owner/repo non valida; in extraKnownMarketplaces Claude Code la prende letteralmente e il clone non riesce
ref github, git Ramo o tag. Predefinito al ramo predefinito del repository
path github, git Il percorso del file marketplace all'interno del repository. Predefinito a .claude-plugin/marketplace.json
path file Il file marketplace stesso. Claude Code lo legge in posizione e prende la directory due livelli su come radice del marketplace, quindi mantenere il file in <root>/.claude-plugin/marketplace.json
path directory La radice del marketplace, la directory che contiene .claude-plugin/marketplace.json
sparsePaths github, git Array di directory per un checkout sparse, come [".claude-plugin", "plugins"]. claude plugin marketplace add --sparse lo imposta
skipLfs github, git Accettato e non ha effetto. Vedere Keep plugin files out of Git LFS
name settings Deve essere uguale alla chiave extraKnownMarketplaces e non può essere un nome riservato
plugins settings Il catalogo inline, senza file ospitato. Ogni elemento accetta name, source, description, version, strict, headers e headersHelper. Scrivere la source di ogni elemento come tipo di oggetto, perché un percorso relativo non ha repository da cui risolversi

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.

Message Level Field
Marketplace must have a name Error name è vuoto
Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace") Error name
Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "." Error name
Marketplace name impersonates an official Anthropic/Claude marketplace Error name. Vedere Reserved names
Marketplace name cannot contain control or bidirectional-formatting characters Error name contiene un carattere di controllo, come un escape o una nuova riga, o un carattere di formattazione bidirezionale Unicode
Marketplace name "inline" is reserved for --plugin-dir session plugins, e le varianti builtin, skills-dir, synced, claude-plugin-test, npm, pip, uv, cargo, github e gh Error name
Author name cannot be empty Error owner.name
Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin") Error plugins[i].name
Plugin name cannot contain control or bidirectional-formatting characters Error plugins[i].name
Duplicate plugin name "x" found in marketplace Error Due voci condividono un name
plugins.i.source: Invalid input Error La source della voce non corrisponde a nessun tipo. Vedere Invalid input on a source
plugins[i].source: Path contains "..": <path> Error Una source relativa che sfugge dalla radice del marketplace
source.source: 'unsupported' is a parse-time placeholder and cannot be authored Error plugins[i].source
Plugin "x" sets headersHelper but is not "strict": false Error plugins[i].headersHelper, su una voce archive
chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null Error renames.<old>
target "x" is not a valid plugin name (PluginIdSchema) Error renames.<old>
Unknown field 'x'. Claude Code ignores it at load time. Warning La chiave denominata al livello superiore, sotto metadata, in una voce, o sotto la relevance di una voce
Marketplace has no plugins defined Warning plugins è vuoto
Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry. Warning plugins[i].headers o plugins[i].headersHelper, su una voce la cui source non è archive
Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin Warning plugins[i].source.sha256
Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time. Warning plugins[i].headers.<name>
Local source "x" is or traverses a symlink, so <path> was not read Warning plugins[i].source
No marketplace description provided. Adding a description helps users understand what this marketplace offers Warning description
Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins Warning plugins[i].version, su una voce di percorso relativo
'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time. Warning plugins[i].relevance
'metadata' must be a free-form object; got <type>. It will be ignored at load time. Warning plugins[i].metadata
'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time. Warning plugins[i].experimental
Marketplace name "x" is reserved in Claude Desktop Warning name è org, org-provisioned o unknown. Claude Desktop rifiuta il marketplace
Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) Warning name. Claude Desktop rifiuta il marketplace
Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars) Warning plugins[i].name. Claude Desktop scarta la voce

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