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:

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.
Creazione di un file marketplace: definisci un marketplace.json che elenca i tuoi plugin e dove trovarli. Vedi Crea il file marketplace.
Ospita il marketplace: esegui il push su GitHub, GitLab o un altro host git. Vedi Ospita e distribuisci marketplace.
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.

Crea la struttura delle directory

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

Crea la skill

Crea un file SKILL.md che definisce cosa fa la skill 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.

Crea il manifest del plugin

Crea un file plugin.json che descrive il plugin. Il manifest va nella directory .claude-plugin/.

{
"name": "quality-review-plugin",
"description": "Aggiunge una skill quality-review per revisioni rapide del codice",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

Crea il file marketplace

Crea il catalogo marketplace che elenca il tuo plugin.

{
"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"
}
]
}

Aggiungi e installa

Dalla directory che contiene my-marketplace, avvia Claude Code ed esegui i seguenti comandi. Il comando install apre una vista dei dettagli del plugin dove selezioni un ambito di installazione per confermare l'installazione. Controlla il riepilogo dell'installazione: se riporta Run /reload-plugins to activate., esegui quel comando.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

Provalo

Seleziona del codice nel tuo editor ed esegui la tua nuova skill. Le skill dei plugin sono associate allo spazio dei nomi del nome del plugin.

/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

Campo	Tipo	Descrizione	Esempio
`name`	string	Identificatore del marketplace in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: quando aggiungono un secondo marketplace con lo stesso nome, Claude Code sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo `marketplace.json`.	`"acme-tools"`
`owner`	object	Informazioni sul manutentore del marketplace (vedi i campi di seguito)
`plugins`	array	Elenco dei plugin disponibili	Vedi di seguito

Note

Nomi riservati: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, healthcare. Anche i nomi che impersonano marketplace ufficiali, come official-claude-plugins o anthropic-plugins-v2, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.

Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è registrato da una fonte non attendibile. Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, first-party-plugins e healthcare non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi.

Campi del proprietario

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome del manutentore o del team
`email`	string	No	Email di contatto per il manutentore
`url`	string	No	Sito web, profilo GitHub o URL dell'organizzazione

Campi opzionali

Campo	Tipo	Descrizione
`$schema`	string	URL dello schema JSON per l'autocompletamento dell'editor e la convalida. Claude Code ignora questo campo al momento del caricamento.
`description`	string	Breve descrizione del marketplace
`version`	string	Versione del manifest del marketplace
`metadata.pluginRoot`	string	Directory che Claude Code risolve sotto i nomi di fonte del plugin bare. Vedi Percorsi relativi. Richiede Claude Code v2.1.239 o successivo.
`allowCrossMarketplaceDependenciesOn`	array	Altri marketplace su cui i plugin in questo marketplace possono dipendere. Le dipendenze da un marketplace non elencato qui sono bloccate all'installazione. Vedi Dipendi da un plugin di un altro marketplace.
`renames`	object	Mappa da un precedente `name` del plugin al suo nome attuale, o a `null` se il plugin è stato rimosso. Consente agli utenti esistenti di migrare automaticamente quando rinomini o rimuovi una voce in `plugins`. Vedi Rinominare o rimuovere un plugin. Richiede Claude Code v2.1.193 o successivo.

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

Campo	Tipo	Descrizione
`name`	string	Identificatore del plugin in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano (ad esempio, `/plugin install my-plugin@marketplace`).
`source`	string\|object	Da dove recuperare il plugin (vedi Plugin sources di seguito)

Campi di plugin opzionali

Campi di metadati standard:

Campo	Tipo	Descrizione
`displayName`	string	Nome leggibile mostrato nelle superfici dell'interfaccia utente. Ritorna a `name` quando omesso. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca.
`description`	string	Breve descrizione del plugin
`version`	string	Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una `command` source non è bloccato da nessuno dei due campi. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in version management.
`author`	object	Informazioni sull'autore del plugin (`name` obbligatorio; `email` e `url` opzionali)
`homepage`	string	URL della homepage o della documentazione del plugin
`repository`	string	URL del repository del codice sorgente
`license`	string	Identificatore di licenza SPDX (ad esempio, MIT, Apache-2.0)
`keywords`	array	Tag per la scoperta e la categorizzazione dei plugin
`metadata`	object	Oggetto in formato libero per i tuoi campi personalizzati, come dati di diritto o catalogo. Claude Code non lo legge. Prima della v2.1.222, `claude plugin validate` segnalava la chiave come campo non riconosciuto.
`category`	string	Categoria del plugin per l'organizzazione
`tags`	array	Tag per la ricercabilità
`strict`	boolean	Controlla se `plugin.json` è l'autorità per le definizioni dei componenti (predefinito: true). Vedi Strict mode di seguito.
`relevance`	object	Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi Recommend plugins for your org.
`defaultEnabled`	boolean	Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi Default enablement.

Campi di configurazione dei componenti:

Campo	Tipo	Descrizione
`skills`	string\|array	Percorsi personalizzati alle directory delle skill contenenti `<name>/SKILL.md`
`commands`	string\|array	Percorsi personalizzati ai file di skill flat `.md` o alle directory
`agents`	string\|array	Percorsi personalizzati ai file degli agenti
`hooks`	string\|object	Configurazione degli hook personalizzati o percorso al file degli hook
`mcpServers`	string\|object	Configurazioni del server MCP o percorso alla configurazione MCP
`lspServers`	string\|object	Configurazioni del server LSP o percorso alla configurazione LSP

Campi di autenticazione dell'archivio:

Imposta questi quando la voce ha una archive source su un server che richiede credenziali.

Campo	Tipo	Descrizione
`headers`	object	Intestazioni HTTP che Claude Code invia quando scarica l'archivio di questa voce. Sostituisce le intestazioni del marketplace con lo stesso nome. Richiede Claude Code v2.1.238 o successivo.
`headersHelper`	string	Comando che stampa le intestazioni HTTP per il download dell'archivio di questa voce come un singolo oggetto JSON, per una credenziale che scade. Vedi Authenticate archive downloads. La voce deve anche impostare `"strict": false`. Richiede Claude Code v2.1.238 o successivo.

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.

Source	Tipo	Campi	Note
Percorso relativo	`string` (ad es. `"./my-plugin"`)	nessuno	Directory locale all'interno del repository del marketplace. Deve iniziare con `./`, a meno che non scrivi un bare name sotto `metadata.pluginRoot`. Claude Code risolve il percorso relativamente alla radice del marketplace, non alla directory `.claude-plugin/`
`github`	object	`repo`, `ref?`, `sha?`
`url`	object	`url`, `ref?`, `sha?`	Fonte URL Git
`git-subdir`	object	`url`, `path`, `ref?`, `sha?`	Sottodirectory all'interno di un repository git. Clona in modo sparso per ridurre al minimo la larghezza di banda per i monorepo
`npm`	object	`package`, `version?`, `registry?`	Installato tramite `npm install`
`archive`	object	`url`, `sha256?`	Archivio zip scaricato tramite HTTPS. Funziona senza git o npm sulla macchina dell'utente. Richiede Claude Code v2.1.224 o successivo
`command`	object	`command`, `timeout?`, `mode?`	Directory del plugin prodotta dall'esecuzione di un comando locale, rieseguita una volta per sessione per raccogliere i cambiamenti. Richiede Claude Code v2.1.229 o successivo

Note

Marketplace sources vs plugin sources: Questi sono concetti diversi che controllano cose diverse.

Marketplace source: dove recuperare il catalogo marketplace.json stesso. Impostato quando gli utenti eseguono /plugin marketplace add o nelle impostazioni extraKnownMarketplaces. Le marketplace sources basate su git supportano ref (branch/tag) ma non sha.
Plugin source: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo source di ogni voce di plugin all'interno di marketplace.json. Le plugin sources basate su git supportano sia ref (branch/tag) che sha (commit esatto).

Ad esempio, un marketplace ospitato in acme-corp/plugin-catalog (marketplace source) può elencare un plugin recuperato da acme-corp/code-formatter (plugin source). La marketplace source e la plugin source puntano a repository diversi e sono fissate indipendentemente.

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.

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

Campo	Tipo	Descrizione
`repo`	string	Obbligatorio. Repository GitHub nel formato `owner/repo`
`ref`	string	Opzionale. Branch o tag Git (predefinito al branch predefinito del repository)
`sha`	string	Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta

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

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL completo del repository git (`https://` o `git@`). Il suffisso `.git` è opzionale, quindi gli URL di Azure DevOps e AWS CodeCommit senza il suffisso funzionano
`ref`	string	Opzionale. Branch o tag Git (predefinito al branch predefinito del repository)
`sha`	string	Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta

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

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL del repository Git, scorciatoia GitHub `owner/repo` o URL SSH
`path`	string	Obbligatorio. Percorso della sottodirectory all'interno del repo contenente il plugin (ad esempio, `"tools/claude-plugin"`)
`ref`	string	Opzionale. Branch o tag Git (predefinito al branch predefinito del repository)
`sha`	string	Opzionale. SHA del commit git completo a 40 caratteri per fissare a una versione esatta

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

