Marketplace reference

• 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

​

Reserved names

• 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

​

Plugin entries

​

How an entry combines with plugin.json

• 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

​

Display fields

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

​

Strict mode

​

Plugin sources

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

​

Relative path plugin source

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

• 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

• 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

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

​

url plugin source

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

​

git-subdir plugin source

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

​

npm plugin source

• 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

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

​

archive plugin source

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

​

command plugin source

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

​

What the command must do

• 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

• 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

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

• 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

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

​

Fields by type

​

Source values valid only in policy lists

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

​

Source objects in settings

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

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

​

Validation messages

​

Invalid input on a source

• 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

​

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