plugin-marketplaces.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Creare e distribuire un marketplace di plugin

6 

7> Crea e ospita marketplace di plugin per distribuire estensioni Claude Code tra team e comunità.

8 

9Un **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à.

10 

11Stai cercando di installare plugin da un marketplace esistente? Vedi [Scopri e installa plugin precostruiti](/docs/it/discover-plugins).

12 

13<h2 id="overview">

14 Panoramica

15</h2>

16 

17La creazione e la distribuzione di un marketplace comporta:

18 

191. **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](/docs/it/plugins) per i dettagli su come crearli.

202. **Creazione di un file marketplace**: definisci un `marketplace.json` che elenca i tuoi plugin e dove trovarli. Vedi [Crea il file marketplace](#create-the-marketplace-file).

213. **Ospita il marketplace**: esegui il push su GitHub, GitLab o un altro host git. Vedi [Ospita e distribuisci marketplace](#host-and-distribute-marketplaces).

224. **Condividi con gli utenti**: gli utenti aggiungono il tuo marketplace con `/plugin marketplace add` e installano singoli plugin. Vedi [Scopri e installa plugin](/docs/it/discover-plugins).

23 

24Una 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`.

25 

26<h2 id="walkthrough-create-a-local-marketplace">

27 Procedura dettagliata: creare un marketplace locale

28</h2>

29 

30Questo 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.

31 

32<Steps>

33 <Step title="Crea la struttura delle directory">

34 ```bash theme={null}

35 mkdir -p my-marketplace/.claude-plugin

36 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin

37 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

38 ```

39 </Step>

40 

41 <Step title="Crea la skill">

42 Crea un file `SKILL.md` che definisce cosa fa la skill `quality-review`.

43 

44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

45 ---

46 description: Rivedi il codice per bug, sicurezza e prestazioni

47 ---

48 

49 Rivedi il codice che ho selezionato o i cambiamenti recenti per:

50 - Potenziali bug o casi limite

51 - Problemi di sicurezza

52 - Problemi di prestazioni

53 - Miglioramenti di leggibilità

54 

55 Sii conciso e pratico.

56 ```

57 </Step>

58 

59 <Step title="Crea il manifest del plugin">

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

61 

62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

63 {

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

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

66 "version": "1.0.0",

67 "author": {

68 "name": "Your Name"

69 }

70 }

71 ```

72 

73 <Note>

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. Nemmeno un plugin [caricato in posizione](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale. Se ometti `version`, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management).

75 </Note>

76 </Step>

77 

78 <Step title="Crea il file marketplace">

79 Crea il catalogo marketplace che elenca il tuo plugin.

80 

81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

82 {

83 "name": "my-plugins",

84 "owner": {

85 "name": "Your Name"

86 },

87 "plugins": [

88 {

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

90 "source": "./plugins/quality-review-plugin",

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

92 }

93 ]

94 }

95 ```

96 </Step>

97 

98 <Step title="Aggiungi e installa">

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.`, vedi [Applica le modifiche ai plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting).

100 

101 ```shell theme={null}

102 /plugin marketplace add ./my-marketplace

103 /plugin install quality-review-plugin@my-plugins

104 ```

105 </Step>

106 

107 <Step title="Provalo">

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

109 

110 ```shell theme={null}

111 /quality-review-plugin:quality-review

112 ```

113 </Step>

114</Steps>

115 

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

117 

118<Note>

119 **Come vengono installati i plugin**: quando gli utenti installano un plugin, Claude Code copia la directory del plugin in una posizione cache, a meno che il plugin non si carichi in posizione. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica in posizione, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. 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.

120 

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.

122</Note>

123 

124<h2 id="create-the-marketplace-file">

125 Crea il file marketplace

126</h2>

127 

128Crea `.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.

129 

130Ogni 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](#marketplace-schema) di seguito per tutti i campi disponibili.

131 

132```json theme={null}

133{

134 "name": "company-tools",

135 "owner": {

136 "name": "DevTools Team",

137 "email": "devtools@example.com"

138 },

139 "plugins": [

140 {

141 "name": "code-formatter",

142 "source": "./plugins/formatter",

143 "description": "Automatic code formatting on save",

144 "version": "2.1.0",

145 "author": {

146 "name": "DevTools Team"

147 }

148 },

149 {

150 "name": "deployment-tools",

151 "source": {

152 "source": "github",

153 "repo": "company/deploy-plugin"

154 },

155 "description": "Deployment automation tools"

156 }

157 ]

158}

159```

160 

161<h2 id="marketplace-schema">

162 Schema del marketplace

163</h2>

164 

165<h3 id="required-fields">

166 Campi obbligatori

167</h3>

168 

169| Campo | Tipo | Descrizione | Esempio |

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

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

172| `owner` | object | Informazioni sul manutentore del marketplace. Vedi [Campi del proprietario](#owner-fields) | |

173| `plugins` | array | Elenco dei plugin disponibili | Vedi [Voci di plugin](#plugin-entries) |

174 

175<Note>

176 **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`, `claude-tag-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.

177 

178 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](/docs/it/errors#marketplace-is-registered-from-an-untrusted-source). 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. Prima della v2.1.265, `claude-tag-plugins` non era riservato.

179 

180 Non puoi nemmeno denominare un marketplace `npm`, `pip`, `uv`, `cargo`, `github`, o `gh`, in nessuna combinazione di maiuscole e minuscole. Questo controllo richiede Claude Code v2.1.275 o successivo.

181</Note>

182 

183<h3 id="owner-fields">

184 Campi del proprietario

185</h3>

186 

187| Campo | Tipo | Obbligatorio | Descrizione |

188| :------ | :----- | :----------- | :------------------------------------------------- |

189| `name` | string | Sì | Nome del manutentore o del team |

190| `email` | string | No | Email di contatto per il manutentore |

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

192 

193<h3 id="optional-fields">

194 Campi opzionali

195</h3>

196 

197| Campo | Tipo | Descrizione |

198| :------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

199| `$schema` | string | URL dello schema JSON per l'autocompletamento dell'editor e la convalida. Claude Code ignora questo campo al momento del caricamento. |

200| `description` | string | Breve descrizione del marketplace |

201| `version` | string | Versione del manifest del marketplace |

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

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

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

205 

206`description` e `version` sono accettati anche sotto `metadata` per compatibilità con le versioni precedenti.

207 

208<h2 id="plugin-entries">

209 Voci di plugin

210</h2>

211 

212Ogni 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`.

213 

214<h3 id="required-fields-2">

215 Campi obbligatori

216</h3>

217 

218| Campo | Tipo | Descrizione |

219| :------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

221| `source` | string\|object | Da dove recuperare il plugin (vedi [Plugin sources](#plugin-sources) di seguito) |

222 

223<h3 id="optional-plugin-fields">

224 Campi di plugin opzionali

225</h3>

226 

227**Campi di metadati standard:**

228 

229| Campo | Tipo | Descrizione |

230| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

231| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Quando né la voce né il `plugin.json` del plugin ne impostano uno, gli utenti vedono il `name` del plugin. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |

232| `description` | string | Breve descrizione del plugin |

233| `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. Neanche un plugin [caricato in place](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |

234| `author` | object | Informazioni sull'autore del plugin (`name` obbligatorio; `email` e `url` opzionali) |

235| `homepage` | string | URL della homepage o della documentazione del plugin |

236| `repository` | string | URL del repository del codice sorgente |

237| `license` | string | Identificatore di licenza SPDX (ad esempio, MIT, Apache-2.0) |

238| `keywords` | array | Tag per la scoperta e la categorizzazione dei plugin |

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

240| `category` | string | Categoria del plugin per l'organizzazione |

241| `tags` | array | Tag per la ricercabilità |

242| `strict` | boolean | Controlla se `plugin.json` è l'autorità per le definizioni dei componenti (predefinito: true). Vedi [Strict mode](#strict-mode) di seguito. |

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

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

245 

246Sia la voce che il `plugin.json` del plugin stesso possono impostare i campi di visualizzazione `displayName`, `description`, `author`, `homepage`, `repository`, `license` e `keywords`. Negli elenchi e nei dettagli dei plugin, prima e dopo l'installazione:

247 

248* Per un campo che imposti sulla voce, gli utenti vedono il valore della voce, anche quando `plugin.json` ne imposta uno diverso.

249* Per un campo che la voce lascia non impostato, gli utenti vedono il valore di `plugin.json`.

250 

251Prima dell'installazione, Claude Code può leggere `plugin.json` solo per le voci con una [relative-path source](#relative-paths), i cui file di plugin si trovano all'interno del marketplace stesso. Per una voce con qualsiasi altro tipo di source, gli utenti vedono solo i campi della voce stessa fino a quando non installano il plugin.

252 

253**Campi di configurazione dei componenti:**

254 

255| Campo | Tipo | Descrizione |

256| :----------- | :------------- | :------------------------------------------------------------------------------ |

257| `skills` | string\|array | Percorsi personalizzati alle directory delle skill contenenti `<name>/SKILL.md` |

258| `commands` | string\|array | Percorsi personalizzati ai file di skill flat `.md` o alle directory |

259| `agents` | string\|array | Percorsi personalizzati ai file degli agenti |

260| `hooks` | string\|object | Configurazione degli hook personalizzati o percorso al file degli hook |

261| `mcpServers` | string\|object | Configurazioni del server MCP o percorso alla configurazione MCP |

262| `lspServers` | string\|object | Configurazioni del server LSP o percorso alla configurazione LSP |

263 

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

265 

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

267 

268| Campo | Tipo | Descrizione |

269| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

272 

273<h2 id="plugin-sources">

274 Origini dei plugin

275</h2>

276 

277Le origini dei plugin indicano a Claude Code dove ottenere ogni singolo plugin elencato nel tuo marketplace. Questi sono impostati nel campo `source` di ogni voce di plugin in `marketplace.json`.

278 

279Claude Code copia ogni plugin installato nella cache locale dei plugin con versione in `~/.claude/plugins/cache`, a meno che il plugin non si carichi al suo posto. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica al suo posto, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. 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. Vedi [Plugin caching and file resolution](/docs/it/plugins-reference#plugin-caching-and-file-resolution) per come un plugin caricato al suo posto da un marketplace di directory locale raccoglie i tuoi modifiche.

280 

281| Origine | Tipo | Campi | Note |

282| ----------------- | --------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

283| 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 [nome semplice sotto `metadata.pluginRoot`](#relative-paths). Claude Code risolve il percorso relativo alla radice del marketplace, non alla directory `.claude-plugin/` |

284| `github` | object | `repo`, `ref?`, `sha?` | |

285| `url` | object | `url`, `ref?`, `sha?` | Origine URL Git |

286| `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 |

287| `npm` | object | `package`, `version?`, `registry?` | Pacchetto npm, recuperato con il tuo client npm e decompresso senza eseguire script di installazione |

288| `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 |

289| `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 |

290 

291<Note>

292 **Origini del marketplace rispetto alle origini dei plugin**: Questi sono concetti diversi che controllano cose diverse.

293 

294 * **Origine del marketplace**: dove recuperare il catalogo `marketplace.json` stesso. Impostato quando gli utenti eseguono `/plugin marketplace add` o nelle impostazioni `extraKnownMarketplaces`. Le origini del marketplace basate su Git supportano `ref` (branch/tag) ma non `sha`.

295 * **Origine del plugin**: dove recuperare un singolo plugin elencato nel marketplace. Impostato nel campo `source` di ogni voce di plugin all'interno di `marketplace.json`. Le origini dei plugin basate su Git supportano sia `ref` (branch/tag) che `sha` (commit esatto).

296 

297 Ad esempio, un marketplace ospitato in `acme-corp/plugin-catalog` (origine del marketplace) può elencare un plugin recuperato da `acme-corp/code-formatter` (origine del plugin). L'origine del marketplace e l'origine del plugin puntano a repository diversi e sono bloccate indipendentemente.

298</Note>

299 

300I tipi di origine 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 blocco effettivo. Claude Code recupera e controlla il commit bloccato direttamente.

301 

302Sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket, ciò significa che l'installazione ha successo anche se il branch o il tag denominato da `ref` è stato successivamente 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 questi server `ref` deve ancora esistere e il commit bloccato deve essere raggiungibile da esso.

303 

304Se distribuisci plugin tramite **Impostazioni organizzazione > Plugin**, sono consentiti solo alcuni tipi di origine. Vedi [Distribuire tramite impostazioni organizzazione](#distribute-through-organization-settings).

305 

306<h3 id="relative-paths">

307 Percorsi relativi

308</h3>

309 

310Per i plugin nello stesso repository, utilizza un percorso che inizia con `./`:

311 

312```json theme={null}

313{

314 "name": "my-plugin",

315 "source": "./plugins/my-plugin"

316}

317```

318 

319I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente `.claude-plugin/`. Nell'esempio precedente, `./plugins/my-plugin` punta a `<repo>/plugins/my-plugin`, anche se `marketplace.json` si trova in `<repo>/.claude-plugin/marketplace.json`. Non utilizzare `../` per fare riferimento a percorsi al di fuori della radice del marketplace. Su macOS e Linux, Claude Code rifiuta una voce di percorso con una barra rovesciata in qualsiasi punto dopo il `./` iniziale, quindi scrivi i separatori come `/` su ogni piattaforma.

320 

321Un nome semplice è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere nomi semplici invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) sulla directory in cui si risolvono. Con `"pluginRoot": "./plugins"`, Claude Code risolve `"source": "formatter"` in `./plugins/formatter`. Richiede Claude Code v2.1.239 o successivo.

322 

323`metadata.pluginRoot` deve essere esso stesso un percorso relativo all'interno del marketplace. Claude Code lo ignora per un'origine che inizia già con `./`. Un'origine che contiene un `/`, come `team-a/formatter`, non è un nome semplice e ha ancora bisogno del prefisso `./`, anche quando `metadata.pluginRoot` è impostato.

324 

325<Note>

326 Claude Code risolve i percorsi relativi rispetto a una copia locale del marketplace, quindi funzionano quando gli utenti aggiungono il tuo marketplace da un'origine 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é Claude Code scarica solo quel file. Per la distribuzione basata su URL, utilizza invece qualsiasi altra [origine del plugin](#plugin-sources). Vedi [Risoluzione dei problemi](#plugins-with-relative-paths-fail-in-url-based-marketplaces) per i dettagli.

327</Note>

328 

329<h3 id="github-repositories">

330 Repository GitHub

331</h3>

332 

333```json theme={null}

334{

335 "name": "github-plugin",

336 "source": {

337 "source": "github",

338 "repo": "owner/plugin-repo"

339 }

340}

341```

342 

343Puoi bloccare a un branch, tag o commit specifico:

344 

345```json theme={null}

346{

347 "name": "github-plugin",

348 "source": {

349 "source": "github",

350 "repo": "owner/plugin-repo",

351 "ref": "v2.0.0",

352 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

353 }

354}

355```

356 

357| Campo | Tipo | Descrizione |

358| :----- | :----- | :------------------------------------------------------------------------------------------------ |

359| `repo` | string | Obbligatorio. Repository GitHub nel formato `owner/repo` |

360| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

361| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

362 

363<h3 id="git-repositories">

364 Repository Git

365</h3>

366 

367```json theme={null}

368{

369 "name": "git-plugin",

370 "source": {

371 "source": "url",

372 "url": "https://gitlab.com/team/plugin.git"

373 }

374}

375```

376 

377Puoi bloccare a un branch, tag o commit specifico:

378 

379```json theme={null}

380{

381 "name": "git-plugin",

382 "source": {

383 "source": "url",

384 "url": "https://gitlab.com/team/plugin.git",

385 "ref": "main",

386 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

387 }

388}

389```

390 

391| Campo | Tipo | Descrizione |

392| :---- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

393| `url` | string | Obbligatorio. URL completo del repository git (`https://` o `git@`). Il suffisso `.git` è facoltativo, quindi gli URL di Azure DevOps e AWS CodeCommit senza il suffisso funzionano |

394| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

395| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

396 

397<h3 id="git-subdirectories">

398 Sottodirectory Git

399</h3>

400 

401Utilizza `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.

402 

403```json theme={null}

404{

405 "name": "my-plugin",

406 "source": {

407 "source": "git-subdir",

408 "url": "https://github.com/acme-corp/monorepo.git",

409 "path": "tools/claude-plugin"

410 }

411}

412```

413 

414Puoi bloccare a un branch, tag o commit specifico:

415 

416```json theme={null}

417{

418 "name": "my-plugin",

419 "source": {

420 "source": "git-subdir",

421 "url": "https://github.com/acme-corp/monorepo.git",

422 "path": "tools/claude-plugin",

423 "ref": "v2.0.0",

424 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

425 }

426}

427```

428 

429Il campo `url` accetta anche una scorciatoia GitHub (`owner/repo`) o URL SSH (`git@github.com:owner/repo.git`).

430 

431| Campo | Tipo | Descrizione |

432| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------------- |

433| `url` | string | Obbligatorio. URL del repository Git, scorciatoia GitHub `owner/repo`, o URL SSH |

434| `path` | string | Obbligatorio. Percorso della sottodirectory all'interno del repository contenente il plugin (ad esempio, `"tools/claude-plugin"`) |

435| `ref` | string | Facoltativo. Branch o tag Git (per impostazione predefinita il branch predefinito del repository) |

436| `sha` | string | Facoltativo. SHA del commit git completo di 40 caratteri per bloccare a una versione esatta |

437 

438<h3 id="npm-packages">

439 Pacchetti npm

440</h3>

441 

442Un'origine npm può denominare qualsiasi pacchetto nel registro npm pubblico o in un registro privato ospitato dal tuo team. Claude Code risolve il pacchetto con il tuo client npm, scarica il tarball e lo decomprime nella cache del plugin.

443 

444Gli script di installazione del pacchetto, come `preinstall` o `postinstall`, non vengono mai eseguiti, e le sue dipendenze non vengono installate durante il recupero.

445 

446Se il pacchetto fornisce un lockfile supportato accanto al suo `package.json`, Claude Code installa quelle [dipendenze del pacchetto Node.js](/docs/it/plugins-reference#node-js-package-dependencies) in un passaggio separato, anche con script disabilitati. Altrimenti, pubblica il plugin con tutto ciò di cui ha bisogno già costruito. Un server MCP che ha bisogno di altri pacchetti può avviarsi tramite `npx`, che li installa al primo esecuzione.

447 

448```json theme={null}

449{

450 "name": "my-npm-plugin",

451 "source": {

452 "source": "npm",

453 "package": "@acme/claude-plugin"

454 }

455}

456```

457 

458Per bloccare a una versione specifica, aggiungi il campo `version`:

459 

460```json theme={null}

461{

462 "name": "my-npm-plugin",

463 "source": {

464 "source": "npm",

465 "package": "@acme/claude-plugin",

466 "version": "2.1.0"

467 }

468}

469```

470 

471Per installare da un registro privato o interno, aggiungi il campo `registry`:

472 

473```json theme={null}

474{

475 "name": "my-npm-plugin",

476 "source": {

477 "source": "npm",

478 "package": "@acme/claude-plugin",

479 "version": "^2.0.0",

480 "registry": "https://npm.example.com"

481 }

482}

483```

484 

485| Campo | Tipo | Descrizione |

486| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------- |

487| `package` | string | Obbligatorio. Nome del pacchetto o pacchetto con scope (ad esempio, `@org/plugin`) |

488| `version` | string | Facoltativo. Versione o intervallo di versioni (ad esempio, `2.1.0`, `^2.0.0`, `~1.5.0`) |

489| `registry` | string | Facoltativo. URL del registro npm personalizzato. Per impostazione predefinita il registro npm del sistema (in genere npmjs.org) |

490 

491<h3 id="zip-archives">

492 Archivi zip

493</h3>

494 

495Utilizza `archive` per distribuire un plugin come file zip che Claude Code scarica tramite HTTPS, in modo che le installazioni 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. Nelle versioni da v2.1.120 a v2.1.223, l'installazione del plugin non riesce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`; nelle versioni precedenti, un marketplace contenente una voce `archive` non si carica affatto.

496 

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

498 

499```json theme={null}

500{

501 "name": "my-plugin",

502 "source": {

503 "source": "archive",

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

505 }

506}

507```

508 

509Quando crei il file zip, puoi comprimere direttamente il contenuto del plugin o comprimere la cartella del plugin stessa. Claude Code cerca `.claude-plugin/` in cima all'archivio, quindi all'interno di una singola cartella di primo livello, quindi entrambi i layout si installano:

510 

511```text theme={null}

512my-plugin.zip my-plugin.zip

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

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

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

516 └── commands/

517```

518 

519Claude Code non cerca più in profondità di una cartella, quindi un plugin annidato più in basso non si installa. Claude Code rifiuta gli archivi più grandi di 256 MiB.

520 

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

522 

523```json theme={null}

524{

525 "name": "my-plugin",

526 "source": {

527 "source": "archive",

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

529 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

530 }

531}

532```

533 

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

535 

536Le origini dell'archivio accettano questi campi:

537 

538| Campo | Tipo | Descrizione |

539| :------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

540| `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 |

541| `sha256` | string | Facoltativo. Digest SHA-256 dell'archivio come 64 caratteri esadecimali, maiuscoli o minuscoli. Claude Code verifica ogni download rispetto ad esso e rifiuta l'installazione in caso di mancata corrispondenza |

542 

543Il digest `sha256` serve anche come versione del plugin quando né `plugin.json` né la voce del marketplace ne dichiara una. Vedi [Gestione delle versioni](/docs/it/plugins-reference#version-management). Se dichiari una `version`, quella stringa di versione è il segnale di aggiornamento, quindi dopo aver modificato il file zip e il suo digest, aumenta anche la versione, altrimenti gli utenti mantengono la copia memorizzata nella cache.

544 

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

546 Autentica i download dell'archivio

547</h4>

548 

549Per autenticare un download dell'archivio, come un download da un registro privato, imposta le intestazioni HTTP che Claude Code invia con esso. Imposta `headers` sull'origine `url` 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`.

550 

551Se il valore che inseriresti in `headers` è di breve durata, come un token che il tuo registro crea su richiesta, imposta invece 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.

552 

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

554 

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

556| :---------------------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

559 

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

561 

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

563 Aggiungi un headersHelper a una voce di plugin

564</h5>

565 

566Questa 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 è l'intera definizione del plugin, quindi un utente può rivedere cosa contiene il plugin prima di accettare il comando:

567 

568```json theme={null}

569{

570 "name": "my-plugin",

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

572 "strict": false,

573 "commands": "./commands",

574 "source": {

575 "source": "archive",

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

577 },

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

579}

580```

581 

582Per controllare la voce, esegui `claude plugin install my-plugin@your-marketplace`. Claude Code ti mostra il comando e l'URL dell'archivio, e scarica il file zip dopo che accetti.

583 

584Prima della v2.1.238, Claude Code scaricava l'archivio di una voce senza le sue `headers` o `headersHelper`, quindi un'installazione che si basava su di esse non riusciva con `HTTP 401 while downloading plugin archive from`, seguito dall'URL, con il codice di stato del registro al posto di 401.

585 

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

587 Scrivi il comando headersHelper

588</h4>

589 

590Che tu imposti `headersHelper` sull'origine `url` di un marketplace o su una voce di plugin, scrivi il comando per soddisfare questi requisiti:

591 

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

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

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

595* **Variabili che Claude Code rimuove**: dall'ambiente di un comando impostato in una voce `marketplace.json` o nelle impostazioni `.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, in un file `--settings` o nelle impostazioni gestite.

596* **Variabili che Claude Code imposta**: `CLAUDE_CODE_MARKETPLACE_URL` e `CLAUDE_CODE_MARKETPLACE_NAME` per il comando di un'origine `url`, e `CLAUDE_CODE_PLUGIN_NAME` e `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` per il comando di una voce. `CLAUDE_CODE_MARKETPLACE_NAME` non è impostato al primo recupero dopo che un utente aggiunge un marketplace per URL, perché quel recupero è quello che fornisce il nome.

597 

598Un comando che crea un token bearer stampa un oggetto come questo:

599 

600```json theme={null}

601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

602```

603 

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

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

606</h4>

607 

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

609 

610* **Il comando non riesce**: se il comando esce con codice diverso da zero, viene eseguito oltre 10 secondi, o stampa qualcosa di diverso da un oggetto JSON di valori di stringa, Claude Code non effettua il recupero o il download per cui ha eseguito il comando.

611* **L'URL del marketplace non inizia con `https://`**: Claude Code non esegue il comando di quell'origine `url` e invia solo le intestazioni elencate nel suo campo `headers`.

612* **Il reindirizzamento lascia l'origine**: quando un download viene reindirizzato dall'origine dell'URL dell'archivio, Claude Code scarta i valori `headers` e l'output del comando sia dell'origine `url` del marketplace che della voce del plugin.

613* **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-*` dalle `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.

614* **Il comando è impostato nelle impostazioni di una directory `--add-dir`**: Claude Code lo ignora, sia su un'origine `url` che su una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces), e invia solo le `headers` di quel file.

615* **Le impostazioni gestite bloccano il comando**: impostare [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources) su `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 comunque il comando per un marketplace che le impostazioni gestite stesse dichiarano.

616 

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

618 Come gli utenti accettano un comando headersHelper

619</h4>

620 

621Un 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.

622 

623In una shell non interattiva, passa [`--yes`](/docs/it/plugins-reference#plugin-install) per accettare il comando. Per accettare solo il comando che un'esecuzione precedente con `--json` ha visualizzato, passa [`--accept-command`](/docs/it/plugins-reference#plugin-install) con lo `sha256` che l'esecuzione ha segnalato.

624 

625Claude 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'installazione o l'aggiornamento. Un cambio nella stringa di query da solo non conta.

626 

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

628 Installazioni e aggiornamenti che rifiutano il comando invece di chiedere

629</h5>

630 

631Su qualsiasi operazione diversa da un'installazione 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 versione installata o rimane disinstallato. Quello che l'utente vede dipende dall'operazione:

632 

633* **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 indirizza l'utente alla vista di quel plugin in `/plugin`. Gli altri plugin in un'installazione in blocco si installano comunque. Un plugin che dipende dal plugin rifiutato non si installa fino a quando l'utente non installa il plugin rifiutato da solo.

634* **Aggiornamento automatico in background, o avvio della sessione per un plugin il cui archivio non è mai stato scaricato**: Claude Code elenca il plugin nella scheda Errori di `/plugin` in modo che l'utente sappia di installarlo o aggiornarlo manualmente. Un aggiornamento automatico che trova la voce ancora pubblicizza l'elenco della versione installata non mostra nulla.

635 

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

637 Quando viene eseguito il comando di un'origine `url` del marketplace

638</h5>

639 

640Un `headersHelper` di un'origine `url` del marketplace è 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 installazione o aggiornamento. Il file di impostazioni che lo dichiara decide quando Claude Code lo esegue:

641 

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

643| :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

645| `.claude/settings.json` o `.claude/settings.local.json` di un progetto | Solo dopo che l'utente accetta la [finestra di dialogo di trust dell'area di lavoro](/docs/it/permissions#what-runs-before-you-trust-a-folder) per quella cartella stessa. Una sessione `-p` o SDK non conta come accettazione, e nemmeno il trust concesso a una cartella padre |

646| Impostazioni gestite dal server | Solo dopo che l'utente approva le impostazioni consegnate nella [finestra di dialogo di approvazione della sicurezza](/docs/it/server-managed-settings#security-approval-dialogs) |

647 

648In una sessione `-p` o SDK, Claude Code non può mostrare la finestra di dialogo di approvazione della sicurezza. Applica le altre impostazioni consegnate, ma il recupero del marketplace, e qualsiasi download dell'archivio che ha bisogno del comando, non riesce fino a quando un utente non ha approvato in una sessione interattiva.

649 

650Per una [voce di plugin inline](/docs/it/settings-reference#extraknownmarketplaces) in uno di questi file, Claude Code richiede lo stesso trust 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 installazione o aggiornamento.

651 

652<h3 id="command-sources">

653 Origini dei comandi

654</h3>

655 

656Utilizza `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. Nella versione da v2.1.120 a v2.1.228, l'installazione del plugin non riesce con `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`, e nelle versioni precedenti l'intero marketplace non si carica.

657 

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

659 

660```json theme={null}

661{

662 "name": "my-plugin",

663 "source": {

664 "source": "command",

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

666 }

667}

668```

669 

670Claude 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 dell'uscita del comando, e il percorso può cambiare tra le esecuzioni.

671 

672Claude Code interrompe un comando che viene eseguito più a lungo di `timeout` secondi, e l'installazione o l'aggiornamento non riesce. Claude Code rifiuta anche il percorso stampato in questi casi, e l'installazione o l'aggiornamento non riesce allo stesso modo:

673 

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

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

676* Su Windows, il percorso è un percorso UNC

677 

678Le origini dei comandi accettano questi campi:

679 

680| Campo | Tipo | Descrizione |

681| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

682| `command` | string | Obbligatorio. Comando shell che stampa il percorso assoluto della directory del plugin come una singola riga su stdout e esce con 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 viene loro chiesto di accettare |

683| `timeout` | number | Facoltativo. Numero intero di secondi di attesa per il comando prima di rinunciare (predefinito: 60, massimo: 600) |

684| `mode` | string | Facoltativo. `"copy"` (predefinito) copia la directory stampata nella cache del plugin. `"link"` utilizza la directory stampata al suo posto. Vedi [Modalità copia e modalità link](#copy-mode-and-link-mode) |

685 

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

687 Modalità copia e modalità link

688</h4>

689 

690Con il valore predefinito `"mode": "copy"`, Claude Code copia la directory stampata nella cache del plugin con versione e deriva la [versione del plugin](/docs/it/plugins-reference#version-management) da un hash del contenuto della directory. Il tuo strumento può eliminare o riscrivere la directory dopo l'uscita del comando, 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.

691 

692Imposta `"mode": "link"` per le directory di plugin di grandi dimensioni 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 primo livello 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'installazione non riesce se una voce di primo livello è un symlink che punta al di fuori della directory stampata. Claude Code salta anche l'[installazione della dipendenza del pacchetto Node.js](/docs/it/plugins-reference#node-js-package-dependencies) per un plugin in modalità link, quindi stampa una directory che contiene già qualsiasi `node_modules` di cui il plugin ha bisogno.

693 

694Mantieni la directory stampata al suo posto per tutto il tempo in cui il plugin rimane installato, perché Claude Code carica il plugin attraverso quei link ad ogni avvio. Claude Code deriva la [versione del plugin](/docs/it/plugins-reference#version-management) dal percorso reale della directory stampata e dalle sue voci di primo livello, non dai file all'interno, quindi stampa un percorso diverso per segnalare nuovo contenuto. In una sessione avviata nella directory stampata o in qualsiasi punto al di sotto di essa, Claude Code non carica affatto il plugin.

695 

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

697 

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

699 Come gli utenti accettano il comando

700</h4>

701 

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

703 

704* 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 quell'installazione. Un `claude plugin update` che può procedere sull'accettazione registrata dello stesso comando non mostra nulla.

705* 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. Per accettare solo il comando che un'esecuzione precedente con `--json` ha visualizzato, passa [`--accept-command`](/docs/it/plugins-reference#plugin-install) con lo `sha256` che l'esecuzione ha segnalato.

706* 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 [Quando Claude Code riesegue il comando](#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 origine da comando come dipendenza di un altro plugin, quindi gli utenti lo installano da soli per primi.

707* Se cambi la voce `command`, 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 Errori di `/plugin` mostra il nuovo comando fino a quando l'utente non lo rivede e accetta eseguendo `claude plugin update <plugin>@<marketplace>`.

708 

709Gli amministratori possono bloccare le origini dei comandi in 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 origini dei comandi per impostazione predefinita.

710 

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

712 Quando Claude Code riesegue il comando

713</h4>

714 

715La directory stampata riflette lo stato dello strumento al momento dell'esecuzione del comando, quindi Claude Code esegue il comando di nuovo in questi momenti:

716 

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

718* Una volta per sessione per ogni plugin con origine da comando abilitato, in background, poco dopo l'avvio della sessione. Questa esecuzione non passa attraverso l'aggiornamento automatico del marketplace, quindi non dipende dall'[impostazione di aggiornamento automatico](/docs/it/discover-plugins#configure-auto-updates) del marketplace

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

720 

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

722 

723Quando 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 il ricaricamento 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).

724 

725<h3 id="advanced-plugin-entries">

726 Voci di plugin avanzate

727</h3>

728 

729Questo esempio mostra una voce di plugin che utilizza molti dei campi facoltativi, inclusi percorsi personalizzati per comandi, agenti, hook e server MCP:

730 

731```json theme={null}

732{

733 "name": "enterprise-tools",

734 "source": {

735 "source": "github",

736 "repo": "company/enterprise-plugin"

737 },

738 "description": "Enterprise workflow automation tools",

739 "version": "2.1.0",

740 "author": {

741 "name": "Enterprise Team",

742 "email": "enterprise@example.com"

743 },

744 "homepage": "https://docs.example.com/plugins/enterprise-tools",

745 "repository": "https://github.com/company/enterprise-plugin",

746 "license": "MIT",

747 "keywords": ["enterprise", "workflow", "automation"],

748 "category": "productivity",

749 "commands": [

750 "./commands/core/",

751 "./commands/enterprise/",

752 "./commands/experimental/preview.md"

753 ],

754 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

755 "hooks": {

756 "PostToolUse": [

757 {

758 "matcher": "Write|Edit",

759 "hooks": [

760 {

761 "type": "command",

762 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

763 }

764 ]

765 }

766 ]

767 },

768 "mcpServers": {

769 "enterprise-db": {

770 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

771 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]

772 }

773 },

774 "strict": false

775}

776```

777 

778Cose chiave da notare:

779 

780* **`commands` e `agents`**: puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin e devono rimanere al suo interno.

781 * 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

782* **`${CLAUDE_PLUGIN_ROOT}`**: utilizza questa variabile nei comandi hook e nelle configurazioni del server MCP per fare riferimento ai file all'interno della directory di installazione del plugin.

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

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

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

786 

787Per impostazione predefinita, le skill di un plugin vengono caricate dalla directory `skills/` sotto la sua `source`. I percorsi elencati nel campo `skills` si aggiungono a quella scansione:

788 

789```json theme={null}

790"skills": ["./skills/", "./extra-skills/"]

791```

792 

793Quando 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 skill:

794 

795```json theme={null}

796"source": "./",

797"skills": ["./skills/code-review", "./skills/docs"]

798```

799 

800Con un'origine alla radice del marketplace, i percorsi elencati sono l'insieme completo per quella voce, e altre directory nella cartella `skills/` condivisa non si caricano. Elencare `./skills/` stesso, o la radice del plugin, mantiene la scansione completa. Se nessuno dei percorsi elencati esiste, la scansione predefinita viene eseguita invece.

801 

802<h3 id="strict-mode">

803 Modalità strict

804</h3>

805 

806Il campo `strict` controlla se `plugin.json` è l'autorità per le definizioni dei componenti (skill, agenti, hook, server MCP, stili di output).

807 

808| Valore | Comportamento |

809| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |

810| `true` (predefinito) | `plugin.json` è l'autorità. La voce del marketplace può integrarla con componenti aggiuntivi, e entrambe le fonti vengono unite. |

811| `false` | La voce del marketplace è l'intera definizione. Se il plugin ha anche un `plugin.json` che dichiara componenti, è un conflitto e il plugin non si carica. |

812 

813**Quando utilizzare ogni modalità:**

814 

815* **`strict: true`**: il plugin ha il suo `plugin.json` e gestisce i suoi componenti. La voce del marketplace può aggiungere skill o hook extra in cima. Questo è il valore predefinito e funziona per la maggior parte dei plugin.

816* **`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 quei file sono esposti come skill, agenti, hook, ecc. Utile quando il marketplace ristruttura o cura i componenti di un plugin diversamente da quanto inteso dall'autore del plugin.

817 

818<h2 id="host-and-distribute-marketplaces">

819 Ospitare e distribuire marketplace

820</h2>

821 

822Quando gli utenti aggiungono un marketplace ospitato in un repository git, o installano un plugin basato su git che elenca, Claude Code clona quel repository del marketplace o del plugin sulla loro macchina. Il clone non scarica mai il contenuto di [Git LFS](https://git-lfs.com), quindi i file tracciati da LFS arrivano come file puntatore. Mantieni i file di cui i tuoi plugin hanno bisogno fuori da LFS.

823 

824<h3 id="host-on-github-recommended">

825 Ospitare su GitHub (consigliato)

826</h3>

827 

828GitHub è il modo consigliato per ospitare e distribuire un marketplace:

829 

8301. **Creare un repository**: configurare un nuovo repository per il tuo marketplace

8312. **Aggiungere il file marketplace**: creare `.claude-plugin/marketplace.json` con le definizioni dei tuoi plugin

8323. **Condividere con i team**: gli utenti aggiungono il tuo marketplace con `/plugin marketplace add owner/repo`

833 

834**Vantaggi**: funzionalità integrate di controllo versione, tracciamento dei problemi e collaborazione in team.

835 

836<h3 id="host-on-other-git-services">

837 Ospitare su altri servizi git

838</h3>

839 

840Qualsiasi servizio di hosting git funziona, come GitLab, Bitbucket e server self-hosted. Gli utenti aggiungono con l'URL completo del repository:

841 

842```shell theme={null}

843/plugin marketplace add https://gitlab.com/company/plugins.git

844```

845 

846<h3 id="private-repositories">

847 Repository privati

848</h3>

849 

850Claude Code supporta l'installazione di plugin da repository privati. Se distribuisci il tuo marketplace attraverso [**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 attraverso la connessione GitHub o GitLab della tua organizzazione su claude.ai. Vedi [Distribuire attraverso le impostazioni dell'organizzazione](#distribute-through-organization-settings) per sapere quali fonti di plugin possono essere private.

851 

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

853 Comandi che esegui

854</h4>

855 

856Quando 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 allo stesso modo del 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. La scorciatoia GitHub `owner/repo` clona per impostazione predefinita su SSH; imposta [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/it/env-vars#variables) per clonarli su HTTPS invece.

857 

858<h4 id="background-auto-updates">

859 Aggiornamenti automatici in background

860</h4>

861 

862Il controllo di aggiornamento in background verifica il remote del marketplace per i nuovi commit con i tuoi helper di credenziali git configurati, allo stesso modo dei comandi che esegui. Per i remote SSH, una chiave caricata in `ssh-agent` autentica il controllo. Claude Code esegue il controllo in modo non interattivo: disattiva i prompt del terminale di git e i programmi askpass, e dice agli helper di credenziali di non richiedere. Se il controllo può autenticarsi a un repository privato su HTTPS dipende dal tuo helper:

863 

864* Un helper che può fornire una credenziale memorizzata senza richiedere autentica il controllo. Git Credential Manager, l'helper Keychain di macOS e `git-credential-store` funzionano in questo modo una volta che contengono una credenziale per l'host.

865* Un helper che ha bisogno di richiedere non può rispondere in background. L'aggiornamento fallisce silenziosamente e il checkout esistente rimane al suo posto, quindi i tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione. Esegui `/plugin marketplace update <name>` per aggiornare il marketplace con le tue credenziali.

866 

867Quando il controllo trova il checkout aggiornato, Claude Code lo lascia così com'è. Quando il controllo trova nuovi commit, o fallisce perché non riesce a raggiungere o autenticarsi al remote, Claude Code clona di nuovo il marketplace e scambia il nuovo clone. Se quel clone fallisce, il checkout esistente rimane al suo posto. La re-clonazione può [scadere su repository di grandi dimensioni](#git-operations-time-out).

868 

869Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:

870 

871* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare la re-clonazione quando il controllo in background non riesce a raggiungere o autenticarsi al remote. I tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione, e gli aggiornamenti manuali con `/plugin marketplace update` continuano a autenticarsi con le tue credenziali.

872* Configura un helper di credenziali git, ad esempio con `gh auth setup-git` per GitHub, in modo che il controllo in background e la re-clonazione possano autenticarsi senza richiedere.

873 

874L'impostazione di 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`.

875 

876<Note>

877 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 workflow predefinito può accedere solo al repository del workflow stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app.

878</Note>

879 

880<h3 id="distribute-through-organization-settings">

881 Distribuire attraverso le impostazioni dell'organizzazione

882</h3>

883 

884Se distribuisci plugin attraverso [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) su un piano Team o Enterprise, si applicano queste regole di origine:

885 

886* Su github.com e gitlab.com, il repository del marketplace deve essere privato o interno. La sincronizzazione dell'organizzazione legge il repository attraverso la connessione che corrisponde al suo host:

887 * **github.com**: l'app GitHub di Claude

888 * **Il tuo host GitHub Enterprise Server**: la tua organizzazione [GitHub Enterprise App](/docs/it/github-enterprise-server#admin-setup)

889 * **gitlab.com o la tua istanza GitLab auto-gestita**: il token di accesso nella configurazione [GitLab](#sync-a-gitlab-hosted-marketplace) della tua organizzazione per quell'host

890* 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, come `./plugins/deploy-tools`.

891* Un'origine di plugin può essere privata in tre casi:

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

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

894 * Un'origine `url` o `git-subdir` sullo stesso host GitLab del repository del marketplace. Su gitlab.com, l'origine deve anche trovarsi sotto lo stesso spazio dei nomi del gruppo di primo livello o dell'utente del repository del marketplace.

895* Qualsiasi altra origine di plugin deve essere un repository pubblico su github.com, gitlab.com o bitbucket.org, che la sincronizzazione dell'organizzazione recupera senza credenziali. La sincronizzazione dell'organizzazione rifiuta le origini di plugin su host che queste regole non coprono.

896 

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

898 

899Per 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 pacchettizza ogni plugin durante la distribuzione, quindi gli utenti non hanno mai bisogno di accesso a un repository di origine separato.

900 

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

902 

903```json theme={null}

904{

905 "name": "deploy-tools",

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

907}

908```

909 

910<h4 id="sync-a-gitlab-hosted-marketplace">

911 Sincronizzare un marketplace ospitato su GitLab

912</h4>

913 

914Per sincronizzare un marketplace da gitlab.com o da un'istanza GitLab auto-gestita, un [Owner](/docs/it/server-managed-settings#access-control) aggiunge prima una configurazione GitLab per quell'host in [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code). Le configurazioni GitLab sono in beta pubblica e si applicano solo alla sincronizzazione del marketplace dei plugin. L'aggiunta di una non rende i repository GitLab disponibili alle [sessioni cloud](/docs/it/claude-code-on-the-web#limitations). Vedi [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) per i passaggi di configurazione.

915 

916Quando aggiungi il marketplace, inserisci l'URL HTTPS del progetto, come `https://gitlab.example.com/platform/claude-plugins`. I progetti nei sottogruppi annidati funzionano. La sincronizzazione dell'organizzazione legge il ramo predefinito del progetto. Se attivi **Sync automatically**, solo i push al ramo predefinito avviano una sincronizzazione.

917 

918<h4 id="keep-executables-out-of-the-top-level-bin-directory">

919 Mantenere gli eseguibili fuori dalla directory bin di primo livello

920</h4>

921 

922Non includere una directory `bin/` di primo livello in nessun plugin che distribuisci attraverso le 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:

923 

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

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

926 

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

928 

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

930 Richiedere marketplace per il tuo team

931</h3>

932 

933Puoi 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`:

934 

935```json theme={null}

936{

937 "extraKnownMarketplaces": {

938 "company-tools": {

939 "source": {

940 "source": "github",

941 "repo": "your-org/claude-plugins"

942 }

943 }

944 }

945}

946```

947 

948Puoi anche specificare quali plugin devono essere abilitati per impostazione predefinita:

949 

950```json theme={null}

951{

952 "enabledPlugins": {

953 "code-formatter@company-tools": true,

954 "deployment-tools@company-tools": true

955 }

956}

957```

958 

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

960 

961<Note>

962 Se utilizzi un'origine 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 è memorizzato una volta per utente in `~/.claude/plugins/known_marketplaces.json`, non per progetto.

963</Note>

964 

965<h3 id="pre-populate-plugins-for-containers">

966 Pre-popolare plugin per i container

967</h3>

968 

969Per le immagini di container e gli ambienti CI, puoi pre-popolare una directory di plugin al momento della compilazione in modo che Claude Code inizi 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.

970 

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

972 

973La directory seed rispecchia la struttura di `~/.claude/plugins`:

974 

975```

976$CLAUDE_CODE_PLUGIN_SEED_DIR/

977 known_marketplaces.json

978 marketplaces/<name>/...

979 cache/<marketplace>/<plugin>/<version>/...

980```

981 

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

983 

984Per 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ì:

985 

986```bash theme={null}

987CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins

988CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

989```

990 

991Quindi 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.

992 

993All'avvio, Claude Code registra i marketplace trovati nel `known_marketplaces.json` del seed nella configurazione primaria e utilizza le cache di plugin trovate sotto `cache/` al loro posto senza re-clonazione. Questo funziona sia in modalità interattiva che in modalità non interattiva con il flag `-p`.

994 

995Dettagli del comportamento:

996 

997* **Sola lettura**: Claude Code non scrive mai nella directory seed.

998* **Auto-aggiornamenti disabilitati**: i marketplace seed non si auto-aggiornano.

999* **Le voci seed hanno la precedenza**: i marketplace dichiarati nel seed sovrascrivono le voci corrispondenti nella configurazione dell'utente ad ogni avvio. Per rinunciare a un plugin seed, utilizza `/plugin disable` piuttosto che rimuovere il marketplace.

1000* **Risoluzione del percorso**: Claude Code individua il contenuto del marketplace sondando `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` al runtime, non fidandosi dei percorsi memorizzati all'interno del JSON del seed. Ciò significa che il seed funziona correttamente anche quando montato in un percorso diverso da dove è stato compilato.

1001* **La mutazione è bloccata**: l'esecuzione di `/plugin marketplace remove` o `/plugin marketplace update` su un marketplace gestito da seed fallisce con una guida per chiedere al tuo amministratore di aggiornare l'immagine seed.

1002* **Si 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.

1003 

1004<h3 id="managed-marketplace-restrictions">

1005 Restrizioni del marketplace gestito

1006</h3>

1007 

1008Per le organizzazioni che richiedono un controllo rigoroso sulle origini 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 rifiutare anche 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 contestuale, imposta [`pluginSuggestionMarketplaces`](/docs/it/settings-reference#pluginsuggestionmarketplaces).

1009 

1010`strictKnownMarketplaces` corrisponde al marketplace da cui proviene un plugin, non alle voci al suo interno, quindi gli utenti possono comunque 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).

1011 

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

1013 

1014| Valore | Comportamento |

1015| -------------------------- | -------------------------------------------------------------------------------------------------- |

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

1017| Array vuoto `[]` | Blocco completo. Blocca ogni origine di marketplace, incluso il marketplace ufficiale di Anthropic |

1018| Elenco di origini | Allowlist applicato. Gli utenti possono aggiungere solo marketplace che corrispondono a una voce |

1019 

1020<h4 id="common-configurations">

1021 Configurazioni comuni

1022</h4>

1023 

1024Disabilita tutte le aggiunte di marketplace, incluso il marketplace ufficiale di Anthropic:

1025 

1026```json theme={null}

1027{

1028 "strictKnownMarketplaces": []

1029}

1030```

1031 

1032Claude Code scarica i plugin [sincronizzati da claude.ai](/docs/it/plugins-reference#synced-plugins) dal tuo account piuttosto che da un marketplace, quindi questo blocco non li copre. Per fermare anche quelli, imposta [`syncClaudeAiPlugins`](/docs/it/settings-reference#syncclaudeaiplugins) a `false` nelle impostazioni gestite, o disattiva Skills per la tua organizzazione su claude.ai.

1033 

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

1035 

1036```json theme={null}

1037{

1038 "strictKnownMarketplaces": [

1039 {

1040 "source": "github",

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

1042 }

1043 ]

1044}

1045```

1046 

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

1048 

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

1050 

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

1052* Macchine in cui Claude Code è già stato eseguito in modo interattivo secondo una politica che ha bloccato il marketplace, come il blocco dell'array vuoto. Claude Code registra il tentativo bloccato e non ritenta dopo il cambio della politica.

1053 

1054Su 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, oppure esegui `claude plugin marketplace add anthropics/claude-plugins-official`.

1055 

1056Consenti solo marketplace specifici:

1057 

1058```json theme={null}

1059{

1060 "strictKnownMarketplaces": [

1061 {

1062 "source": "github",

1063 "repo": "acme-corp/approved-plugins"

1064 },

1065 {

1066 "source": "github",

1067 "repo": "acme-corp/security-tools",

1068 "ref": "v2.0"

1069 },

1070 {

1071 "source": "url",

1072 "url": "https://plugins.example.com/marketplace.json"

1073 }

1074 ]

1075}

1076```

1077 

1078Consenti 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.

1079 

1080```json theme={null}

1081{

1082 "strictKnownMarketplaces": [

1083 {

1084 "source": "github",

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

1086 }

1087 ]

1088}

1089```

1090 

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

1092 

1093```json theme={null}

1094{

1095 "strictKnownMarketplaces": [

1096 {

1097 "source": "hostPattern",

1098 "hostPattern": "^github\\.example\\.com$"

1099 }

1100 ]

1101}

1102```

1103 

1104Consenti marketplace basati su filesystem da una directory specifica utilizzando la corrispondenza del modello regex sul percorso:

1105 

1106```json theme={null}

1107{

1108 "strictKnownMarketplaces": [

1109 {

1110 "source": "pathPattern",

1111 "pathPattern": "^/opt/approved/"

1112 }

1113 ]

1114}

1115```

1116 

1117Utilizza `".*"` come `pathPattern` per consentire qualsiasi percorso del filesystem controllando comunque le origini di rete con `hostPattern`.

1118 

1119<Note>

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

1121 

1122 Il marketplace ufficiale di Anthropic è l'unico che Claude Code registra di per sé, e solo quando l'allowlist lo consente. La registrazione automatica manca anche su alcune macchine, come gli ambienti non interattivi e le macchine in cui una politica 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).

1123</Note>

1124 

1125<h4 id="how-restrictions-work">

1126 Come funzionano le restrizioni

1127</h4>

1128 

1129Le restrizioni vengono controllate prima di qualsiasi operazione di rete o filesystem. Il controllo viene eseguito sull'aggiunta del marketplace e sull'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin. Se un marketplace è stato aggiunto prima che la politica fosse configurata e la sua origine non corrisponde più all'allowlist, Claude Code rifiuta di installare o aggiornare plugin da esso. Lo stesso controllo si applica a `blockedMarketplaces`.

1130 

1131Dove i due elenchi vengono applicati dipende da dove li imposti:

1132 

1133* **La console di amministrazione claude.ai**: Claude Code applica entrambi gli elenchi nelle sessioni che [leggono le impostazioni gestite dal server](/docs/it/managed-settings#where-and-when-a-policy-applies). claude.ai li controlla anche quando chiunque nella tua organizzazione aggiunge un nuovo marketplace da un repository git su claude.ai, o da **Customize** nell'app Claude Desktop al di fuori della sua scheda Code. Questo copre un marketplace che un membro aggiunge per il proprio account e uno aggiunto per l'intera organizzazione in [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins). claude.ai rifiuta un repository che l'allowlist non ammette o che la blocklist nomina. Non ri-controlla un marketplace che è stato aggiunto in entrambi i posti prima che tu imposti gli elenchi, e non controlla i plugin caricati.

1134* **Un file di impostazioni gestite, una politica a livello di sistema operativo o un'altra origine gestita**: Claude Code applica entrambi gli elenchi dove legge quella fonte. claude.ai non la legge.

1135 

1136Per bloccare ogni repository di marketplace sotto un proprietario GitHub, utilizza 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'allowlist, vedi [Owner wildcards](/docs/it/settings-reference#owner-wildcards).

1137 

1138Quando 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 bare `github.com` o `gitlab.com`, Claude Code lo controlla anche rispetto alle 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 corrispondeva a una voce `url` solo rispetto a un URL che recuperava come file `marketplace.json` ospitato.

1139 

1140L'allowlist utilizza la corrispondenza esatta per la maggior parte dei tipi di origine, a parte le voci `github` con owner-wildcard. Affinché un marketplace sia consentito, tutti i campi specificati devono corrispondere:

1141 

1142* Per le origini GitHub: `repo` è obbligatorio, nominando un repository o utilizzando 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'allowlist, e la stessa regola si applica a `path`

1143* Per le origini URL: l'URL completo deve corrispondere esattamente

1144* Per le origini `hostPattern`: l'host del marketplace viene confrontato con il modello regex

1145* Per le origini `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex

1146 

1147La corrispondenza esatta dell'allowlist 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 i moduli `https://`, `ssh://` e `user@host:path` corrispondano tutti.

1148 

1149Un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) è abbinato per host: una voce `hostPattern` che corrisponde a `claude.ai` lo governa, in `strictKnownMarketplaces` e in `blockedMarketplaces`. Sull'allowlist, tale voce non ammette i caricamenti personali su claude.ai di un membro. Richiede Claude Code v2.1.273 o successivo.

1150 

1151Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/docs/it/managed-settings), i singoli utenti e le configurazioni del progetto non possono ignorare queste restrizioni.

1152 

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

1154 

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

1156 Risoluzione della versione e canali di rilascio

1157</h3>

1158 

1159Le 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 origini basate su git, se ometti `version`, Claude Code utilizza lo SHA del commit risolto della fonte, quindi gli utenti ricevono 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 origini `archive`.

1160 

1161<Warning>

1162 L'impostazione di `version` fissa il plugin per ogni tipo di origine tranne [`command`](#command-sources), la cui versione include sempre un hash di ciò che il comando ha prodotto. Un plugin [caricato in posizione](/docs/it/plugins-reference#plugin-caching-and-file-resolution) da un marketplace aggiunto come directory locale non è fissato neanche. Se dichiari `"version": "1.0.0"` in `plugin.json` e fai il push di nuovi commit senza cambiare quella stringa, gli utenti esistenti di quelle origini mantengono la copia memorizzata nella cache, perché Claude Code vede la stessa versione. Aumenta il campo ad ogni rilascio, o omettilo per ricadere nella versione risolta.

1163 

1164 Evita di impostare `version` sia in `plugin.json` che nella voce del marketplace. Claude Code utilizza sempre il valore `plugin.json` senza avvertimento, quindi una versione del manifest obsoleta può mascherare una versione che hai impostato in `marketplace.json`.

1165</Warning>

1166 

1167<h4 id="set-up-release-channels">

1168 Configurare i canali di rilascio

1169</h4>

1170 

1171Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a ref o SHA diversi dello stesso repository. Puoi quindi dare a ogni gruppo di utenti il suo marketplace attraverso le impostazioni gestite in uno di due modi:

1172 

1173* 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 origini gestite](/docs/it/managed-settings#precedence-within-the-managed-tier) dice se il file o il profilo per gruppo si applica su un dispositivo che ha anche un'origine a livello di organizzazione.

1174* Definisci una [politica del gateway delle app Claude](/docs/it/claude-apps-gateway-config#managed) per gruppo. Il gateway applica la prima politica la cui regola di corrispondenza si adatta a un utente, quindi ordina le politiche in modo che ogni utente raggiunga la politica del suo gruppo. La `extraKnownMarketplaces` di una politica di gruppo sostituisce la mappa della politica catch-all piuttosto che unirsi ad essa, quindi elenca ogni marketplace di cui il gruppo ha bisogno nella politica del gruppo, non solo il suo marketplace del canale.

1175 

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

1177 

1178<Warning>

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

1180</Warning>

1181 

1182<h5 id="example">

1183 Esempio

1184</h5>

1185 

1186```json theme={null}

1187{

1188 "name": "stable-tools",

1189 "plugins": [

1190 {

1191 "name": "code-formatter",

1192 "source": {

1193 "source": "github",

1194 "repo": "acme-corp/code-formatter",

1195 "ref": "stable"

1196 }

1197 }

1198 ]

1199}

1200```

1201 

1202```json theme={null}

1203{

1204 "name": "latest-tools",

1205 "plugins": [

1206 {

1207 "name": "code-formatter",

1208 "source": {

1209 "source": "github",

1210 "repo": "acme-corp/code-formatter",

1211 "ref": "latest"

1212 }

1213 }

1214 ]

1215}

1216```

1217 

1218<h5 id="assign-channels-to-user-groups">

1219 Assegnare i canali ai gruppi di utenti

1220</h5>

1221 

1222Assegna ogni marketplace al suo gruppo di utenti attraverso le impostazioni gestite endpoint-managed per gruppo o la politica del gateway descritte in [Configurare i canali di rilascio](#set-up-release-channels). Ad esempio, il gruppo stabile riceve:

1223 

1224```json theme={null}

1225{

1226 "extraKnownMarketplaces": {

1227 "stable-tools": {

1228 "source": {

1229 "source": "github",

1230 "repo": "acme-corp/stable-tools"

1231 }

1232 }

1233 }

1234}

1235```

1236 

1237Il gruppo early-access riceve `latest-tools` invece:

1238 

1239```json theme={null}

1240{

1241 "extraKnownMarketplaces": {

1242 "latest-tools": {

1243 "source": {

1244 "source": "github",

1245 "repo": "acme-corp/latest-tools"

1246 }

1247 }

1248 }

1249}

1250```

1251 

1252<h4 id="pin-dependency-versions">

1253 Fissare le versioni delle dipendenze

1254</h4>

1255 

1256Un plugin può limitare le sue dipendenze a un intervallo semver in modo che gli aggiornamenti a una dipendenza non rompano il plugin dipendente. Vedi [Constrain plugin dependency versions](/docs/it/plugin-dependencies) per la convenzione del tag git `{plugin-name}--v{version}`, la sintassi dell'intervallo e come più vincoli sulla stessa dipendenza vengono combinati.

1257 

1258<h3 id="rename-or-remove-a-plugin">

1259 Rinominare o rimuovere un plugin

1260</h3>

1261 

1262Il `name` di un plugin è il suo identificatore stabile. Gli utenti lo referenziano in `enabledPlugins`, `pluginConfigs` e comandi `/plugin install`, quindi cambiarlo rompe ogni installazione esistente. Per cambiare l'etichetta mostrata nell'interfaccia utente senza rompere le installazioni, imposta [`displayName`](#optional-plugin-fields) e mantieni `name` invariato.

1263 

1264Se devi cambiare il `name` di un plugin, o rimuovi un plugin dall'array `plugins`, aggiungi una voce `renames` di primo livello 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:

1265 

1266```json theme={null}

1267{

1268 "name": "acme-tools",

1269 "owner": { "name": "Acme" },

1270 "plugins": [

1271 { "name": "code-formatter", "source": "./plugins/code-formatter" }

1272 ],

1273 "renames": {

1274 "formatter": "code-formatter",

1275 "legacy-linter": null

1276 }

1277}

1278```

1279 

1280Quando un utente avvia Claude Code con il vecchio nome ancora nelle sue impostazioni, Claude Code segue la mappa `renames`:

1281 

1282* 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 nella nuova chiave negli ambiti di impostazioni utente, progetto e locale sia per `enabledPlugins` che per `pluginConfigs`, quindi l'avviso appare una volta.

1283* Per una voce `null`, Claude Code elimina la vecchia chiave e l'avviso segnala che il plugin è stato rimosso dal marketplace.

1284* Se il plugin rinominato utilizza un'origine remota come `github` o `npm`, Claude Code segnala `plugin-cache-miss` dopo la ridenominazione e l'utente deve eseguire `/plugin install` una volta per recuperarlo con il nuovo nome.

1285 

1286Tratta `renames` come una storia 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`.

1287 

1288Esegui `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`.

1289 

1290<Note>

1291 Le impostazioni gestite e di politica sono di sola lettura per Claude Code, quindi i plugin abilitati lì non possono essere riscritti automaticamente. Il plugin rinominato continua a caricarsi ad ogni sessione, ma l'avviso di ridenominazione ricorre fino a quando un amministratore non aggiorna `enabledPlugins` nel file di impostazioni gestite per utilizzare il nuovo nome. Lo stesso si applica ai plugin abilitati attraverso altre origini di sola lettura come `--add-dir`.

1292</Note>

1293 

1294Le versioni precedenti di Claude Code ignorano il campo `renames` e segnalano `plugin-not-found` per il vecchio nome.

1295 

1296<h2 id="validation-and-testing">

1297 Validazione e test

1298</h2>

1299 

1300Testa il tuo marketplace prima di condividerlo. La validazione controlla la struttura dei file; per testare se un plugin cambia il comportamento di Claude su prompt realistici, esegui la sua suite di eval con [`claude plugin eval`](/docs/it/plugin-evals) prima di pubblicare una nuova versione.

1301 

1302Dalla tua directory marketplace, valida la sintassi JSON:

1303 

1304```bash theme={null}

1305claude plugin validate .

1306```

1307 

1308O da Claude Code:

1309 

1310```shell theme={null}

1311/plugin validate .

1312```

1313 

1314Aggiungi il marketplace per il test:

1315 

1316```shell theme={null}

1317/plugin marketplace add ./path/to/marketplace

1318```

1319 

1320Installa un plugin di test per verificare che tutto funzioni:

1321 

1322```shell theme={null}

1323/plugin install test-plugin@marketplace-name

1324```

1325 

1326Per i flussi di lavoro di test completi dei plugin, vedi [Testa i tuoi plugin localmente](/docs/it/plugins#test-your-plugins-locally). Per la risoluzione dei problemi tecnici, vedi [Plugins reference](/docs/it/plugins-reference).

1327 

1328<h2 id="manage-marketplaces-from-the-cli">

1329 Gestisci marketplace dalla CLI

1330</h2>

1331 

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

1333 

1334<h3 id="plugin-marketplace-add">

1335 Plugin marketplace add

1336</h3>

1337 

1338Aggiungi un marketplace da un repository GitHub, URL git, URL remoto o percorso locale.

1339 

1340```bash theme={null}

1341claude plugin marketplace add <source> [options]

1342```

1343 

1344**Argomenti:**

1345 

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

1347 

1348Un 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.

1349 

1350**Opzioni:**

1351 

1352| Opzione | Descrizione | Predefinito |

1353| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1354| `--scope <scope>` | Dove dichiarare il marketplace: `user`, `project` o `local`. Vedi [Plugin installation scopes](/docs/it/plugins-reference#plugin-installation-scopes) | `user` |

1355| `--sparse <paths...>` | Limita il checkout a directory specifiche tramite git sparse-checkout. Utile per i monorepo | |

1356| `--claudeai` | Leggi l'argomento come il nome di un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) invece di una fonte. Richiede Claude Code v2.1.273 o successivo | |

1357 

1358Aggiungi un marketplace da GitHub utilizzando la scorciatoia `owner/repo`:

1359 

1360```bash theme={null}

1361claude plugin marketplace add acme-corp/claude-plugins

1362```

1363 

1364Fissa a un branch o tag specifico con `@ref`:

1365 

1366```bash theme={null}

1367claude plugin marketplace add acme-corp/claude-plugins@v2.0

1368```

1369 

1370Aggiungi da un URL git su un host non-GitHub:

1371 

1372```bash theme={null}

1373claude plugin marketplace add https://gitlab.example.com/team/plugins.git

1374```

1375 

1376Aggiungi da un URL remoto che serve il file `marketplace.json` direttamente:

1377 

1378```bash theme={null}

1379claude plugin marketplace add https://example.com/marketplace.json

1380```

1381 

1382Aggiungi da una directory locale per il test:

1383 

1384```bash theme={null}

1385claude plugin marketplace add ./my-marketplace

1386```

1387 

1388Dichiara il marketplace a livello di progetto in modo che sia condiviso con il tuo team tramite `.claude/settings.json`:

1389 

1390```bash theme={null}

1391claude plugin marketplace add acme-corp/claude-plugins --scope project

1392```

1393 

1394Per un monorepo, limita il checkout alle directory che contengono il contenuto del plugin:

1395 

1396```bash theme={null}

1397claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1398```

1399 

1400Aggiungi un [marketplace ospitato su claude.ai](/docs/it/discover-plugins#add-from-claude-ai) dal nome stampato nella sezione `From claude.ai:` di `claude plugin marketplace list`:

1401 

1402```bash theme={null}

1403claude plugin marketplace add --claudeai claudeai-organization-library

1404```

1405 

1406Con `--claudeai`, il comando rifiuta `--scope` e `--sparse`. Il marketplace è ospitato per il tuo account, non dichiarato in un file di impostazioni, quindi non puoi condividerlo tramite il `.claude/settings.json` di un progetto.

1407 

1408<h3 id="plugin-marketplace-list">

1409 Plugin marketplace list

1410</h3>

1411 

1412Elenca tutti i marketplace configurati.

1413 

1414```bash theme={null}

1415claude plugin marketplace list [options]

1416```

1417 

1418**Opzioni:**

1419 

1420| Opzione | Descrizione |

1421| :------- | :--------------- |

1422| `--json` | Output come JSON |

1423 

1424Con `--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.

1425 

1426Un marketplace [claude.ai](/docs/it/discover-plugins#add-from-claude-ai) aggiunto non ha un clone locale, quindi la sua voce contiene i suoi identificatori claude.ai, `marketplaceId` e `organizationUuid`, al posto di `installLocation`.

1427 

1428In sessioni di terminale dove [i plugin si sincronizzano dal tuo account claude.ai](/docs/it/plugins-reference#synced-plugins), l'elenco di testo termina con una sezione `From claude.ai:` che nomina ciò che claude.ai elenca per il tuo account oltre ai marketplace che hai aggiunto. Per aggiungerne uno, vedi [Aggiungi da claude.ai](/docs/it/discover-plugins#add-from-claude-ai). L'output `--json` copre solo i marketplace configurati e lascia fuori quella sezione. Richiede Claude Code v2.1.273 o successivo.

1429 

1430<h3 id="plugin-marketplace-remove">

1431 Plugin marketplace remove

1432</h3>

1433 

1434Rimuovi un marketplace configurato. L'alias `rm` è accettato anche.

1435 

1436```bash theme={null}

1437claude plugin marketplace remove <name> [options]

1438```

1439 

1440**Argomenti:**

1441 

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

1443 

1444**Opzioni:**

1445 

1446| Opzione | Descrizione | Predefinito |

1447| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- |

1448| `--scope <scope>` | Limita la rimozione a un singolo ambito di impostazioni: `user`, `project` o `local`. Vedi [Plugin installation scopes](/docs/it/plugins-reference#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) |

1449 

1450<Warning>

1451 La rimozione di un marketplace dal suo ultimo ambito rimanente disinstalla anche tutti i plugin che hai installato da esso. Per aggiornare un marketplace senza perdere i plugin installati, usa `claude plugin marketplace update` invece.

1452</Warning>

1453 

1454<h3 id="plugin-marketplace-update">

1455 Plugin marketplace update

1456</h3>

1457 

1458Aggiorna 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.

1459 

1460```bash theme={null}

1461claude plugin marketplace update [name]

1462```

1463 

1464**Argomenti:**

1465 

1466* `[name]`: nome del marketplace da aggiornare, come mostrato da `claude plugin marketplace list`. Aggiorna tutti i marketplace se omesso

1467 

1468Sia `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](#pre-populate-plugins-for-containers).

1469 

1470<h2 id="troubleshooting">

1471 Risoluzione dei problemi

1472</h2>

1473 

1474<h3 id="marketplace-not-loading">

1475 Marketplace non carica

1476</h3>

1477 

1478**Sintomi**: Non è possibile aggiungere il marketplace o visualizzare i plugin da esso

1479 

1480**Soluzioni**:

1481 

1482* Verificare che l'URL del marketplace sia accessibile

1483* Controllare che `.claude-plugin/marketplace.json` esista nel percorso specificato

1484* Assicurarsi che la sintassi JSON sia valida utilizzando `claude plugin validate .` o `/plugin validate .` dalla directory del marketplace. Per controllare il frontmatter di skill, agent e command, vedere [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest)

1485* Per i repository privati, confermare di avere i permessi di accesso

1486 

1487<h3 id="marketplace-validation-errors">

1488 Errori di validazione del marketplace

1489</h3>

1490 

1491Eseguire `claude plugin validate .` o `/plugin validate .` dalla directory del marketplace per verificare la presenza di 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 →`.

1492 

1493A partire da Claude Code v2.1.196, il pass per voce include anche:

1494 

1495* plugin il cui `source` è `.`

1496* viene eseguito quando `marketplace.json` è al di fuori di una directory `.claude-plugin`, risolvendo le origini rispetto alla directory del file stesso

1497* segnala i problemi di ogni voce anche quando un'altra parte del file ha errori di schema

1498 

1499Le versioni precedenti saltano i plugin nella radice del marketplace e scendono solo da `.claude-plugin/marketplace.json`.

1500 

1501Da una directory del marketplace, Claude Code non apre i file skill, agent, command o hook dei plugin. Per trovare errori in questi file, vedere [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:

1502 

1503| Errore | Causa | Soluzione |

1504| :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1505| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory denominata non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file skill, agent o command da controllare | Eseguire dalla radice del marketplace, o creare `.claude-plugin/marketplace.json` con i campi obbligatori |

1506| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controllare la presenza di virgole mancanti, virgole extra o stringhe non quotate |

1507| `Duplicate plugin name "x" found in marketplace` | Due plugin condividono lo stesso nome | Assegnare a ogni plugin un valore `name` univoco |

1508| `plugins[0].source: Path contains ".."` | Un segmento del percorso di origine è `..` | Utilizzare percorsi relativi alla radice del marketplace senza segmenti `..`. Vedere [Relative paths](#relative-paths) |

1509| `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 nuova riga | Rimuovere il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |

1510| `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 nuova riga | Rimuovere il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |

1511 

1512**Avvisi** (non bloccanti):

1513 

1514* `Marketplace has no plugins defined`: aggiungere almeno un plugin all'array `plugins`

1515* `No marketplace description provided`: aggiungere una `description` di livello superiore per aiutare gli utenti a comprendere il marketplace

1516* `Plugin name "x" is not kebab-case`: rinominare utilizzando solo lettere minuscole, cifre e trattini (ad esempio, `my-plugin`). Claude Code accetta altre forme, ma la sincronizzazione del marketplace claude.ai le rifiuta.

1517* `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. Rinominare il marketplace. Prima della v2.1.221, `claude plugin validate` non eseguiva questo controllo.

1518* `Marketplace name "x" is not accepted by Claude Desktop` o `Plugin name "x" is not accepted by Claude Desktop`: Claude Desktop accetta nomi di lunghezza 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. Rinominare il marketplace o il plugin. Prima della v2.1.221, `claude plugin validate` non eseguiva questi controlli.

1519 

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

1521 Validate a plugin or a directory without a manifest

1522</h4>

1523 

1524Per trovare file skill, agent e command il cui frontmatter non viene analizzato, eseguire `claude plugin validate` e denominare la directory che li contiene. Claude Code non guarda al di fuori della directory denominata. Ogni esecuzione tranne una rispetto a un plugin che ha un `plugin.json` richiede Claude Code v2.1.233 o successivo.

1525 

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

1527 Scegliere la directory da denominare

1528</h5>

1529 

1530Claude Code controlla file diversi a seconda di quale directory denominate. Trovare ciò che si desidera controllare nella prima colonna ed eseguire il comando di quella riga:

1531 

1532| Per controllare | Eseguire | Claude Code controlla |

1533| :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1534| 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` nella radice del plugin |

1535| Una directory di skill, agent o command, come un plugin che non ha ancora un `plugin.json` | `claude plugin validate .claude/skills`, `~/.claude/agents` o `./my-plugin/agents` | Ogni file skill, agent o command in quella directory |

1536| 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 con un altro nome, come `plugins/`, non ha un'esecuzione che controlla il suo `SKILL.md` radice |

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

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

1539 

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

1541 Controllare un plugin il cui skill è il suo `SKILL.md` radice

1542</h5>

1543 

1544Quando si esegue `claude plugin validate` rispetto a una directory di plugin, Claude Code non controlla un `SKILL.md` nella radice del plugin. Quando il plugin si trova in una directory denominata `skills`, eseguire il comando due volte:

1545 

1546* Denominare quella directory `skills` per controllare il `SKILL.md` radice del plugin.

1547* Denominare la directory del plugin per controllare il resto.

1548 

1549Quando il plugin si trova con un altro nome, come `plugins/`, l'esecuzione della directory skills non è disponibile e nessuna esecuzione controlla il suo `SKILL.md` radice.

1550 

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

1552 Controllare file dietro symlink

1553</h5>

1554 

1555Quando si esegue `claude plugin validate`, Claude Code non segue i symlink all'interno della directory denominata. Ciò che fa dipende da dove si trova il collegamento:

1556 

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

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

1559* **La directory `skills`, `agents` o `commands` denominata è essa stessa un symlink, o la sua directory padre `.claude` è**: Claude Code segnala un errore e non controlla nulla in essa. Denominare invece la directory reale.

1560 

1561In due casi di skill, l'esecuzione passa con avvisi. Per controllare i file collegati, eseguire di nuovo e denominare una directory che li contiene direttamente:

1562 

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

1564* **Una [voce skill collegata](/docs/it/skills#where-skills-live) in `~/.claude/skills` o `.claude/skills`**: Claude Code segue la voce in una sessione. Per controllarla, denominare una directory chiamata `skills` che contiene la cartella reale.

1565 

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

1567 Leggere i risultati della validazione

1568</h5>

1569 

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

1571 

1572`No manifest found in directory` significa che Claude Code non ha trovato `plugin.json` o `marketplace.json` lì, e nessun file skill, agent o command nelle directory che sonda sotto di essa. Denominare invece la directory `skills`, `agents` o `commands` che contiene i file.

1573 

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

1575 

1576* `YAML frontmatter failed to parse: ...`: correggere lo YAML nel blocco frontmatter del file skill, agent o command. Fino a quando non lo farete, una sessione non legge alcun campo frontmatter dal file

1577* `Invalid JSON syntax: ...` su `hooks/hooks.json`: correggere la sintassi JSON. Fino a quando non lo farete, una sessione carica il plugin senza gli hook in quel file. Claude Code segnala questo errore solo in un'esecuzione di plugin

1578 

1579In un'esecuzione di plugin, Claude Code avverte anche di un `CLAUDE.md` nella radice del plugin. Per i percorsi impostati tramite 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ì.

1580 

1581<h3 id="plugin-installation-failures">

1582 Errori di installazione del plugin

1583</h3>

1584 

1585**Sintomi**: Il marketplace appare ma l'installazione del plugin non riesce

1586 

1587**Soluzioni**:

1588 

1589* Verificare che gli URL di origine del plugin siano accessibili

1590* Controllare che le directory dei plugin contengano i file obbligatori

1591* Per le origini GitHub, assicurarsi che i repository siano pubblici o che si abbia accesso

1592* Testare manualmente le origini dei plugin clonando/scaricando

1593* 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 di commit per SHA, come AWS CodeCommit, il `ref` deve ancora esistere e il commit bloccato deve essere raggiungibile da esso. Se l'installazione continua a non riuscire, confermare che il commit bloccato esiste ancora nel repository

1594 

1595<h3 id="private-repository-authentication-fails">

1596 L'autenticazione del repository privato non riesce

1597</h3>

1598 

1599**Sintomi**: Errori di autenticazione durante l'installazione di plugin da repository privati

1600 

1601**Soluzioni**:

1602 

1603Per l'installazione manuale e gli aggiornamenti:

1604 

1605* Verificare di essere autenticati con il provider git (ad esempio, eseguire `gh auth status` per GitHub)

1606* Controllare che il helper delle credenziali sia configurato: `git config --global credential.helper`

1607* Eseguire `git ls-remote <marketplace-url>` per verificare se git può autenticarsi da solo. Se git chiede un nome utente o una password, archiviare prima la credenziale: per GitHub su HTTPS, eseguire `gh auth setup-git`, e per i remote SSH, caricare la chiave in `ssh-agent`

1608 

1609Per gli aggiornamenti automatici in background:

1610 

1611* Il controllo in background utilizza gli helper delle credenziali git configurati ma non richiede mai, quindi l'helper deve essere in grado di rispondere con una credenziale archiviata. I remote SSH con una chiave caricata in `ssh-agent` si autenticano anche

1612* Se l'helper deve richiedervi, l'aggiornamento in background non riesce silenziosamente e il checkout esistente rimane in place. Accedere all'helper prima in modo che contenga una credenziale per l'host. Per GitHub, eseguire `gh auth login`, quindi `gh auth setup-git`

1613* Quando il controllo trova nuovi commit, o non riesce a raggiungere o autenticarsi al remote, Claude Code ri-clona il marketplace con le stesse credenziali. Il ri-clone potrebbe scadere su repository di grandi dimensioni

1614* Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote

1615* Se il ri-clone scade su un repository di grandi dimensioni, aumentare il limite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)

1616* Oppure aggiornare i marketplace privati manualmente con `/plugin marketplace update <name>`, che utilizza le credenziali

1617 

1618Prima della v2.1.280, il controllo in background veniva eseguito senza gli helper delle credenziali e non poteva autenticarsi ai repository privati su HTTPS.

1619 

1620<h3 id="marketplace-updates-fail-in-offline-environments">

1621 Gli aggiornamenti del marketplace non riescono in ambienti offline

1622</h3>

1623 

1624**Sintomi**: In un ambiente offline o airgapped, l'aggiornamento in background del marketplace non riesce a raggiungere il remote e Claude Code tenta ripetutamente un ri-clone che non può avere successo.

1625 

1626**Causa**: L'aggiornamento in background controlla il remote del marketplace per nuovi commit, e quando il controllo non riesce a raggiungere il remote, Claude Code tenta di clonare il marketplace di nuovo. Offline, il clone non riesce allo stesso modo e il checkout esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva `git pull` nel checkout esistente, spostava il checkout da parte per ri-clonare quando il pull non riusciva, e lo ripristinava in seguito su base best-effort.

1627 

1628L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio. Ogni sessione ripete comunque il tentativo non riuscito, e ogni operazione git può attendere il [timeout di 120 secondi](#git-operations-time-out).

1629 

1630**Soluzione**: Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per saltare il tentativo di ri-clone e continuare a utilizzare il checkout esistente quando il controllo non riesce a raggiungere il remote:

1631 

1632```bash theme={null}

1633export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1634```

1635 

1636Per distribuzioni completamente offline in cui il repository non sarà mai raggiungibile, utilizzare [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) per pre-popolare la directory dei plugin al momento della compilazione.

1637 

1638<h3 id="git-operations-time-out">

1639 Le operazioni Git scadono

1640</h3>

1641 

1642**Sintomi**: L'installazione del plugin o gli aggiornamenti del marketplace non riescono con un errore di timeout come `Git clone timed out after 120s`.

1643 

1644**Causa**: Claude Code utilizza un timeout di 120 secondi per tutte le operazioni git, inclusa la clonazione di repository di plugin e il ri-clone di un marketplace per aggiornarlo. I repository di grandi dimensioni o le connessioni di rete lente potrebbero superare questo limite.

1645 

1646**Soluzione**: Aumentare il timeout utilizzando la variabile di ambiente `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. Il valore è in millisecondi:

1647 

1648```bash theme={null}

1649export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutes

1650```

1651 

1652<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">

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

1654</h3>

1655 

1656**Sintomi**: È stato aggiunto un marketplace tramite un URL come `https://example.com/marketplace.json`, ma i plugin con origini di percorso relativo come `"./plugins/my-plugin"` non riescono a installarsi con `its marketplace entry path does not stay inside the marketplace directory`. I plugin già installati non riescono a caricarsi con `Plugin source path refused`. Entrambi i messaggi hanno una [voce di riferimento dell'errore](/docs/it/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).

1657 

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

1659 

1660**Soluzioni**:

1661 

1662* **Utilizzare origini esterne**: modificare le voci dei plugin in qualsiasi [plugin source](#plugin-sources) diverso da un percorso relativo:

1663 ```json theme={null}

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

1665 ```

1666* **Utilizzare un marketplace basato su Git**: ospitare il marketplace in un repository Git e aggiungerlo con l'URL git. I marketplace basati su Git clonano l'intero repository, rendendo i percorsi relativi funzionanti correttamente.

1667 

1668<h3 id="files-not-found-after-installation">

1669 File non trovati dopo l'installazione

1670</h3>

1671 

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

1673 

1674**Causa**: Claude Code copia i plugin installati in una directory cache, a meno che il plugin non si carichi in place. Una [`command` source in link mode](#copy-mode-and-link-mode) si carica in place, così come una [relative path source](#relative-paths) in un marketplace aggiunto da una directory locale. I percorsi che fanno riferimento a file al di fuori della directory di un plugin copiato (come `../shared-utils`) non funzioneranno perché questi file non vengono copiati.

1675 

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

1677 

1678Per ulteriori strumenti di debug e problemi comuni, vedere [Debugging and development tools](/docs/it/plugins-reference#debugging-and-development-tools).

1679 

1680<h2 id="see-also">

1681 Vedi anche

1682</h2>

1683 

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

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

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

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

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