Campo	Tipo	Descrizione
`package`	string	Obbligatorio. Nome del pacchetto o pacchetto con scope (ad esempio, `@org/plugin`)
`version`	string	Opzionale. Versione o intervallo di versione (ad esempio, `2.1.0`, `^2.0.0`, `~1.5.0`)
`registry`	string	Opzionale. URL del registro npm personalizzato. Predefinito al registro npm del sistema (tipicamente npmjs.org)

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:

Campo	Tipo	Descrizione
`url`	string	Obbligatorio. URL HTTPS dell'archivio zip. Claude Code rifiuta gli URL `http://`, insieme agli host loopback, link-local e cloud-metadata. Ogni hop di reindirizzamento deve soddisfare le stesse regole, o Claude Code rifiuta il download
`sha256`	string	Opzionale. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'install su una mancata corrispondenza

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:

Posto	Download che ottengono le intestazioni	Quando Claude Code esegue un `headersHelper` impostato lì
Marketplace `url` source	Download di archivi sull'origine dell'URL del marketplace, ovvero lo stesso schema, host e porta	Prima di ogni fetch del `marketplace.json` del marketplace e prima di ogni download di archivio su quell'origine. Claude Code riutilizza l'output di un'esecuzione per fino a 60 secondi
Voce del plugin	Solo il download di quella voce	Solo quando un utente installa o aggiorna quel singolo plugin da solo e accetta 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:

File di impostazioni	Quando Claude Code esegue il comando
Impostazioni utente, un file `--settings` o un file di impostazioni gestite sulla macchina	Senza chiedere, incluso durante un aggiornamento del marketplace in background
Un `.claude/settings.json` o `.claude/settings.local.json` di un progetto	Solo dopo che l'utente accetta la workspace trust dialog per quella cartella stessa. Una sessione `-p` o SDK non conta come accettarla, e nemmeno la fiducia concessa a una cartella padre
Impostazioni gestite dal server	Solo dopo che l'utente approva le impostazioni consegnate nella security approval dialog

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:

Campo	Tipo	Descrizione
`command`	string	Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce 0. Deve essere ASCII stampabile, al massimo 500 caratteri, senza sequenze di quattro o più spazi, in modo che gli utenti possano rivedere l'intero comando che gli viene chiesto di accettare
`timeout`	number	Opzionale. Numero intero di secondi da aspettare per il comando prima di rinunciare (predefinito: 60, massimo: 600)
`mode`	string	Opzionale. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi Copy mode and link mode

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

Valore	Comportamento
`true` (predefinito)	`plugin.json` è l'autorità. La voce del marketplace può integrarla con componenti aggiuntivi e entrambe le fonti vengono unite.
`false`	La voce del marketplace è la definizione completa. Se il plugin ha anche un `plugin.json` che dichiara componenti, è un conflitto e il plugin non riesce a caricarsi.

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:

Crea un repository: configura un nuovo repository per il tuo marketplace
Aggiungi il file marketplace: crea .claude-plugin/marketplace.json con le tue definizioni di plugin
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:

Provider	Forma URL riscritta
GitHub	`https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins`
GitLab	`https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins`
Bitbucket	`https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins`

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:

Valore	Comportamento
Non definito (predefinito)	Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace
Array vuoto `[]`	Blocco completo. Blocca ogni origine di marketplace, incluso il marketplace ufficiale di Anthropic
Elenco di fonti	Elenco di autorizzazione applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce

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.

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:

Opzione	Descrizione	Predefinito
`--scope <scope>`	Dove dichiarare il marketplace: `user`, `project` o `local`. Vedi Plugin installation scopes	`user`
`--sparse <paths...>`	Limita il checkout a directory specifiche tramite git sparse-checkout. Utile per i monorepo

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:

Opzione	Descrizione
`--json`	Output come JSON

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:

Opzione	Descrizione	Predefinito
`--scope <scope>`	Limita la rimozione a un singolo ambito di impostazioni: `user`, `project` o `local`. Vedi Plugin installation scopes. Se omesso, la dichiarazione viene rimossa da ogni ambito modificabile. Se fornito, solo la dichiarazione di quell'ambito viene rimossa; lo stato condiviso, la cache e i dati dei plugin installati vengono preservati quando il marketplace è ancora dichiarato in un altro ambito	(tutti gli ambiti)

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:

Errore	Causa	Soluzione
`No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json`	La directory che hai denominato non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file di skill, agente o comando da verificare	Esegui dalla radice del marketplace, o crea `.claude-plugin/marketplace.json` con i campi obbligatori
`Invalid JSON syntax: Unexpected token...`	Errore di sintassi JSON in marketplace.json	Controlla le virgole mancanti, le virgole extra o le stringhe non quotate
`Duplicate plugin name "x" found in marketplace`	Due plugin condividono lo stesso nome	Dai a ogni plugin un valore `name` univoco
`plugins[0].source: Path contains ".."`	Il percorso di origine contiene `..`	Usa percorsi relativi alla radice del marketplace senza `..`. Vedi Percorsi relativi
`Marketplace name cannot contain control or bidirectional-formatting characters`	Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline	Rimuovi il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace`
`Plugin name cannot contain control or bidirectional-formatting characters`	Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline	Rimuovi il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo

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:

Per verificare	Esegui	Claude Code controlla
Un plugin che ha un `plugin.json`	`claude plugin validate ./plugins/my-plugin`	`plugin.json`, `hooks/hooks.json`, e le directory `skills`, `agents`, e `commands` alla radice del plugin
Una directory di skill, agenti o comandi, come un plugin che non ha ancora un `plugin.json`	`claude plugin validate .claude/skills`, `~/.claude/agents`, o `./my-plugin/agents`	Ogni file di skill, agente o comando in quella directory
Una cartella il cui skill è il suo `SKILL.md` radice	`claude plugin validate ./skills`, denominando la directory `skills` che contiene la cartella	Il `SKILL.md` radice di ogni cartella. La directory contenente deve essere denominata `skills`; una cartella sotto un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice
Le tre directory di un progetto contemporaneamente	`claude plugin validate .claude`, o la radice del progetto quando non ha un manifest `.claude-plugin/`	`.claude/skills`, `.claude/agents`, e `.claude/commands`
Le tue directory a livello di utente	`claude plugin validate ~/.claude`	`~/.claude/skills`, `~/.claude/agents`, e `~/.claude/commands`

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 errori "path not found".

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

plugin-marketplaces.md +467 −76

63 {63 {

64 "name": "quality-review-plugin",64 "name": "quality-review-plugin",

65 "description": "Aggiunge una skill quality-review per revisioni rapide del codice",65 "description": "Aggiunge una skill quality-review per revisioni rapide del codice",

~~66 "version": "1.0.0"~~66 "version": "1.0.0",

67 "author": {

68 "name": "Your Name"

69 }

67 }70 }

68 ```71 ```

69 72

70 <Note>73 <Note>

71 Impostare `version` significa che gli utenti ricevono aggiornamenti solo quando modifichi questo campo, quindi incrementalo ad ogni rilascio. Se ometti `version` e ospiti questo marketplace in git, ogni commit conta automaticamente come una nuova versione. Vedi [Risoluzione della versione](#version-resolution-and-release-channels) per scegliere l'approccio giusto.74 Impostare `version` significa che gli utenti ricevono aggiornamenti solo quando modifichi questo campo, quindi incrementalo ad ogni rilascio. Un plugin con una [`command` source](#command-sources) non è bloccato da questo campo. Se ometti `version`, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management).

72 </Note>75 </Note>

73 </Step>76 </Step>

74 77

93 </Step>96 </Step>

94 97

95 <Step title="Aggiungi e installa">98 <Step title="Aggiungi e installa">

~~96 Aggiungi il marketplace e installa il plugin.~~99 Dalla directory che contiene `my-marketplace`, avvia Claude Code ed esegui i seguenti comandi. Il comando install apre una vista dei dettagli del plugin dove selezioni un ambito di installazione per confermare l'installazione. Controlla il riepilogo dell'installazione: se riporta `Run /reload-plugins to activate.`, esegui quel comando.

97 100

98 ```shell theme={null}101 ```shell theme={null}

99 /plugin marketplace add ./my-marketplace102 /plugin marketplace add ./my-marketplace

113Per saperne di più su cosa possono fare i plugin, inclusi hooks, agenti, server MCP e server LSP, vedi [Plugins](/docs/it/plugins).116Per saperne di più su cosa possono fare i plugin, inclusi hooks, agenti, server MCP e server LSP, vedi [Plugins](/docs/it/plugins).

114 117

115<Note>118<Note>

116 **Come vengono installati i plugin**: Quando gli utenti installano un plugin, Claude Code copia la directory del plugin in una posizione cache. Ciò significa che i plugin non possono fare riferimento a file al di fuori della loro directory utilizzando percorsi come `../shared-utils`, perché quei file non verranno copiati.119 **Come vengono installati i plugin**: quando gli utenti installano un plugin, Claude Code copia la directory del plugin in una posizione cache, ad eccezione di una [`command` source in link mode](#copy-mode-and-link-mode), che viene utilizzata al suo posto. I plugin copiati non possono fare riferimento a file al di fuori della loro directory utilizzando percorsi come `../shared-utils`, perché quei file non verranno copiati.

117 120

118 Se hai bisogno di condividere file tra plugin, usa symlink. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per i dettagli.121 Se hai bisogno di condividere file tra plugin, usa symlink. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per i dettagli.

119</Note>122</Note>

164</h3>167</h3>

165 168

167| :-------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |170| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |

168| `name` | string | Identificatore del marketplace (kebab-case, senza spazi). Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: aggiungere un secondo marketplace con lo stesso nome sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |171| `name` | string | Identificatore del marketplace in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano plugin (ad esempio, `/plugin install my-tool@your-marketplace`). Ogni utente può registrare un solo marketplace per nome: quando aggiungono un secondo marketplace con lo stesso nome, Claude Code sostituisce il primo. Per pubblicare più plugin sotto un nome di marketplace, elencarli tutti in un singolo [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |

171 174

180</h3>183</h3>

181 184

183| :------ | :----- | :----------- | :----------------------------------- |186| :------ | :----- | :----------- | :------------------------------------------------- |

189| `url` | string | No | Sito web, profilo GitHub o URL dell'organizzazione |

186 190

187<h3 id="optional-fields">191<h3 id="optional-fields">

188 Campi opzionali192 Campi opzionali

196| `metadata.pluginRoot` | string | Directory di base anteposta ai percorsi di fonte del plugin relativo (ad esempio, `"./plugins"` ti consente di scrivere `"source": "formatter"` invece di `"source": "./plugins/formatter"`) |200| `metadata.pluginRoot` | string | Directory che Claude Code risolve sotto i nomi di fonte del plugin bare. Vedi [Percorsi relativi](#relative-paths). Richiede Claude Code v2.1.239 o successivo. |

197| `allowCrossMarketplaceDependenciesOn` | array | Altri marketplace su cui i plugin in questo marketplace possono dipendere. Le dipendenze da un marketplace non elencato qui sono bloccate all'installazione. Vedi [Dipendi da un plugin di un altro marketplace](/docs/it/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |201| `allowCrossMarketplaceDependenciesOn` | array | Altri marketplace su cui i plugin in questo marketplace possono dipendere. Le dipendenze da un marketplace non elencato qui sono bloccate all'installazione. Vedi [Dipendi da un plugin di un altro marketplace](/docs/it/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |

198| `renames` | object | Mappa da un precedente `name` del plugin al suo nome attuale, o a `null` se il plugin è stato rimosso. Consente agli utenti esistenti di migrare automaticamente quando rinomini o rimuovi una voce in `plugins`. Vedi [Rinominare o rimuovere un plugin](#rename-or-remove-a-plugin). Richiede Claude Code v2.1.193 o successivo. |202| `renames` | object | Mappa da un precedente `name` del plugin al suo nome attuale, o a `null` se il plugin è stato rimosso. Consente agli utenti esistenti di migrare automaticamente quando rinomini o rimuovi una voce in `plugins`. Vedi [Rinominare o rimuovere un plugin](#rename-or-remove-a-plugin). Richiede Claude Code v2.1.193 o successivo. |

199 203

203 Voci di plugin207 Voci di plugin

204</h2>208</h2>

205 209

206Ogni voce di plugin nell'array `plugins` descrive un plugin e dove trovarlo. Puoi includere qualsiasi campo dallo [schema del manifest del plugin](/docs/it/plugins-reference#plugin-manifest-schema), come `description`, `version`, `author`, `commands` e `hooks`, più questi campi specifici del marketplace: `source`, `category`, `tags`, `strict` e `relevance`.210Ogni voce di plugin nell'array `plugins` descrive un plugin e dove trovarlo. Puoi includere qualsiasi campo dallo [schema del manifest del plugin](/docs/it/plugins-reference#plugin-manifest-schema), come `description`, `version`, `author`, `commands` e `hooks`, più questi campi specifici del marketplace: `source`, `category`, `tags`, `strict`, `relevance`, `headers` e `headersHelper`.

207 211

208<h3 id="required-fields-2">212<h3 id="required-fields-2">

209 Campi obbligatori213 Campi obbligatori

210</h3>214</h3>

211 215

213| :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |217| :------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

214| `name` | string | Identificatore del plugin (kebab-case, senza spazi). Questo è pubblico: gli utenti lo vedono quando installano (ad esempio, `/plugin install my-plugin@marketplace`). |218| `name` | string | Identificatore del plugin in kebab-case, senza spazi, caratteri di controllo o caratteri di formattazione bidirezionale. Questo è pubblico: gli utenti lo vedono quando installano (ad esempio, `/plugin install my-plugin@marketplace`). |

216 220

217<h3 id="optional-plugin-fields">221<h3 id="optional-plugin-fields">

221**Campi di metadati standard:**225**Campi di metadati standard:**

222 226

224| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |228| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

225| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Ritorna a `name` quando omesso. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. Richiede Claude Code v2.1.143 o successivo. |229| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Ritorna a `name` quando omesso. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |

227| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Ometti per tornare allo SHA del commit git. Vedi [Version resolution](#version-resolution-and-release-channels). |231| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una [`command` source](#command-sources) non è bloccato da nessuno dei due campi. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |

237| `metadata` | object | Oggetto in formato libero per i tuoi campi personalizzati, come dati di diritto o catalogo. Claude Code non lo legge. Prima della v2.1.222, `claude plugin validate` segnalava la chiave come campo non riconosciuto. |

236| `relevance` | object | Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi [Recommend plugins for your org](/docs/it/plugin-relevance). Richiede Claude Code v2.1.152 o successivo. |241| `relevance` | object | Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi [Recommend plugins for your org](/docs/it/plugin-relevance). |

237| `defaultEnabled` | boolean | Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi [Default enablement](/docs/it/plugins-reference#default-enablement). Richiede Claude Code v2.1.154 o successivo. |242| `defaultEnabled` | boolean | Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi [Default enablement](/docs/it/plugins-reference#default-enablement). |

238 243

239**Campi di configurazione dei componenti:**244**Campi di configurazione dei componenti:**

240 245

249 254

255**Campi di autenticazione dell'archivio:**

256

257Imposta questi quando la voce ha una [`archive` source](#zip-archives) su un server che richiede credenziali.

258

259| Campo | Tipo | Descrizione |

260| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

261| `headers` | object | Intestazioni HTTP che Claude Code invia quando scarica l'archivio di questa voce. Sostituisce le intestazioni del marketplace con lo stesso nome. Richiede Claude Code v2.1.238 o successivo. |

262| `headersHelper` | string | Comando che stampa le intestazioni HTTP per il download dell'archivio di questa voce come un singolo oggetto JSON, per una credenziale che scade. Vedi [Authenticate archive downloads](#authenticate-archive-downloads). La voce deve anche impostare [`"strict": false`](#strict-mode). Richiede Claude Code v2.1.238 o successivo. |

263

250<h2 id="plugin-sources">264<h2 id="plugin-sources">

251 Plugin sources265 Plugin sources

252</h2>266</h2>

253 267

254Le 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`.268Le 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`.

255 269

256Dopo che Claude Code clona o scarica un plugin sulla macchina locale, lo copia nella cache del plugin locale con versione in `~/.claude/plugins/cache`.270Claude 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](#copy-mode-and-link-mode), che Claude Code utilizza al suo posto. Claude Code inoltre [installa le dipendenze del pacchetto Node.js idonee del plugin](/docs/it/plugins-reference#node-js-package-dependencies) nella copia memorizzata nella cache.

257 271

259| ----------------- | --------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |273| ----------------- | --------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

260| Percorso relativo | `string` (ad es. `"./my-plugin"`) | nessuno | Directory locale all'interno del repository del marketplace. Deve iniziare con `./`. Risolto relativamente alla radice del marketplace, non alla directory `.claude-plugin/` |274| Percorso relativo | `string` (ad es. `"./my-plugin"`) | nessuno | Directory locale all'interno del repository del marketplace. Deve iniziare con `./`, a meno che non scrivi un [bare name sotto `metadata.pluginRoot`](#relative-paths). Claude Code risolve il percorso relativamente alla radice del marketplace, non alla directory `.claude-plugin/` |

280| `command` | object | `command`, `timeout?`, `mode?` | Directory del plugin prodotta dall'esecuzione di un comando locale, rieseguita una volta per sessione per raccogliere i cambiamenti. Richiede Claude Code v2.1.229 o successivo |

265 281

266<Note>282<Note>

267 **Marketplace sources vs plugin sources**: Questi sono concetti diversi che controllano cose diverse.283 **Marketplace sources vs plugin sources**: Questi sono concetti diversi che controllano cose diverse.

268 284

269 * **Marketplace source**: dove recuperare il catalogo `marketplace.json` stesso. Impostato quando gli utenti eseguono `/plugin marketplace add` o nelle impostazioni `extraKnownMarketplaces`. Supporta `ref` (branch/tag) ma non `sha`.285 * **Marketplace source**: dove recuperare il catalogo `marketplace.json` stesso. Impostato quando gli utenti eseguono `/plugin marketplace add` o nelle impostazioni `extraKnownMarketplaces`. Le marketplace sources basate su git supportano `ref` (branch/tag) ma non `sha`.

270 * **Plugin source**: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo `source` di ogni voce di plugin all'interno di `marketplace.json`. Supporta sia `ref` (branch/tag) che `sha` (commit esatto).286 * **Plugin source**: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo `source` di ogni voce di plugin all'interno di `marketplace.json`. Le plugin sources basate su git supportano sia `ref` (branch/tag) che `sha` (commit esatto).

271 287

272 Ad esempio, un marketplace ospitato in `acme-corp/plugin-catalog` (marketplace source) può elencare un plugin recuperato da `acme-corp/code-formatter` (plugin source). La marketplace source e la plugin source puntano a repository diversi e sono fissate indipendentemente.288 Ad esempio, un marketplace ospitato in `acme-corp/plugin-catalog` (marketplace source) può elencare un plugin recuperato da `acme-corp/code-formatter` (plugin source). La marketplace source e la plugin source puntano a repository diversi e sono fissate indipendentemente.

273</Note>289</Note>

276 292

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

278 294

295Se distribuisci plugin tramite **Organization settings > Plugins**, solo alcuni tipi di source sono consentiti. Vedi [Distribute through organization settings](#distribute-through-organization-settings).

296

279<h3 id="relative-paths">297<h3 id="relative-paths">

280 Percorsi relativi298 Percorsi relativi

281</h3>299</h3>

291 309

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

293 311

312Un bare name è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere bare names invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) 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.

313

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

315

294<Note>316<Note>

295 I percorsi relativi si risolvono rispetto a una copia locale del marketplace, quindi funzionano quando gli utenti aggiungono il tuo marketplace da una fonte git o da una directory locale. Se gli utenti aggiungono il tuo marketplace tramite un URL diretto al file `marketplace.json`, i percorsi relativi non si risolveranno, perché viene scaricato solo quel file. Per la distribuzione basata su URL, usa invece GitHub, npm o fonti URL git. Vedi [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) per i dettagli.317 Claude Code risolve i percorsi relativi rispetto a una copia locale del marketplace, quindi funzionano quando gli utenti aggiungono il tuo marketplace da una fonte git o da una directory locale. Se gli utenti aggiungono il tuo marketplace tramite un URL diretto al file `marketplace.json`, i percorsi relativi non si risolveranno, perché viene scaricato solo quel file. Per la distribuzione basata su URL, usa invece qualsiasi altra [plugin source](#plugin-sources). Vedi [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) per i dettagli.

296</Note>318</Note>

297 319

298<h3 id="github-repositories">320<h3 id="github-repositories">

455 477

478<h3 id="zip-archives">

479 Archivi zip

480</h3>

481

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

483

484Questa voce installa il plugin da un file zip su un server di artefatti:

485

486```json theme={null}

487{

488 "name": "my-plugin",

489 "source": {

490 "source": "archive",

491 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"

492 }

493}

494```

495

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

497

498```text theme={null}

499my-plugin.zip my-plugin.zip

500├── .claude-plugin/ └── my-plugin/

501│ └── plugin.json ├── .claude-plugin/

502└── commands/ │ └── plugin.json

503 └── commands/

504```

505

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

507

508Per fissare il file esatto, aggiungi un campo `sha256` con il digest dell'archivio:

509

510```json theme={null}

511{

512 "name": "my-plugin",

513 "source": {

514 "source": "archive",

515 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",

516 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

517 }

518}

519```

520

521Se il file scaricato non corrisponde al pin, Claude Code rifiuta l'install e segnala [`Plugin archive integrity check failed`](/docs/it/errors#plugin-archive-integrity-check-failed).

522

523Le archive sources accettano questi campi:

524

525| Campo | Tipo | Descrizione |

526| :------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

527| `url` | string | Obbligatorio. URL HTTPS dell'archivio zip. Claude Code rifiuta gli URL `http://`, insieme agli host loopback, link-local e cloud-metadata. Ogni hop di reindirizzamento deve soddisfare le stesse regole, o Claude Code rifiuta il download |

528| `sha256` | string | Opzionale. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'install su una mancata corrispondenza |

529

530Il digest `sha256` serve anche come versione del plugin quando né `plugin.json` né la voce del marketplace ne dichiara una. Vedi [Version management](/docs/it/plugins-reference#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.

531

532<h4 id="authenticate-archive-downloads">

533 Autentica i download degli archivi

534</h4>

535

536Per 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`](/docs/it/settings-reference#extraknownmarketplaces). Su Claude Code v2.1.238 o successivo, puoi impostarla sulla voce del plugin invece, accanto a `source`.

537

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

539

540Il posto che scegli decide quali download ottengono le intestazioni e quando Claude Code esegue il comando:

541

542| Posto | Download che ottengono le intestazioni | Quando Claude Code esegue un `headersHelper` impostato lì |

543| :----------------------- | :----------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

544| Marketplace `url` source | Download di archivi sull'origine dell'URL del marketplace, ovvero lo stesso schema, host e porta | Prima di ogni fetch del `marketplace.json` del marketplace e prima di ogni download di archivio su quell'origine. Claude Code riutilizza l'output di un'esecuzione per fino a 60 secondi |

545| Voce del plugin | Solo il download di quella voce | Solo quando un utente installa o aggiorna quel singolo plugin da solo e [accetta il comando](#how-users-accept-a-headershelper-command) |

546

547Dove 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`.

548

549<h5 id="add-a-headershelper-to-a-plugin-entry">

550 Aggiungi un headersHelper a una voce di plugin

551</h5>

552

553Questa 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`](#strict-mode), la voce del marketplace è la definizione completa del plugin, quindi un utente può rivedere cosa contiene il plugin prima di accettare il comando:

554

555```json theme={null}

556{

557 "name": "my-plugin",

558 "description": "Formatting commands for internal services",

559 "strict": false,

560 "commands": "./commands",

561 "source": {

562 "source": "archive",

563 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

564 },

565 "headersHelper": "/opt/bin/mint-registry-token.sh"

566}

567```

568

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

570

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

572

573<h4 id="write-the-headershelper-command">

574 Scrivi il comando headersHelper

575</h4>

576

577Che tu imposti `headersHelper` su una `url` source di un marketplace o su una voce di plugin, scrivi il comando per soddisfare questi requisiti:

578

579* **Testo del comando**: al massimo 500 caratteri di ASCII stampabile, senza una sequenza di quattro o più spazi.

580* **Output**: stampa un oggetto JSON di nomi di intestazione e valori di stringa su stdout, quindi esci con 0 entro 10 secondi.

581* **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`](/docs/it/env-vars#variables). Fornisci un percorso assoluto o un comando su `PATH`, perché un percorso relativo si risolve rispetto a quella directory, non al progetto dell'utente.

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

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

584

585Un comando che conia un token bearer stampa un oggetto come questo:

586

587```json theme={null}

588{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

589```

590

591<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

592 Quando Claude Code salta un comando headersHelper o scarta il suo output

593</h4>

594

595Claude Code non esegue un comando `headersHelper`, o scarta le intestazioni che provengono da `headers` o dall'output del comando, in queste situazioni:

596

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

598* **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`.

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

600* **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](/docs/it/settings-reference#extraknownmarketplaces) a seconda di quale file la dichiara.

601* **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](/docs/it/settings-reference#extraknownmarketplaces) allo stesso modo, e invia solo le `headers` di quel file.

602* **Le impostazioni gestite bloccano il comando**: impostare [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources) a `true` blocca i comandi `headersHelper`, e [`allowManagedHooksOnly`](/docs/it/settings-reference#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.

603

604<h4 id="how-users-accept-a-headershelper-command">

605 Come gli utenti accettano un comando headersHelper

606</h4>

607

608Un 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`](/docs/it/plugins-reference#plugin-install) per accettarlo.

609

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

611

612<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

613 Install e aggiornamenti che rifiutano il comando invece di chiedere

614</h5>

615

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

617

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

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

620

621<h5 id="when-a-marketplace-url-source’s-command-runs">

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

623</h5>

624

625Un `headersHelper` di una marketplace `url` source è dichiarato in un file di impostazioni, come una voce [`extraKnownMarketplaces`](/docs/it/settings-reference#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:

626

627| File di impostazioni | Quando Claude Code esegue il comando |

628| :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

629| Impostazioni utente, un file `--settings` o un file di impostazioni gestite sulla macchina | Senza chiedere, incluso durante un aggiornamento del marketplace in background |

630| Un `.claude/settings.json` o `.claude/settings.local.json` di un progetto | Solo dopo che l'utente accetta la [workspace trust dialog](/docs/it/permissions#what-runs-before-you-trust-a-folder) per quella cartella stessa. Una sessione `-p` o SDK non conta come accettarla, e nemmeno la fiducia concessa a una cartella padre |

631| Impostazioni gestite dal server | Solo dopo che l'utente approva le impostazioni consegnate nella [security approval dialog](/docs/it/server-managed-settings#security-approval-dialogs) |

632

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

634

635Per una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces) 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.

636

637<h3 id="command-sources">

638 Command sources

639</h3>

640

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

642

643Questa voce installa il plugin da qualsiasi directory che lo strumento stampa:

644

645```json theme={null}

646{

647 "name": "my-plugin",

648 "source": {

649 "source": "command",

650 "command": "my-tool claude-plugin-path"

651 }

652}

653```

654

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

656

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

658

659* La directory non ha contenuto di plugin al suo livello superiore, come una directory `.claude-plugin/` o una directory `skills/`, `commands/`, `agents/` o `hooks/`

660* La directory è quella in cui Claude Code è stato avviato, o una delle sue padre

661* Su Windows, il percorso è un percorso UNC

662

663Le command sources accettano questi campi:

664

665| Campo | Tipo | Descrizione |

666| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

667| `command` | string | Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce 0. Deve essere ASCII stampabile, al massimo 500 caratteri, senza sequenze di quattro o più spazi, in modo che gli utenti possano rivedere l'intero comando che gli viene chiesto di accettare |

668| `timeout` | number | Opzionale. Numero intero di secondi da aspettare per il comando prima di rinunciare (predefinito: 60, massimo: 600) |

669| `mode` | string | Opzionale. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi [Copy mode and link mode](#copy-mode-and-link-mode) |

670

671<h4 id="copy-mode-and-link-mode">

672 Copy mode and link mode

673</h4>

674

675Con il predefinito `"mode": "copy"`, Claude Code copia la directory stampata nella cache del plugin con versione e deriva la [plugin version](/docs/it/plugins-reference#version-management) 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.

676

677Imposta `"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](/docs/it/plugins-reference#node-js-package-dependencies) per un plugin in link mode, quindi stampa una directory che contiene già qualsiasi `node_modules` di cui il plugin ha bisogno.

678

679Mantieni 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](/docs/it/plugins-reference#version-management) 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.

680

681Claude Code non supporta link mode su Windows e rifiuta di installare un plugin in link mode lì. Dichiara `"mode": "copy"` invece.

682

683<h4 id="how-users-accept-the-command">

684 Come gli utenti accettano il comando

685</h4>

686

687Claude Code esegue il tuo comando sulla macchina dell'utente, quindi lega ogni esecuzione all'accettazione esplicita dell'utente:

688

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

690* 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](#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.

691* 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>`.

692

693Gli amministratori possono bloccare le command sources in tutta un'organizzazione con l'impostazione gestita [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources). Se un'organizzazione imposta [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly), Claude Code blocca le command sources per impostazione predefinita.

694

695<h4 id="when-claude-code-re-runs-the-command">

696 Quando Claude Code riesegue il comando

697</h4>

698

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

700

701* Ogni volta che l'utente installa o aggiorna il plugin

702* 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](/docs/it/discover-plugins#configure-auto-updates) del marketplace

703* All'avvio o su `/reload-plugins`, quando la versione installata di un plugin abilitato è mancante dalla cache del plugin

704

705Claude Code salta le due esecuzioni in background quando l'utente imposta [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/it/env-vars). Gli install e gli aggiornamenti espliciti eseguono comunque il comando con quella variabile impostata.

706

707Quando 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](/docs/it/plugins-reference#environment-variables). 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`](/docs/it/prompt-caching#enabling-or-disabling-a-plugin).

708

456<h3 id="advanced-plugin-entries">709<h3 id="advanced-plugin-entries">

457 Voci di plugin avanzate710 Voci di plugin avanzate

458</h3>711</h3>

508 761

509Cose importanti da notare:762Cose importanti da notare:

510 763

511* **`commands` e `agents`**: puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin.764* **`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.

512* **`${CLAUDE_PLUGIN_ROOT}`**: Usa questa variabile nelle configurazioni degli hook e del server MCP per fare riferimento ai file all'interno della directory di installazione del plugin. Questo è necessario perché i plugin vengono copiati in una posizione cache quando installati.765 * 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`](/docs/it/errors#path-escapes-plugin-directory), e carica comunque il plugin senza quel componente

766* **`${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.

513 * Vedi la [tabella di sostituzione](/docs/it/plugins-reference#environment-variables) per quali campi di configurazione la sostituiscono per tipo di server767 * Vedi la [tabella di sostituzione](/docs/it/plugins-reference#environment-variables) per quali campi di configurazione la sostituiscono per tipo di server

514 * Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti dei plugin, usa [`${CLAUDE_PLUGIN_DATA}`](/docs/it/plugins-reference#persistent-data-directory) invece768 * Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti dei plugin, usa [`${CLAUDE_PLUGIN_DATA}`](/docs/it/plugins-reference#persistent-data-directory) invece

515* **`strict: false`**: poiché è impostato su false, il plugin non ha bisogno del suo `plugin.json`. La voce del marketplace definisce tutto. Vedi [Strict mode](#strict-mode) di seguito.769* **`strict: false`**: poiché è impostato su false, il plugin non ha bisogno del suo `plugin.json`. La voce del marketplace definisce tutto. Vedi [Strict mode](#strict-mode) di seguito.

575 Repository privati829 Repository privati

576</h3>830</h3>

577 831

578Claude Code supporta l'installazione di plugin da repository privati. Per l'installazione manuale e gli aggiornamenti, 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`](/docs/it/env-vars#variables) per clonare su HTTPS invece.832Claude Code supporta l'installazione di plugin da repository privati. Se distribuisci il tuo marketplace tramite [**Organization settings > Plugins**](https://claude.ai/admin-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](#distribute-through-organization-settings) per le regole complete.

833

834<h4 id="commands-you-run">

835 Comandi che esegui

836</h4>

837

838Quando 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`](/docs/it/env-vars#variables) per clonare su HTTPS invece.

579 839

580Gli aggiornamenti automatici in background funzionano diversamente. 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 delle operazioni manuali. 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](#git-operations-time-out), quindi gli aggiornamenti automatici del marketplace privato possono non riuscire intermittentemente.840<h4 id="background-auto-updates">

841 Aggiornamenti automatici in background

842</h4>

843

844Per 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](#git-operations-time-out), quindi gli aggiornamenti automatici del marketplace privato possono non riuscire intermittentemente.

581 845

582Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:846Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:

583 847

608 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del flusso di lavoro predefinito può accedere solo al repository del flusso di lavoro stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app. Una riscrittura URL globale configurata nella pipeline autentica anche il pull in background direttamente.872 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del flusso di lavoro predefinito può accedere solo al repository del flusso di lavoro stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app. Una riscrittura URL globale configurata nella pipeline autentica anche il pull in background direttamente.

609</Note>873</Note>

610 874

611<h3 id="test-locally-before-distribution">875<h3 id="distribute-through-organization-settings">

612 Testa localmente prima della distribuzione876 Distribuisci tramite impostazioni dell'organizzazione

613</h3>877</h3>

614 878

615Testa il tuo marketplace localmente prima di condividerlo:879Se distribuisci plugin tramite [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) su un piano Team o Enterprise, si applicano queste regole di origine:

616 880

617```shell theme={null}881* 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.

618/plugin marketplace add ./my-marketplace882* Ogni origine di plugin deve essere di tipo `github`, `url` o `git-subdir`, o un [percorso relativo](#relative-paths) 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`.

619/plugin install quality-review-plugin@my-plugins883* Un'origine di plugin può essere privata in due casi:

884 * Un'origine github.com che condivide il proprietario del repository del marketplace

885 * Un'origine sull'host GitHub Enterprise della tua organizzazione con l'app GHE installata sul repository

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

887

888Vedi [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) per il flusso di lavoro dell'amministratore.

889

890Per includere plugin privati, posiziona le cartelle dei plugin all'interno del repository del marketplace e fai riferimento ad esse con un [percorso relativo](#relative-paths). 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.

891

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

893

894```json theme={null}

895{

896 "name": "deploy-tools",

897 "source": "./plugins/deploy-tools"

898}

620```899```

621 900

622Per l'intera gamma di comandi add (GitHub, URL Git, percorsi locali, URL remoti), vedi [Aggiungi marketplace](/docs/it/discover-plugins#add-marketplaces).901<h4 id="keep-executables-out-of-the-top-level-bin-directory">

902 Mantieni gli eseguibili fuori dalla directory bin di livello superiore

903</h4>

904

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

906

907* **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`.

908* **Caricamento diretto**: se carichi il plugin in [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) invece, claude.ai rifiuta il caricamento con lo stesso messaggio.

909

910Mantieni 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](/docs/it/plugins-reference#environment-variables).

623 911

624<h3 id="require-marketplaces-for-your-team">912<h3 id="require-marketplaces-for-your-team">

625 Richiedi marketplace per il tuo team913 Richiedi marketplace per il tuo team

626</h3>914</h3>

627 915

628Puoi configurare il tuo repository in modo che i membri del team vengano automaticamente invitati a installare il tuo marketplace quando fidano della cartella del progetto. Aggiungi il tuo marketplace a `.claude/settings.json`:916Puoi 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](/docs/it/permissions#what-runs-before-you-trust-a-folder), senza alcun prompt separato. Aggiungi il tuo marketplace a `.claude/settings.json`:

629 917

630```json theme={null}918```json theme={null}

631{919{

651}939}

652```940```

653 941

654Per le opzioni di configurazione complete, vedi [Plugin settings](/docs/it/settings#plugin-settings).942Per le opzioni di configurazione complete, vedi [Plugin settings](/docs/it/settings-reference#plugin-settings).

655 943

656<Note>944<Note>

657 Se usi una fonte locale `directory` o `file` con un percorso relativo, il percorso si risolve rispetto al checkout principale del tuo repository. Quando esegui Claude Code da un git worktree, il percorso punta ancora al checkout principale, quindi tutti i worktree condividono la stessa posizione del marketplace. Lo stato del marketplace viene archiviato una volta per utente in `~/.claude/plugins/known_marketplaces.json`, non per progetto.945 Se usi una fonte locale `directory` o `file` con un percorso relativo, il percorso si risolve rispetto al checkout principale del tuo repository. Quando esegui Claude Code da un git worktree, il percorso punta ancora al checkout principale, quindi tutti i worktree condividono la stessa posizione del marketplace. Lo stato del marketplace viene archiviato una volta per utente in `~/.claude/plugins/known_marketplaces.json`, non per progetto.

699 Restrizioni del marketplace gestito987 Restrizioni del marketplace gestito

700</h3>988</h3>

701 989

702Per 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`](/docs/it/settings#strictknownmarketplaces) nelle impostazioni gestite. Per anche rifiutare i flag CLI che caricano plugin, agenti e server MCP per una singola esecuzione, abbinalo a [`disableSideloadFlags`](/docs/it/settings#available-settings). Per consentire quali plugin dei marketplace possono apparire come suggerimenti di installazione contestuali, imposta [`pluginSuggestionMarketplaces`](/docs/it/settings#available-settings).990Per 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`](/docs/it/settings-reference#strictknownmarketplaces) nelle impostazioni gestite. Per anche rifiutare i flag CLI che caricano plugin, agenti e server MCP per una singola esecuzione, abbinalo a [`disableSideloadFlags`](/docs/it/settings-reference#disablesideloadflags). Per consentire quali plugin dei marketplace possono apparire come suggerimenti di installazione contestuali, imposta [`pluginSuggestionMarketplaces`](/docs/it/settings-reference#pluginsuggestionmarketplaces).

991

992`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`](#command-sources) da un marketplace consentito. Per bloccare anche le origini dei comandi, imposta [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources).

703 993

704Quando `strictKnownMarketplaces` è configurato nelle impostazioni gestite, il comportamento della restrizione dipende dal valore:994Quando `strictKnownMarketplaces` è configurato nelle impostazioni gestite, il comportamento della restrizione dipende dal valore:

705 995

706| Valore | Comportamento |996| Valore | Comportamento |

707| -------------------------- | --------------------------------------------------------------------------------------------------------- |997| -------------------------- | --------------------------------------------------------------------------------------------------------------- |

708| Non definito (predefinito) | Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace |998| Non definito (predefinito) | Nessuna restrizione. Gli utenti possono aggiungere qualsiasi marketplace |

710| Elenco di fonti | Gli utenti possono aggiungere solo marketplace che corrispondono esattamente all'elenco di autorizzazione |1000| Elenco di fonti | Elenco di autorizzazione applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce |

711 1001

712<h4 id="common-configurations">1002<h4 id="common-configurations">

713 Configurazioni comuni1003 Configurazioni comuni

714</h4>1004</h4>

715 1005

716Disabilita tutti gli aggiunte di marketplace:1006Disabilita tutti gli aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:

717 1007

718```json theme={null}1008```json theme={null}

719{1009{

721}1011}

722```1012```

723 1013

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

1015

1016```json theme={null}

1017{

1018 "strictKnownMarketplaces": [

1019 {

1020 "source": "github",

1021 "repo": "anthropics/claude-plugins-official"

1022 }

1023 ]

1024}

1025```

1026

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

1028

1029La registrazione automatica non copre ogni macchina. Più comunemente manca:

1030

1031* Ambienti non interattivi che vengono eseguiti prima del primo avvio interattivo della macchina.

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

1033

1034Su queste macchine, aggiungi il marketplace a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json` in modo che Claude Code lo registri automaticamente, o esegui `claude plugin marketplace add anthropics/claude-plugins-official`.

1035

724Consenti solo marketplace specifici:1036Consenti solo marketplace specifici:

725 1037

726```json theme={null}1038```json theme={null}

743}1055}

744```1056```

745 1057

1058Consenti ogni repository di marketplace sotto un'organizzazione GitHub con una voce [owner-wildcard](/docs/it/settings-reference#owner-wildcards). I wildcard del proprietario richiedono Claude Code v2.1.223 o successivo.

1059

1060```json theme={null}

1061{

1062 "strictKnownMarketplaces": [

1063 {

1064 "source": "github",

1065 "repo": "acme-corp/*"

1066 }

1067 ]

1068}

1069```

1070

746Consenti tutti i marketplace da un server git interno utilizzando la corrispondenza del modello regex sull'host. Questo è l'approccio consigliato per [GitHub Enterprise Server](/docs/it/github-enterprise-server#plugin-marketplaces-on-ghes) o istanze GitLab self-hosted:1071Consenti tutti i marketplace da un server git interno utilizzando la corrispondenza del modello regex sull'host. Questo è l'approccio consigliato per [GitHub Enterprise Server](/docs/it/github-enterprise-server#plugin-marketplaces-on-ghes) o istanze GitLab self-hosted:

747 1072

748```json theme={null}1073```json theme={null}

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

773 1098

774<Note>1099<Note>

775 `strictKnownMarketplaces` limita ciò che gli utenti possono aggiungere, ma non registra i marketplace di per sé. Per rendere i marketplace consentiti disponibili automaticamente senza che gli utenti eseguano `/plugin marketplace add`, abbinalo a [`extraKnownMarketplaces`](/docs/it/settings#extraknownmarketplaces) nello stesso `managed-settings.json`. Vedi [Usare entrambi insieme](/docs/it/settings#strictknownmarketplaces).1100 `strictKnownMarketplaces` limita ciò che gli utenti possono aggiungere, ma non registra i marketplace di per sé. Per registrare un marketplace consentito per gli utenti automaticamente, aggiungilo a [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) nello stesso `managed-settings.json`.

1101

1102 Il marketplace ufficiale di Anthropic è l'unico che Claude Code registra di per sé, e solo quando l'elenco di autorizzazione lo consente. La registrazione automatica manca anche alcune macchine, come ambienti non interattivi e macchine dove una policy precedente lo ha bloccato. Per coprire quelle macchine, aggiungi il marketplace ufficiale a `extraKnownMarketplaces` anche. Per i due setting affiancati, vedi il [riferimento `strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces).

776</Note>1103</Note>

777 1104

778<h4 id="how-restrictions-work">1105<h4 id="how-restrictions-work">

781 1108

782Le 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`.1109Le 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`.

783 1110

784L'elenco di autorizzazione utilizza la corrispondenza esatta per la maggior parte dei tipi di fonte. Affinché un marketplace sia consentito, tutti i campi specificati devono corrispondere esattamente:1111Per 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](/docs/it/settings-reference#owner-wildcards).

1112

1113Quando un utente aggiunge un URL di repository `https://` che Claude Code [clona piuttosto che recupera](/docs/it/discover-plugins#add-from-other-git-hosts), 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.

1114

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

785 1116

786* Per le fonti GitHub: `repo` è obbligatorio e `ref` o `path` devono corrispondere anche se specificati nell'elenco di autorizzazione1117* 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](/docs/it/settings-reference#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`

787* Per le fonti URL: l'URL completo deve corrispondere esattamente1118* Per le fonti URL: l'URL completo deve corrispondere esattamente

788* Per le fonti `hostPattern`: l'host del marketplace viene confrontato con il modello regex1119* Per le fonti `hostPattern`: l'host del marketplace viene confrontato con il modello regex

789* Per le fonti `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex1120* Per le fonti `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex

790 1121

791La corrispondenza esatta non normalizza gli URL: una barra finale, il suffisso `.git` o il modulo `ssh://` rispetto a `https://` vengono trattati 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 tutte le forme corrispondano.1122La 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.

792 1123

793Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/docs/it/settings#settings-files), le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.1124Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/docs/it/managed-settings), le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.

794 1125

795Per i dettagli di configurazione completi inclusi tutti i tipi di fonte supportati e il confronto con `extraKnownMarketplaces`, vedi il [riferimento strictKnownMarketplaces](/docs/it/settings#strictknownmarketplaces).1126Per i dettagli di configurazione completi inclusi tutti i tipi di fonte supportati e il confronto con `extraKnownMarketplaces`, vedi il [riferimento strictKnownMarketplaces](/docs/it/settings-reference#strictknownmarketplaces).

796 1127

797<h3 id="version-resolution-and-release-channels">1128<h3 id="version-resolution-and-release-channels">

798 Risoluzione della versione e canali di rilascio1129 Risoluzione della versione e canali di rilascio

799</h3>1130</h3>

800 1131

801Le 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.1132Le 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](/docs/it/plugins-reference#version-management) per l'ordine di risoluzione completo, incluse le fonti `archive`.

~~802~~

803Claude Code risolve la versione di un plugin dal primo di questi che è impostato:

~~804~~

8051. `version` nel `plugin.json` del plugin

8062. `version` nella voce del marketplace del plugin

8073. Lo SHA del commit git della fonte del plugin

~~808~~

809Per i tipi di fonte basati su git `github`, `url`, `git-subdir` e i percorsi relativi all'interno di un marketplace ospitato su git, puoi omettere completamente `version` e ogni nuovo commit viene trattato come una nuova versione. Questa è la configurazione più semplice per i plugin interni o in fase di sviluppo attivo.

810 1133

811<Warning>1134<Warning>

812 Impostare `version` fissa il plugin. Se `plugin.json` dichiara `"version": "1.0.0"`, spingere nuovi commit senza cambiare quella stringa non fa nulla per gli utenti esistenti, perché Claude Code vede la stessa versione e mantiene la copia in cache. Aumenta il campo ad ogni rilascio, o omettilo per usare lo SHA del commit.1135 Impostare `version` fissa il plugin per ogni tipo di fonte tranne [`command`](#command-sources), la cui versione include sempre un hash di ciò che il comando ha prodotto. Se dichiari `"version": "1.0.0"` in `plugin.json` e spingi nuovi commit senza cambiare quella stringa, gli utenti esistenti di quelle fonti mantengono la copia in cache, perché Claude Code vede la stessa versione. Aumenta il campo ad ogni rilascio, o omettilo per ricadere sulla versione risolta.

813 1136

814 Evita di impostare `version` sia in `plugin.json` che nella voce del marketplace. Il valore `plugin.json` vince sempre silenziosamente, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in `marketplace.json`.1137 Evita di impostare `version` sia in `plugin.json` che nella voce del marketplace. Il valore `plugin.json` vince sempre silenziosamente, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in `marketplace.json`.

815</Warning>1138</Warning>

818 Configura i canali di rilascio1141 Configura i canali di rilascio

819</h4>1142</h4>

820 1143

821Per 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 i due marketplace a diversi gruppi di utenti tramite [impostazioni gestite](/docs/it/settings#settings-files).1144Per 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:

1145

1146* Distribuisci [impostazioni gestite endpoint-managed](/docs/it/managed-settings#delivery-mechanisms) separate, come un file di impostazioni gestite o un profilo MDM, ai dispositivi di ogni gruppo. [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#precedence-within-the-managed-tier) dice se il file per gruppo o il profilo si applica su un dispositivo che ha anche una fonte a livello di organizzazione.

1147* Definisci una [policy del gateway delle app Claude](/docs/it/claude-apps-gateway-config#managed) 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.

1148

1149Le impostazioni gestite dal server dalla console di amministrazione [si applicano a ogni utente nella tua organizzazione](/docs/it/server-managed-settings#current-limitations), quindi non possono portare un'assegnazione per gruppo.

822 1150

823<Warning>1151<Warning>

824 Ogni canale deve risolversi a una versione diversa. Se usi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref fissato. Se ometti `version`, gli SHA dei commit distinti già distinguono i canali. Se due ref si risolvono alla stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.1152 Ogni canale deve risolversi a una versione diversa. Se usi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref fissato. Se ometti `version`, gli SHA dei commit distinti già distinguono i canali. Se due ref si risolvono alla stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.

864 Assegna i canali ai gruppi di utenti1192 Assegna i canali ai gruppi di utenti

865</h5>1193</h5>

866 1194

867Assegna ogni marketplace al gruppo di utenti appropriato tramite impostazioni gestite. Ad esempio, il gruppo stabile riceve:1195Assegna 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](#set-up-release-channels). Ad esempio, il gruppo stabile riceve:

868 1196

869```json theme={null}1197```json theme={null}

870{1198{

944 1272

945Testa il tuo marketplace prima di condividerlo.1273Testa il tuo marketplace prima di condividerlo.

946 1274

947Valida la sintassi JSON del tuo marketplace:1275Dalla tua directory marketplace, valida la sintassi JSON:

948 1276

949```bash theme={null}1277```bash theme={null}

950claude plugin validate .1278claude plugin validate .

1057| :------- | :--------------- |1385| :------- | :--------------- |

1059 1387

1060Con `--json`, ogni voce include `name`, `source` 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.1388Con `--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.

1061 1389

1062<h3 id="plugin-marketplace-remove">1390<h3 id="plugin-marketplace-remove">

1063 Plugin marketplace remove1391 Plugin marketplace remove

1113 1441

1114* Verifica che l'URL del marketplace sia accessibile1442* Verifica che l'URL del marketplace sia accessibile

1115* Controlla che `.claude-plugin/marketplace.json` esista nel percorso specificato1443* Controlla che `.claude-plugin/marketplace.json` esista nel percorso specificato

1116* Assicurati che la sintassi JSON sia valida utilizzando `claude plugin validate` o `/plugin validate`. Per verificare il frontmatter di skill, agente e comando, esegui il comando su ogni directory di plugin1444* 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](#validate-a-plugin-or-a-directory-without-a-manifest)

1117* Per i repository privati, conferma di avere i permessi di accesso1445* Per i repository privati, conferma di avere i permessi di accesso

1118 1446

1119<h3 id="marketplace-validation-errors">1447<h3 id="marketplace-validation-errors">

1130 1458

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

1132 1460

1133Per validare il `plugin.json` di un singolo plugin e i suoi file di skill, agente, comando e hook, esegui il comando sulla directory del plugin stesso, ad esempio `claude plugin validate ./plugins/my-plugin`. Errori comuni:1461Dalla 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](#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:

1134 1462

1136| :------------------------------------------------ | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |1464| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1137| `File not found: .claude-plugin/marketplace.json` | Manifest mancante | Crea `.claude-plugin/marketplace.json` con i campi obbligatori |1465| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory che hai denominato non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file di skill, agente o comando da verificare | Esegui dalla radice del marketplace, o crea `.claude-plugin/marketplace.json` con i campi obbligatori |

1138| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controlla le virgole mancanti, le virgole extra o le stringhe non quotate |1466| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controlla le virgole mancanti, le virgole extra o le stringhe non quotate |

1140| `plugins[0].source: Path contains ".."` | Il percorso di origine contiene `..` | Usa percorsi relativi alla radice del marketplace senza `..`. Vedi [Percorsi relativi](#relative-paths) |1468| `plugins[0].source: Path contains ".."` | Il percorso di origine contiene `..` | Usa percorsi relativi alla radice del marketplace senza `..`. Vedi [Percorsi relativi](#relative-paths) |

1141| `YAML frontmatter failed to parse: ...` | YAML non valido in un file di skill, agente o comando | Correggi la sintassi YAML nel blocco frontmatter. Al runtime questo file si carica senza metadati. Segnalato solo quando si valida una directory di plugin |1469| `Marketplace name cannot contain control or bidirectional-formatting characters` | Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |

1142| `Invalid JSON syntax: ...` (hooks.json) | `hooks/hooks.json` malformato | Correggi la sintassi JSON. Un `hooks/hooks.json` malformato impedisce al plugin intero di caricarsi. Segnalato solo quando si valida una directory di plugin |1470| `Plugin name cannot contain control or bidirectional-formatting characters` | Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |

1143 1471

1144**Avvisi** (non bloccanti):1472**Avvisi** (non bloccanti):

1145 1473

1146* `Marketplace has no plugins defined`: aggiungi almeno un plugin all'array `plugins`1474* `Marketplace has no plugins defined`: aggiungi almeno un plugin all'array `plugins`

1147* `No marketplace description provided`: aggiungi una `description` di livello superiore per aiutare gli utenti a comprendere il tuo marketplace1475* `No marketplace description provided`: aggiungi una `description` di livello superiore per aiutare gli utenti a comprendere il tuo marketplace

1148* `Plugin name "x" is not kebab-case`: il nome del plugin contiene lettere maiuscole, spazi o caratteri speciali. 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.1476* `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.

1477* `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.

1478* `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.

1479

1480<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1481 Validate a plugin or a directory without a manifest

1482</h4>

1483

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

1485

1486<h5 id="pick-the-directory-to-name">

1487 Pick the directory to name

1488</h5>

1489

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

1491

1492| Per verificare | Esegui | Claude Code controlla |

1493| :------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1494| Un plugin che ha un `plugin.json` | `claude plugin validate ./plugins/my-plugin` | `plugin.json`, `hooks/hooks.json`, e le directory `skills`, `agents`, e `commands` alla radice del plugin |

1495| Una directory di skill, agenti o comandi, come un plugin che non ha ancora un `plugin.json` | `claude plugin validate .claude/skills`, `~/.claude/agents`, o `./my-plugin/agents` | Ogni file di skill, agente o comando in quella directory |

1496| Una cartella il cui skill è il suo `SKILL.md` radice | `claude plugin validate ./skills`, denominando la directory `skills` che contiene la cartella | Il `SKILL.md` radice di ogni cartella. La directory contenente deve essere denominata `skills`; una cartella sotto un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice |

1497| Le tre directory di un progetto contemporaneamente | `claude plugin validate .claude`, o la radice del progetto quando non ha un manifest `.claude-plugin/` | `.claude/skills`, `.claude/agents`, e `.claude/commands` |

1498| Le tue directory a livello di utente | `claude plugin validate ~/.claude` | `~/.claude/skills`, `~/.claude/agents`, e `~/.claude/commands` |

1499

1500<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

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

1502</h5>

1503

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

1505

1506* Denomina quella directory `skills` per verificare il `SKILL.md` radice del plugin.

1507* Denomina la directory del plugin per verificare il resto.

1508

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

1510

1511<h5 id="check-files-behind-symlinks">

1512 Check files behind symlinks

1513</h5>

1514

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

1516

1517* **Una directory `skills`, `agents`, o `commands` collegata sotto la radice del plugin o `.claude`**: Claude Code avverte che nulla in essa è stato letto.

1518* **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à.

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

1520

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

1522

1523* **Un plugin il cui directory `skills` [collega a una directory skills di un plugin fratello](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks)**: denomina la directory del plugin fratello.

1524* **Una [voce di skill collegata](/docs/it/skills#where-skills-live) 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.

1525

1526<h5 id="read-the-validation-results">

1527 Read the validation results

1528</h5>

1529

1530Un'esecuzione pulita termina con `Validation passed`.

1531

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

1533

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

1535

1536* `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

1537* `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

1538

1539In 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](/docs/it/plugins-reference#component-path-fields) in `plugin.json`, Claude Code controlla che ogni percorso esista ma non legge i file lì.

1149 1540

1150<h3 id="plugin-installation-failures">1541<h3 id="plugin-installation-failures">

1151 Errori di installazione del plugin1542 Errori di installazione del plugin

1172Per l'installazione manuale e gli aggiornamenti:1563Per l'installazione manuale e gli aggiornamenti:

1173 1564

1174* Verifica di essere autenticato con il tuo provider git (ad esempio, esegui `gh auth status` per GitHub)1565* Verifica di essere autenticato con il tuo provider git (ad esempio, esegui `gh auth status` per GitHub)

1175* Controlla che il tuo helper di credenziali sia configurato correttamente: `git config --global credential.helper`1566* Controlla che il tuo helper di credenziali sia configurato: `git config --global credential.helper`

1176* Prova a clonare il repository manualmente per verificare che le tue credenziali funzionino1567* 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`

1177 1568

1178Per gli aggiornamenti automatici in background:1569Per gli aggiornamenti automatici in background:

1179 1570

1198export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11589export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1199```1590```

1200 1591

1201Con questa variabile impostata, Claude Code mantiene il clone obsoleto del marketplace in caso di fallimento di `git pull` e continua a utilizzare lo stato ultimo noto come buono. Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizza [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) per pre-popolare la directory dei plugin al momento della compilazione.1592Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizza [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) per pre-popolare la directory dei plugin al momento della compilazione.

1202 1593

1203<h3 id="git-operations-time-out">1594<h3 id="git-operations-time-out">

1204 Le operazioni Git scadono1595 Le operazioni Git scadono

1220 1611

1221**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 errori "path not found".1612**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 errori "path not found".

1222 1613

1223**Causa**: I marketplace basati su URL scaricano solo il file `marketplace.json` stesso. Non scaricano i file dei plugin dal server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.1614**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.

1224 1615

1225**Soluzioni**:1616**Soluzioni**:

1226 1617

1227* **Usa origini esterne**: Cambia le voci dei plugin per usare GitHub, npm o origini URL git invece di percorsi relativi:1618* **Usa origini esterne**: cambia le voci dei plugin per usare qualsiasi [plugin source](#plugin-sources) diverso da un percorso relativo:

1228 ```json theme={null}1619 ```json theme={null}

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

1230 ```1621 ```

1236 1627

1237**Sintomi**: Il plugin si installa ma i riferimenti ai file non riescono, specialmente i file al di fuori della directory del plugin1628**Sintomi**: Il plugin si installa ma i riferimenti ai file non riescono, specialmente i file al di fuori della directory del plugin

1238 1629

1239**Causa**: I plugin vengono copiati in una directory cache piuttosto che utilizzati in-place. I percorsi che fanno riferimento a file al di fuori della directory del plugin (come `../shared-utils`) non funzioneranno perché quei file non vengono copiati.1630**Causa**: I plugin vengono copiati in una directory cache piuttosto che utilizzati in-place, tranne per una [`command` source in link mode](#copy-mode-and-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.

1240 1631

1241**Soluzioni**: Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per le soluzioni alternative inclusi symlink e ristrutturazione delle directory.1632**Soluzioni**: Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per le soluzioni alternative inclusi symlink e ristrutturazione delle directory.

1242 1633

1249* [Scopri e installa plugin precostruiti](/docs/it/discover-plugins) - Installazione di plugin da marketplace esistenti1640* [Scopri e installa plugin precostruiti](/docs/it/discover-plugins) - Installazione di plugin da marketplace esistenti

1250* [Plugins](/docs/it/plugins) - Creazione dei tuoi plugin1641* [Plugins](/docs/it/plugins) - Creazione dei tuoi plugin

1251* [Plugins reference](/docs/it/plugins-reference) - Specifiche tecniche complete e schemi1642* [Plugins reference](/docs/it/plugins-reference) - Specifiche tecniche complete e schemi

1252* [Plugin settings](/docs/it/settings#plugin-settings) - Opzioni di configurazione dei plugin1643* [Plugin settings](/docs/it/settings-reference#plugin-settings) - Opzioni di configurazione dei plugin

1253* [strictKnownMarketplaces reference](/docs/it/settings#strictknownmarketplaces) - Restrizioni del marketplace gestito1644* [strictKnownMarketplaces reference](/docs/it/settings-reference#strictknownmarketplaces) - Restrizioni del marketplace gestito

plugin-marketplaces.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

Creare e distribuire un marketplace di plugin

Panoramica

Procedura dettagliata: creare un marketplace locale

Crea la struttura delle directory

Crea la skill

Crea il manifest del plugin

Crea il file marketplace

Aggiungi e installa

Provalo

Crea il file marketplace

Schema del marketplace

Campi obbligatori

Campi del proprietario

Campi opzionali

Voci di plugin

Campi obbligatori

Campi di plugin opzionali

Plugin sources

Percorsi relativi

Repository GitHub

Repository Git

Sottodirectory Git

Pacchetti npm

Archivi zip

Autentica i download degli archivi

Aggiungi un headersHelper a una voce di plugin

Scrivi il comando headersHelper

Quando Claude Code salta un comando headersHelper o scarta il suo output

Come gli utenti accettano un comando headersHelper

Install e aggiornamenti che rifiutano il comando invece di chiedere

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

Command sources

Copy mode and link mode

Come gli utenti accettano il comando

Quando Claude Code riesegue il comando

Voci di plugin avanzate

Strict mode

Ospita e distribuisci marketplace

Ospita su GitHub (consigliato)

Ospita su altri servizi git

Repository privati

Comandi che esegui

Aggiornamenti automatici in background

Distribuisci tramite impostazioni dell'organizzazione

Mantieni gli eseguibili fuori dalla directory bin di livello superiore

Richiedi marketplace per il tuo team

Pre-popola plugin per i container

Restrizioni del marketplace gestito

Configurazioni comuni

Come funzionano le restrizioni

Risoluzione della versione e canali di rilascio

Configura i canali di rilascio

Esempio

Assegna i canali ai gruppi di utenti

Fissa le versioni delle dipendenze

Rinomina o rimuovi un plugin

Validazione e test

Gestisci marketplace dalla CLI

Plugin marketplace add

Plugin marketplace list

Plugin marketplace remove

Plugin marketplace update

Troubleshooting

Marketplace non carica

Errori di validazione del marketplace

Validate a plugin or a directory without a manifest

Pick the directory to name

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

Check files behind symlinks

Read the validation results

Errori di installazione del plugin

L'autenticazione del repository privato non riesce

Gli aggiornamenti del marketplace non riescono in ambienti offline

Le operazioni Git scadono

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

File non trovati dopo l'installazione

Vedi anche