Go Premium Account

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

This page contains 0 additions and 1688 deletions.

2026

Wed 9 22:58 Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Wed 23 23:57 Thu 24 22:57 Fri 25 23:58

This document has no rendered page for this history range.

plugin-marketplaces.md +0 −1688 deleted

File Deleted View Diff

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

~~5# Criar e distribuir um marketplace de plugins~~

~~7> Crie e hospede marketplaces de plugins para distribuir extensões Claude Code em equipes e comunidades.~~

9Um **marketplace de plugins** é um catálogo que permite distribuir plugins para outros. Os marketplaces fornecem descoberta centralizada, rastreamento de versão, atualizações automáticas e suporte para múltiplos tipos de fonte, incluindo repositórios git e caminhos locais. Este guia mostra como criar seu próprio marketplace para compartilhar plugins com sua equipe ou comunidade.

~~11Procurando instalar plugins de um marketplace existente? Veja [Descobrir e instalar plugins pré-construídos](/docs/pt/discover-plugins).~~

~~13<h2 id="overview">~~

~~14 Visão geral~~

~~15</h2>~~

~~17Criar e distribuir um marketplace envolve:~~

191. **Criar plugins**: construir um ou mais plugins com skills, agents, hooks, MCP servers ou LSP servers. Este guia assume que você já tem plugins para distribuir; veja [Criar plugins](/docs/pt/plugins) para detalhes sobre como criá-los.

~~202. **Criar o arquivo de marketplace**: definir um `marketplace.json` que lista seus plugins e onde encontrá-los. Veja [Criar o arquivo de marketplace](#create-the-marketplace-file).~~

~~213. **Hospedar o marketplace**: fazer push para GitHub, GitLab ou outro host git. Veja [Hospedar e distribuir marketplaces](#host-and-distribute-marketplaces).~~

~~224. **Compartilhar com usuários**: usuários adicionam seu marketplace com `/plugin marketplace add` e instalam plugins individuais. Veja [Descobrir e instalar plugins](/docs/pt/discover-plugins).~~

~~24Depois que seu marketplace estiver ativo, você pode atualizá-lo fazendo push de alterações para seu repositório. Os usuários atualizam sua cópia local com `/plugin marketplace update`.~~

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

~~27 Passo a passo: criar um marketplace local~~

~~28</h2>~~

30Este exemplo cria um marketplace com um plugin: uma skill `quality-review` para revisões de código. Você criará a estrutura de diretórios, adicionará uma skill, criará o manifesto do plugin e o catálogo do marketplace, depois instalará e testará.

~~32<Steps>~~

~~33 <Step title="Criar a estrutura de diretórios">~~

~~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>~~

~~41 <Step title="Criar a skill">~~

~~42 Crie um arquivo `SKILL.md` que define o que a skill `quality-review` faz.~~

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

~~45 ---~~

~~46 description: Revisar código para bugs, segurança e desempenho~~

~~47 ---~~

~~49 Revise o código que selecionei ou as alterações recentes para:~~

~~50 - Possíveis bugs ou casos extremos~~

~~51 - Preocupações de segurança~~

~~52 - Problemas de desempenho~~

~~53 - Melhorias de legibilidade~~

~~55 Seja conciso e acionável.~~

~~56 ```~~

~~57 </Step>~~

~~59 <Step title="Criar o manifesto do plugin">~~

~~60 Crie um arquivo `plugin.json` que descreve o plugin. O manifesto vai no diretório `.claude-plugin/`.~~

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

~~63 {~~

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

~~65 "description": "Adiciona uma skill quality-review para revisões rápidas de código",~~

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

~~67 "author": {~~

~~68 "name": "Seu Nome"~~

~~69 }~~

~~70 }~~

~~71 ```~~

~~73 <Note>~~

74 Definir `version` significa que os usuários só recebem atualizações quando você altera este campo, então aumente-o em cada lançamento. Um plugin com uma [`command` source](#command-sources) não é fixado por este campo. Nem é um plugin [carregado no local](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) de um marketplace adicionado como um diretório local. Se você omitir `version`, a versão vem da próxima fonte em [gerenciamento de versão](/docs/pt/plugins-reference#version-management).

~~75 </Note>~~

~~76 </Step>~~

~~78 <Step title="Criar o arquivo de marketplace">~~

~~79 Crie o catálogo de marketplace que lista seu plugin.~~

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

~~82 {~~

~~83 "name": "my-plugins",~~

~~84 "owner": {~~

~~85 "name": "Seu Nome"~~

~~86 },~~

~~87 "plugins": [~~

~~88 {~~

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

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

~~91 "description": "Adiciona uma skill quality-review para revisões rápidas de código"~~

~~92 }~~

~~93 ]~~

~~94 }~~

~~95 ```~~

~~96 </Step>~~

~~98 <Step title="Adicionar e instalar">~~

99 A partir do diretório que contém `my-marketplace`, inicie Claude Code e execute os seguintes comandos. O comando install abre uma visualização de detalhes do plugin onde você seleciona um escopo de instalação para confirmar a instalação. Verifique o resumo da instalação: se ele relatar `Run /reload-plugins to activate.`, veja [Aplicar alterações de plugin sem reiniciar](/docs/pt/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="Experimentar">

108 Selecione algum código em seu editor e execute sua nova skill. As skills do plugin são nomeadas com o nome do plugin.

~~109~~

110 ```shell theme={null}

111 /quality-review-plugin:quality-review

112 ```

113 </Step>

114</Steps>

~~115~~

116Para saber mais sobre o que os plugins podem fazer, incluindo hooks, agents, MCP servers e LSP servers, veja [Plugins](/docs/pt/plugins).

~~117~~

118<Note>

119 **Como os plugins são instalados**: quando os usuários instalam um plugin, Claude Code copia o diretório do plugin para um local de cache, a menos que o plugin seja carregado no local. Uma [`command` source em link mode](#copy-mode-and-link-mode) é carregada no local, assim como uma [fonte de caminho relativo](#relative-paths) em um marketplace adicionado de um diretório local. Os plugins copiados não podem referenciar arquivos fora de seu diretório usando caminhos como `../shared-utils`, porque esses arquivos não serão copiados.

~~120~~

121 Se você precisar compartilhar arquivos entre plugins, use symlinks. Veja [Plugin caching and file resolution](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) para detalhes.

122</Note>

~~123~~

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

125 Criar o arquivo de marketplace

126</h2>

~~127~~

128Crie `.claude-plugin/marketplace.json` na raiz do seu repositório. Este arquivo define o nome do seu marketplace, informações do proprietário e uma lista de plugins com suas fontes.

~~129~~

130Cada entrada de plugin precisa no mínimo de um `name` e um `source` que diz ao Claude Code onde buscá-lo. Veja o [esquema completo](#marketplace-schema) abaixo para todos os campos disponíveis.

~~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": "Formatação automática de código ao salvar",

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": "Ferramentas de automação de implantação"

156 }

157 ]

158}

159```

~~160~~

161<h2 id="marketplace-schema">

162 Esquema de marketplace

163</h2>

~~164~~

165<h3 id="required-fields">

166 Campos obrigatórios

167</h3>

~~168~~

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

171| `name` | string | Identificador de marketplace em kebab-case, sem espaços, caracteres de controle ou caracteres de formatação bidirecional. Isso é público: os usuários o veem ao instalar plugins (por exemplo, `/plugin install my-tool@your-marketplace`). Cada usuário pode registrar apenas um marketplace por nome: quando adiciona um segundo marketplace com o mesmo nome, Claude Code substitui o primeiro. Para publicar múltiplos plugins sob um nome de marketplace, liste-os todos em um único [`marketplace.json`](#create-the-marketplace-file). | `"acme-tools"` |

~~174~~

175<Note>

176 **Nomes reservados**: os seguintes nomes de marketplace são reservados para uso oficial da Anthropic e não podem ser usados por marketplaces de terceiros: `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`. Nomes que imitam marketplaces oficiais, como `official-claude-plugins` ou `anthropic-plugins-v2`, também são bloqueados. Reservar esses nomes impede que um marketplace de terceiros se apresente como uma fonte publicada pela Anthropic.

~~177~~

178 Claude Code verifica novamente os nomes reservados toda vez que carrega um marketplace, não apenas quando você adiciona um. Um marketplace que foi registrado sob um desses nomes antes do nome se tornar reservado para de carregar e relata que está [registrado de uma fonte não confiável](/docs/pt/errors#marketplace-is-registered-from-an-untrusted-source). Remova esse marketplace e adicione-o novamente da fonte oficial da Anthropic. Um marketplace de terceiros afetado por um nome recém-reservado carrega novamente assim que você o adiciona novamente sob um nome diferente. Antes da v2.1.205, `first-party-plugins` e `healthcare` não eram reservados, e um marketplace já registrado sob um nome reservado continuava carregando. Antes da v2.1.265, `claude-tag-plugins` não era reservado.

~~179~~

180 Você também não pode nomear um marketplace como `npm`, `pip`, `uv`, `cargo`, `github` ou `gh`, em qualquer capitalização. Esta verificação requer Claude Code v2.1.275 ou posterior.

181</Note>

~~182~~

183<h3 id="owner-fields">

184 Campos do proprietário

185</h3>

~~186~~

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

191| `url` | string | Não | Site, perfil do GitHub ou URL da organização |

~~192~~

193<h3 id="optional-fields">

194 Campos opcionais

195</h3>

~~196~~

197| Campo | Tipo | Descrição |

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

199| `$schema` | string | URL do JSON Schema para autocompletar e validação do editor. Claude Code ignora este campo no momento do carregamento. |

200| `description` | string | Breve descrição do marketplace |

201| `version` | string | Versão do manifesto do marketplace |

202| `metadata.pluginRoot` | string | Diretório que Claude Code resolve nomes de fonte de plugin simples. Veja [Caminhos relativos](#relative-paths). Requer Claude Code v2.1.239 ou posterior. |

203| `allowCrossMarketplaceDependenciesOn` | array | Outros marketplaces que plugins neste marketplace podem depender. Dependências de um marketplace não listado aqui são bloqueadas na instalação. Veja [Depender de um plugin de outro marketplace](/docs/pt/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |

204| `renames` | object | Mapa de um antigo `name` de plugin para seu nome atual, ou para `null` se o plugin foi removido. Permite que usuários existentes migrem automaticamente quando você renomeia ou remove uma entrada em `plugins`. Veja [Renomear ou remover um plugin](#rename-or-remove-a-plugin). Requer Claude Code v2.1.193 ou posterior. |

~~205~~

206`description` e `version` também são aceitos sob `metadata` para compatibilidade com versões anteriores.

~~207~~

208<h2 id="plugin-entries">

209 Entradas de plugin

210</h2>

~~211~~

212Cada entrada de plugin no array `plugins` descreve um plugin e onde encontrá-lo. Você pode incluir qualquer campo do [esquema de manifesto de plugin](/docs/pt/plugins-reference#plugin-manifest-schema), como `description`, `version`, `author`, `commands` e `hooks`, além destes campos específicos do marketplace: `source`, `category`, `tags`, `strict`, `relevance`, `headers` e `headersHelper`.

~~213~~

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

215 Campos obrigatórios

216</h3>

~~217~~

218| Campo | Tipo | Descrição |

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

220| `name` | string | Identificador de plugin em kebab-case, sem espaços, caracteres de controle ou caracteres de formatação bidirecional. Isso é público: os usuários o veem ao instalar (por exemplo, `/plugin install my-plugin@marketplace`). |

~~222~~

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

224 Campos de plugin opcionais

225</h3>

~~226~~

227**Campos de metadados padrão:**

~~228~~

229| Campo | Tipo | Descrição |

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

231| `displayName` | string | Nome legível por humanos exibido em superfícies de UI. Quando nem a entrada nem o `plugin.json` do plugin define um, os usuários veem o `name` do plugin. Pode conter espaços e qualquer capitalização. Não é usado para namespacing ou lookup. |

232| `description` | string | Breve descrição do plugin |

233| `version` | string | Versão do plugin. Se definido (aqui ou em `plugin.json`), o plugin é fixado a esta string e os usuários recebem atualizações apenas quando ela muda. Um plugin com uma [`command` source](#command-sources) não é fixado por nenhum dos dois campos. Nem um plugin [carregado no local](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) de um marketplace adicionado como diretório local. Se não definido em nenhum lugar, a versão vem da próxima fonte em [gerenciamento de versão](/docs/pt/plugins-reference#version-management). |

234| `author` | object | Informações do autor do plugin (`name` obrigatório; `email` e `url` opcionais) |

235| `homepage` | string | URL da página inicial ou documentação do plugin |

236| `repository` | string | URL do repositório de código-fonte |

237| `license` | string | Identificador de licença SPDX (por exemplo, MIT, Apache-2.0) |

238| `keywords` | array | Tags para descoberta e categorização de plugins |

239| `metadata` | object | Objeto de forma livre para seus próprios campos, como dados de direito ou catálogo. Claude Code não o lê. Antes da v2.1.222, `claude plugin validate` relatava a chave como um campo não reconhecido. |

240| `category` | string | Categoria do plugin para organização |

241| `tags` | array | Tags para pesquisabilidade |

242| `strict` | boolean | Controla se `plugin.json` é a autoridade para definições de componentes (padrão: true). Veja [Strict mode](#strict-mode) abaixo. |

243| `relevance` | object | Sinais que informam ao Claude Code quando sugerir este plugin aos usuários. Tem efeito apenas para marketplaces que um administrador coloca na lista de permissões em configurações gerenciadas. Veja [Recomendar plugins para sua organização](/docs/pt/plugin-relevance). |

244| `defaultEnabled` | boolean | Se o plugin está habilitado após a instalação (padrão: true). Defina como `false` para instalar o plugin desabilitado até que o usuário opte por ativá-lo. Tem precedência sobre o mesmo campo no `plugin.json` do plugin. Veja [Default enablement](/docs/pt/plugins-reference#default-enablement). |

~~245~~

246Tanto a entrada quanto o próprio `plugin.json` do plugin podem definir os campos de exibição `displayName`, `description`, `author`, `homepage`, `repository`, `license` e `keywords`. Em listagens e detalhes de plugins, antes e depois da instalação:

~~247~~

248* Para um campo que você define na entrada, os usuários veem o valor da entrada, mesmo quando `plugin.json` define um diferente.

249* Para um campo que a entrada deixa indefinido, os usuários veem o valor de `plugin.json`.

~~250~~

251Antes da instalação, Claude Code pode ler `plugin.json` apenas para entradas com uma [fonte de caminho relativo](#relative-paths), cujos arquivos de plugin vivem dentro do próprio marketplace. Para uma entrada com qualquer outro tipo de fonte, os usuários veem apenas os campos da própria entrada até que instalem o plugin.

~~252~~

253**Campos de configuração de componentes:**

~~254~~

255| Campo | Tipo | Descrição |

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

~~263~~

264**Campos de autenticação de arquivo:**

~~265~~

266Defina estes quando a entrada tiver uma [`archive` source](#zip-archives) em um servidor que requer credenciais.

~~267~~

268| Campo | Tipo | Descrição |

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

270| `headers` | object | Cabeçalhos HTTP que Claude Code envia quando baixa o arquivo desta entrada. Substitui os cabeçalhos do marketplace com o mesmo nome. Requer Claude Code v2.1.238 ou posterior. |

271| `headersHelper` | string | Comando que imprime os cabeçalhos HTTP para o download do arquivo desta entrada como um objeto JSON, para uma credencial que expira. Veja [Autenticar downloads de arquivo](#authenticate-archive-downloads). A entrada também deve definir [`"strict": false`](#strict-mode). Requer Claude Code v2.1.238 ou posterior. |

~~272~~

273<h2 id="plugin-sources">

274 Fontes de plugin

275</h2>

~~276~~

277As fontes de plugin informam ao Claude Code onde buscar cada plugin individual listado em seu marketplace. Elas são definidas no campo `source` de cada entrada de plugin em `marketplace.json`.

~~278~~

279Claude Code copia cada plugin instalado para o cache de plugin versionado local em `~/.claude/plugins/cache`, exceto quando o plugin é carregado no lugar. Uma [fonte `command` em modo link](#copy-mode-and-link-mode) é carregada no lugar, assim como uma [fonte de caminho relativo](#relative-paths) em um marketplace adicionado de um diretório local. Claude Code também [instala as dependências de pacote Node.js elegíveis do plugin](/docs/pt/plugins-reference#node-js-package-dependencies) na cópia em cache. Veja [Plugin caching and file resolution](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) para como um plugin carregado no lugar de um marketplace de diretório local capta suas edições.

~~280~~

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

283| Caminho relativo | `string` (por exemplo, `"./my-plugin"`) | nenhum | Diretório local dentro do repositório de marketplace. Deve começar com `./`, a menos que você escreva um [nome simples sob `metadata.pluginRoot`](#relative-paths). Claude Code resolve o caminho relativamente à raiz do marketplace, não ao diretório `.claude-plugin/` |

289| `command` | object | `command`, `timeout?`, `mode?` | Diretório de plugin produzido pela execução de um comando local, re-executado uma vez por sessão para captar mudanças. Requer Claude Code v2.1.229 ou posterior |

~~290~~

291<Note>

292 **Fontes de marketplace vs fontes de plugin**: Estes são conceitos diferentes que controlam coisas diferentes.

~~293~~

294 * **Fonte de marketplace**: onde buscar o próprio catálogo `marketplace.json`. Definido quando os usuários executam `/plugin marketplace add` ou em configurações `extraKnownMarketplaces`. Fontes de marketplace baseadas em Git suportam `ref` (branch/tag) mas não `sha`.

295 * **Fonte de plugin**: onde buscar um plugin individual listado no marketplace. Definido no campo `source` de cada entrada de plugin dentro de `marketplace.json`. Fontes de plugin baseadas em Git suportam tanto `ref` (branch/tag) quanto `sha` (commit exato).

~~296~~

297 Por exemplo, um marketplace hospedado em `acme-corp/plugin-catalog` (fonte de marketplace) pode listar um plugin buscado de `acme-corp/code-formatter` (fonte de plugin). A fonte de marketplace e a fonte de plugin apontam para repositórios diferentes e são fixadas independentemente.

298</Note>

~~299~~

300Os tipos de fonte baseados em git abaixo são `github`, `url` e `git-subdir`. Quando tanto `ref` quanto `sha` são definidos em qualquer um deles, o `sha` é o pino efetivo. Claude Code busca e faz checkout do commit fixado diretamente.

~~301~~

302Na maioria dos hosts git, incluindo GitHub, GitLab e Bitbucket, isso significa que a instalação é bem-sucedida mesmo se o branch ou tag nomeado por `ref` tenha sido deletado upstream, desde que o commit ainda seja alcançável a partir do repositório. Alguns servidores, como AWS CodeCommit, não suportam busca de commits por SHA. Nesses servidores, o `ref` ainda deve existir e o commit fixado deve ser alcançável a partir dele.

~~303~~

304Se você distribuir plugins através de **Configurações da Organização > Plugins**, apenas alguns tipos de fonte são permitidos. Veja [Distribuir através de configurações da organização](#distribute-through-organization-settings).

~~305~~

306<h3 id="relative-paths">

307 Caminhos relativos

308</h3>

~~309~~

310Para plugins no mesmo repositório, use um caminho começando com `./`:

~~311~~

312```json theme={null}

313{

314 "name": "my-plugin",

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

316}

317```

~~318~~

319Os caminhos são resolvidos relativamente à raiz do marketplace, que é o diretório contendo `.claude-plugin/`. A fonte `./plugins/my-plugin` portanto aponta para `<repo>/plugins/my-plugin`, mesmo que `marketplace.json` viva em `<repo>/.claude-plugin/marketplace.json`. Não use `../` para referenciar caminhos fora da raiz do marketplace. Em macOS e Linux, Claude Code recusa uma entrada de caminho com uma barra invertida em qualquer lugar após o `./` inicial, então escreva os separadores como `/` em todas as plataformas.

~~320~~

321Um nome simples é um único nome de diretório sem `/`, como `"formatter"`. Para escrever nomes simples em vez de caminhos `./`, defina [`metadata.pluginRoot`](#optional-fields) para o diretório sob o qual eles se resolvem. Com `"pluginRoot": "./plugins"`, Claude Code resolve `"source": "formatter"` para `./plugins/formatter`. Requer Claude Code v2.1.239 ou posterior.

~~322~~

323`metadata.pluginRoot` deve ser um caminho relativo dentro do marketplace. Claude Code o ignora para uma fonte que já começa com `./`. Uma fonte que contém um `/`, como `team-a/formatter`, não é um nome simples e ainda precisa do prefixo `./`, mesmo quando `metadata.pluginRoot` está definido.

~~324~~

325<Note>

326 Claude Code resolve caminhos relativos contra uma cópia local do marketplace, então funcionam quando os usuários adicionam seu marketplace de uma fonte git ou um diretório local. Se os usuários adicionarem seu marketplace via URL direta para o arquivo `marketplace.json`, caminhos relativos não serão resolvidos, porque Claude Code baixa apenas esse arquivo. Para distribuição baseada em URL, use qualquer outra [fonte de plugin](#plugin-sources) em vez disso. Veja [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) para detalhes.

327</Note>

~~328~~

329<h3 id="github-repositories">

330 Repositórios 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~~

343Você pode fixar a um branch, tag ou commit específico:

~~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 | Descrição |

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

359| `repo` | string | Obrigatório. Repositório GitHub no formato `owner/repo` |

360| `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) |

361| `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

~~362~~

363<h3 id="git-repositories">

364 Repositórios 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~~

377Você pode fixar a um branch, tag ou commit específico:

~~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 | Descrição |

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

393| `url` | string | Obrigatório. URL completa do repositório git (`https://` ou `git@`). O sufixo `.git` é opcional, então URLs do Azure DevOps e AWS CodeCommit sem o sufixo funcionam |

394| `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) |

395| `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

~~396~~

397<h3 id="git-subdirectories">

398 Subdiretórios Git

399</h3>

~~400~~

401Use `git-subdir` para apontar para um plugin que vive dentro de um subdiretório de um repositório git. Claude Code usa um clone parcial e esparso para buscar apenas o subdiretório, minimizando largura de banda para grandes monorepos.

~~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~~

414Você pode fixar a um branch, tag ou commit específico:

~~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~~

429O campo `url` também aceita atalho GitHub (`owner/repo`) ou URLs SSH (`git@github.com:owner/repo.git`).

~~430~~

431| Campo | Tipo | Descrição |

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

433| `url` | string | Obrigatório. URL do repositório Git, atalho GitHub `owner/repo` ou URL SSH |

434| `path` | string | Obrigatório. Caminho do subdiretório dentro do repositório contendo o plugin (por exemplo, `"tools/claude-plugin"`) |

435| `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) |

436| `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

~~437~~

438<h3 id="npm-packages">

439 Pacotes npm

440</h3>

~~441~~

442Uma fonte npm pode nomear qualquer pacote no registro npm público ou em um registro privado que sua equipe hospeda. Claude Code resolve o pacote com seu cliente npm, baixa o tarball e o desempacota no cache de plugin.

~~443~~

444Os scripts de instalação do pacote, como `preinstall` ou `postinstall`, nunca são executados, e suas dependências não são instaladas durante a busca.

~~445~~

446Se o pacote enviar um lockfile suportado ao lado de seu `package.json`, Claude Code instala essas [dependências de pacote Node.js](/docs/pt/plugins-reference#node-js-package-dependencies) em uma etapa separada, também com scripts desabilitados. Caso contrário, publique o plugin com tudo que ele precisa já construído. Um servidor MCP que precisa de outros pacotes pode ser iniciado através de `npx`, que os instala na primeira execução.

~~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~~

458Para fixar a uma versão específica, adicione o 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~~

471Para instalar de um registro privado ou interno, adicione o 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 | Descrição |

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

487| `package` | string | Obrigatório. Nome do pacote ou pacote com escopo (por exemplo, `@org/plugin`) |

488| `version` | string | Opcional. Versão ou intervalo de versão (por exemplo, `2.1.0`, `^2.0.0`, `~1.5.0`) |

489| `registry` | string | Opcional. URL de registro npm personalizado. Padrão é o registro npm do sistema (tipicamente npmjs.org) |

~~490~~

491<h3 id="zip-archives">

492 Arquivos zip

493</h3>

~~494~~

495Use `archive` para distribuir um plugin como um arquivo zip que Claude Code baixa via HTTPS, para que as instalações funcionem sem git ou npm na máquina do usuário. Hospede o arquivo em qualquer servidor de arquivo estático ou repositório de artefatos, como um bucket S3, um repositório genérico do Artifactory ou nginx. Requer Claude Code v2.1.224 ou posterior. Nas versões v2.1.120 até v2.1.223, a instalação do plugin falha com `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`; em versões mais antigas, um marketplace contendo uma entrada `archive` falha ao carregar completamente.

~~496~~

497Esta entrada instala o plugin de um arquivo zip em um servidor de artefatos:

~~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 você constrói o zip, você pode fazer zip do conteúdo do plugin diretamente ou fazer zip da pasta do plugin em si. Claude Code procura por `.claude-plugin/` no topo do arquivo, depois dentro de uma única pasta de nível superior, então ambos os layouts instalam:

~~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 não procura mais profundamente do que uma pasta, então um plugin aninhado mais abaixo falha ao instalar. Claude Code recusa arquivos maiores que 256 MiB.

~~520~~

521Para fixar o arquivo exato, adicione um campo `sha256` com o resumo do arquivo:

~~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 o arquivo baixado não corresponder ao pino, Claude Code recusa a instalação e relata [`Plugin archive integrity check failed`](/docs/pt/errors#plugin-archive-integrity-check-failed).

~~535~~

536As fontes de arquivo aceitam estes campos:

~~537~~

538| Campo | Tipo | Descrição |

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

540| `url` | string | Obrigatório. URL HTTPS do arquivo zip. Claude Code rejeita URLs `http://`, junto com hosts de loopback, link-local e cloud-metadata. Cada salto de redirecionamento deve satisfazer as mesmas regras, ou Claude Code recusa o download |

541| `sha256` | string | Opcional. Resumo SHA-256 do arquivo como 64 caracteres hexadecimais, maiúsculos ou minúsculos. Claude Code verifica cada download contra ele e recusa a instalação em caso de incompatibilidade |

~~542~~

543O resumo `sha256` também serve como a versão do plugin quando nem `plugin.json` nem a entrada de marketplace declara uma. Veja [Gerenciamento de versão](/docs/pt/plugins-reference#version-management). Se você declarar uma `version`, essa string de versão é o sinal de atualização, então após alterar o zip e seu resumo, aumente a versão também, ou os usuários mantêm a cópia em cache.

~~544~~

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

546 Autenticar downloads de arquivo

547</h4>

~~548~~

549Para autenticar um download de arquivo, como um download de um registro privado, defina os cabeçalhos HTTP que Claude Code envia com ele. Defina `headers` na fonte `url` de onde você registrou o marketplace, como uma entrada [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces). No Claude Code v2.1.238 ou posterior, você pode defini-lo na entrada do plugin em vez disso, ao lado de `source`.

~~550~~

551Se o valor que você colocaria em `headers` for de curta duração, como um token que seu registro cria sob demanda, defina um comando `headersHelper` no mesmo lugar em vez disso. Claude Code executa o comando e envia o objeto JSON que ele imprime como os cabeçalhos desse lugar. Requer Claude Code v2.1.238 ou posterior.

~~552~~

553O lugar que você escolhe decide quais downloads recebem os cabeçalhos e quando Claude Code executa o comando:

~~554~~

555| Lugar | Downloads que recebem os cabeçalhos | Quando Claude Code executa um `headersHelper` definido lá |

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

557| Fonte `url` do marketplace | Downloads de arquivo na origem da URL do marketplace, significando o mesmo esquema, host e porta | Antes de cada busca do `marketplace.json` do marketplace e antes de cada download de arquivo nessa origem. Claude Code reutiliza a saída de uma execução por até 60 segundos |

558| Entrada de plugin | Apenas o download dessa entrada | Apenas quando um usuário instala ou atualiza esse plugin sozinho e [aceita o comando](#how-users-accept-a-headershelper-command) |

~~559~~

560Onde ambos os lugares definem um cabeçalho do mesmo nome, Claude Code envia o valor da entrada. Dentro de um lugar, um cabeçalho que o comando imprime substitui um cabeçalho do mesmo nome listado em `headers`.

~~561~~

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

563 Adicionar um headersHelper a uma entrada de plugin

564</h5>

~~565~~

566Esta entrada define `headersHelper` ao lado de `source`. Ela também define `"strict": false`, que Claude Code requer de uma entrada `marketplace.json` que define `headersHelper`. Com [`"strict": false`](#strict-mode), a entrada de marketplace é a definição completa do plugin, então um usuário pode revisar o que o plugin contém antes de aceitar o 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~~

582Para verificar a entrada, execute `claude plugin install my-plugin@your-marketplace`. Claude Code mostra o comando e a URL do arquivo, e baixa o zip após você aceitar.

~~583~~

584Antes de v2.1.238, Claude Code baixava um arquivo de entrada sem seus `headers` ou `headersHelper`, então uma instalação que dependia deles falhava com `HTTP 401 while downloading plugin archive from`, seguido pela URL, com o código de status do registro no lugar de 401.

~~585~~

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

587 Escrever o comando headersHelper

588</h4>

~~589~~

590Se você definir `headersHelper` em uma fonte `url` de um marketplace ou em uma entrada de plugin, escreva o comando para atender a estes requisitos:

~~591~~

592* **Texto do comando**: no máximo 500 caracteres de ASCII imprimível, sem execução de quatro ou mais espaços.

593* **Saída**: imprima um objeto JSON de nomes de cabeçalho e valores de string em stdout, depois saia com 0 dentro de 10 segundos.

594* **Shell e diretório de trabalho**: Claude Code executa o comando através de `sh`, ou `cmd.exe` no Windows, a partir do diretório de configuração, `~/.claude` ou [`CLAUDE_CONFIG_DIR`](/docs/pt/env-vars#variables). Dê um caminho absoluto ou um comando em `PATH`, porque um caminho relativo se resolve contra esse diretório, não o projeto do usuário.

595* **Variáveis que Claude Code remove**: do ambiente de um comando definido em uma entrada `marketplace.json` ou em um `.claude/settings.json` ou `.claude/settings.local.json` de um projeto, Claude Code remove cada variável cujo nome contém uma palavra como `TOKEN`, `SECRET`, `KEY` ou `AUTH`, incluindo `ANTHROPIC_API_KEY`. Claude Code não aplica essa remoção a um comando definido em configurações de usuário, um arquivo `--settings` ou configurações gerenciadas.

596* **Variáveis que Claude Code define**: `CLAUDE_CODE_MARKETPLACE_URL` e `CLAUDE_CODE_MARKETPLACE_NAME` para um comando de fonte `url`, e `CLAUDE_CODE_PLUGIN_NAME` e `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` para um comando de entrada. `CLAUDE_CODE_MARKETPLACE_NAME` não está definido na primeira busca após um usuário adicionar um marketplace por URL, porque essa busca é o que fornece o nome.

~~597~~

598Um comando que cria um token bearer imprime um objeto como este:

~~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 pula um comando headersHelper ou descarta sua saída

606</h4>

~~607~~

608Claude Code não executa um comando `headersHelper`, ou descarta cabeçalhos que vieram de `headers` ou da saída do comando, nestas situações:

~~609~~

610* **Comando falha**: se o comando sair com código não-zero, executar por mais de 10 segundos ou imprimir qualquer coisa que não seja um objeto JSON de valores de string, Claude Code não faz a busca ou download para o qual executou o comando.

611* **URL do marketplace não começa com `https://`**: Claude Code não executa o comando da fonte `url` desse e envia apenas os cabeçalhos listados em seu campo `headers`.

612* **Redirecionamento sai da origem**: quando um download é redirecionado para fora da origem da URL do arquivo, Claude Code descarta os valores de `headers` e saída de comando tanto da fonte `url` do marketplace quanto da entrada de plugin.

613* **Entrada define um cabeçalho de roteamento ou identidade**: Claude Code descarta nomes de roteamento de requisição e identidade de cliente como `Host`, `Cookie` e `X-Forwarded-*` de um `headers` de entrada e saída de comando, e mantém nomes de autenticação como `Authorization`. Claude Code filtra cada entrada `marketplace.json` dessa forma, e uma [entrada de configurações inline](/docs/pt/settings-reference#extraknownmarketplaces) dependendo de qual arquivo a declara.

614* **Comando definido em configurações de um diretório `--add-dir`**: Claude Code o ignora, em uma fonte `url` e em uma [entrada de plugin inline](/docs/pt/settings-reference#extraknownmarketplaces) igualmente, e envia apenas os `headers` desse arquivo.

615* **Configurações gerenciadas bloqueiam o comando**: definir [`disableCommandPluginSources`](/docs/pt/settings-reference#disablecommandpluginsources) como `true` bloqueia comandos `headersHelper`, e [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) também os bloqueia a menos que `disableCommandPluginSources` seja explicitamente `false`. Sob qualquer bloqueio, Claude Code ainda executa o comando para um marketplace que as próprias configurações gerenciadas declaram.

~~616~~

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

618 Como usuários aceitam um comando headersHelper

619</h4>

~~620~~

621Um usuário aceita o comando de uma entrada de plugin cada vez que instala ou atualiza esse plugin sozinho, a partir da própria visualização do plugin em `/plugin` ou com `claude plugin install` ou `claude plugin update`. Claude Code mostra o comando e a URL do arquivo, e executa o comando apenas após o usuário aceitar.

~~622~~

623Em um shell não-interativo, passe [`--yes`](/docs/pt/plugins-reference#plugin-install) para aceitar o comando. Para aceitar apenas o comando que uma execução anterior com `--json` exibiu, passe [`--accept-command`](/docs/pt/plugins-reference#plugin-install) com o `sha256` que a execução relatou.

~~624~~

625Claude Code executa apenas o comando que mostrou, para a URL do arquivo que mostrou. Se o comando ou URL do arquivo da entrada mudou entre, Claude Code recusa a instalação ou atualização. Uma mudança apenas na string de consulta não conta.

~~626~~

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

628 Instalações e atualizações que recusam o comando em vez de perguntar

629</h5>

~~630~~

631Em qualquer operação que não seja uma instalação ou atualização de um único plugin, Claude Code não executa o comando de uma entrada nem baixa seu arquivo, então o plugin permanece em sua versão instalada ou permanece desinstalado. O que o usuário vê depende da operação:

~~632~~

633* **Instalando vários plugins de uma vez, de uma sugestão de plugin ou como dependência de outro plugin**: Claude Code recusa o plugin que tem o comando e aponta o usuário para a própria visualização desse plugin em `/plugin`. Os outros plugins em uma instalação em massa ainda instalam. Um plugin que depende do plugin recusado falha ao instalar até o usuário instalar o plugin recusado sozinho.

634* **Atualização automática em segundo plano, ou início de sessão para um plugin cujo arquivo nunca foi baixado**: Claude Code lista o plugin na aba Erros de `/plugin` para que o usuário saiba instalá-lo ou atualizá-lo manualmente. Uma atualização automática que encontra a entrada ainda anuncia a versão instalada lista nada.

~~635~~

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

637 Quando o comando de uma fonte `url` de marketplace é executado

638</h5>

~~639~~

640Um `headersHelper` de fonte `url` de marketplace é declarado em um arquivo de configurações, como uma entrada [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces), em vez de no catálogo que o marketplace publica, então Claude Code não pede ao usuário para aceitá-lo em cada instalação ou atualização. O arquivo de configurações que o declara decide quando Claude Code o executa:

~~641~~

642| Arquivo de configurações | Quando Claude Code executa o comando |

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

644| Configurações de usuário, um arquivo `--settings` ou um arquivo de configurações gerenciadas na máquina | Sem perguntar, incluindo durante uma atualização de marketplace em segundo plano |

645| Um `.claude/settings.json` ou `.claude/settings.local.json` de um projeto | Apenas após o usuário aceitar o [diálogo de confiança de workspace](/docs/pt/permissions#what-runs-before-you-trust-a-folder) para essa pasta em si. Uma sessão `-p` ou SDK não conta como aceitá-lo, e nem a confiança concedida a uma pasta pai |

646| Configurações gerenciadas pelo servidor | Apenas após o usuário aprovar as configurações entregues no [diálogo de aprovação de segurança](/docs/pt/server-managed-settings#security-approval-dialogs) |

~~647~~

648Em uma sessão `-p` ou SDK, Claude Code não pode mostrar o diálogo de aprovação de segurança. Ele aplica as outras configurações entregues, mas a busca de marketplace e qualquer download de arquivo que precise do comando falha até um usuário ter aprovado em uma sessão interativa.

~~649~~

650Para uma [entrada de plugin inline](/docs/pt/settings-reference#extraknownmarketplaces) em um desses arquivos, Claude Code requer a mesma confiança de pasta ou aprovação de configurações que para um comando de nível de marketplace nesse arquivo, e o usuário também aceita o comando da entrada em cada instalação ou atualização.

~~651~~

652<h3 id="command-sources">

653 Fontes de comando

654</h3>

~~655~~

656Use `command` quando uma ferramenta instalada localmente produz o diretório de plugin, como um IDE que renderiza seu plugin para a cadeia de ferramentas atualmente selecionada. Claude Code executa o comando quando o usuário instala o plugin e o re-executa em segundo plano uma vez por sessão, então seus usuários captam a saída alterada da ferramenta sem reinstalar. Requer Claude Code v2.1.229 ou posterior. Na v2.1.120 até v2.1.228, a instalação do plugin falha com `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`, e em versões mais antigas o marketplace inteiro falha ao carregar.

~~657~~

658Esta entrada instala o plugin de qualquer diretório que a ferramenta imprime:

~~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 executa o comando através do shell da plataforma, `sh` em macOS e Linux ou `cmd.exe` no Windows, a partir do diretório inicial do usuário. O comando deve imprimir exatamente uma linha em stdout e sair com código 0. Essa linha é o caminho absoluto de um diretório que contém o plugin completo no momento em que o comando sai, e o caminho pode mudar entre execuções.

~~671~~

672Claude Code para um comando que executa mais tempo que `timeout` segundos, e a instalação ou atualização falha. Claude Code também recusa o caminho impresso nestas situações, e a instalação ou atualização falha da mesma forma:

~~673~~

674* O diretório não tem conteúdo de plugin em seu nível superior, como um diretório `.claude-plugin/` ou um diretório `skills/`, `commands/`, `agents/` ou `hooks/`

675* O diretório é aquele em que Claude Code foi iniciado, ou um de seus pais

676* No Windows, o caminho é um caminho UNC

~~677~~

678As fontes de comando aceitam estes campos:

~~679~~

680| Campo | Tipo | Descrição |

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

682| `command` | string | Obrigatório. Comando shell que imprime o caminho absoluto do diretório de plugin como uma única linha em stdout e sai com 0. Deve ser ASCII imprimível, no máximo 500 caracteres, sem execuções de quatro ou mais espaços, para que os usuários possam revisar o comando inteiro que são solicitados a aceitar |

683| `timeout` | number | Opcional. Número inteiro de segundos para esperar pelo comando antes de desistir (padrão: 60, máximo: 600) |

684| `mode` | string | Opcional. `"copy"` (padrão) copia o diretório impresso para o cache de plugin. `"link"` usa o diretório impresso no lugar. Veja [Modo de cópia e modo de link](#copy-mode-and-link-mode) |

~~685~~

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

687 Modo de cópia e modo de link

688</h4>

~~689~~

690Com o padrão `"mode": "copy"`, Claude Code copia o diretório impresso para o cache de plugin versionado e deriva a [versão do plugin](/docs/pt/plugins-reference#version-management) de um hash do conteúdo do diretório. Sua ferramenta pode deletar ou reescrever o diretório após o comando sair, e uma re-execução que produz conteúdo idêntico conta como atualizado. Claude Code recusa instalar um diretório maior que 256 MiB ou contendo mais de 20.000 entradas.

~~691~~

692Defina `"mode": "link"` para diretórios de plugin grandes que não devem ser copiados, como uma exportação de SDK renderizada. Claude Code preenche a entrada de cache do plugin com um link para cada entrada de nível superior do diretório impresso e usa os arquivos no lugar, então nada é copiado, conteúdos de arquivo não são hash, e os limites de tamanho não se aplicam. A instalação falha se uma entrada de nível superior é um symlink que aponta para fora do diretório impresso. Claude Code também pula a [instalação de dependência de pacote Node.js](/docs/pt/plugins-reference#node-js-package-dependencies) para um plugin em modo link, então imprima um diretório que já contém qualquer `node_modules` que o plugin precisa.

~~693~~

694Mantenha o diretório impresso no lugar enquanto o plugin permanecer instalado, porque Claude Code carrega o plugin através desses links em cada inicialização. Claude Code deriva a [versão do plugin](/docs/pt/plugins-reference#version-management) do caminho real do diretório impresso e suas entradas de nível superior, não dos arquivos dentro, então imprima um caminho diferente para sinalizar novo conteúdo. Em uma sessão iniciada no diretório impresso ou em qualquer lugar abaixo dele, Claude Code não carrega o plugin.

~~695~~

696Claude Code não suporta modo link no Windows e recusa instalar um plugin em modo link lá. Declare `"mode": "copy"` em vez disso.

~~697~~

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

699 Como usuários aceitam o comando

700</h4>

~~701~~

702Claude Code executa seu comando na máquina do usuário, então vincula cada execução à aceitação explícita do usuário:

~~703~~

704* Quando os usuários instalam o plugin a partir de sua tela de detalhes em `/plugin`, ou instalam ou atualizam com `claude plugin install` ou `claude plugin update` em um terminal interativo, Claude Code mostra a eles a string de comando exato primeiro e registra o comando aceito para essa instalação. Um `claude plugin update` que pode prosseguir na aceitação registrada do mesmo comando mostra nada.

705* Em um shell não-interativo, como um script de provisionamento, passe `--yes` para `claude plugin install` ou `claude plugin update` para aceitar o comando que imprime. Para aceitar apenas o comando que uma execução anterior com `--json` exibiu, passe [`--accept-command`](/docs/pt/plugins-reference#plugin-install) com o `sha256` que a execução relatou.

706* Cada outro caminho executa apenas o comando que o usuário já aceitou. Isso inclui atualizações iniciadas de `/plugin` e as execuções em segundo plano descritas em [Quando Claude Code re-executa o comando](#when-claude-code-re-runs-the-command). Quando nenhum foi aceito, Claude Code recusa executar o comando e diz ao usuário como revisar. Claude Code nunca instala um plugin com fonte de comando como dependência de outro plugin, então os usuários o instalam sozinhos primeiro.

707* Se você alterar o `command` da entrada, ou alternar seu `mode`, os usuários mantêm a versão que já têm e Claude Code para de re-executar o comando. Em sessões interativas, a aba Erros de `/plugin` mostra o novo comando até o usuário revisar e aceitar executando `claude plugin update <plugin>@<marketplace>`.

~~708~~

709Administradores podem bloquear fontes de comando em toda uma organização com a configuração gerenciada [`disableCommandPluginSources`](/docs/pt/settings-reference#disablecommandpluginsources). Se uma organização definir [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly), Claude Code bloqueia fontes de comando por padrão.

~~710~~

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

712 Quando Claude Code re-executa o comando

713</h4>

~~714~~

715O diretório impresso reflete o estado da ferramenta no momento em que o comando foi executado, então Claude Code executa o comando novamente nestes momentos:

~~716~~

717* Cada vez que o usuário instala ou atualiza o plugin

718* Uma vez por sessão para cada plugin com fonte de comando habilitado, em segundo plano, pouco após a sessão iniciar. Esta execução não passa pela atualização automática de marketplace, então não depende da [configuração de atualização automática](/docs/pt/discover-plugins#configure-auto-updates) do marketplace

719* Na inicialização ou em `/reload-plugins`, quando a versão instalada de um plugin habilitado está faltando do cache de plugin

~~720~~

721Claude Code pula as duas execuções em segundo plano quando o usuário define [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/pt/env-vars). Instalações e atualizações explícitas ainda executam o comando com essa variável definida.

~~722~~

723Quando a saída hash do comando mudou, Claude Code instala o resultado como uma nova versão e o recarrega na sessão interativa em execução, alternando [os mesmos componentes que `/reload-plugins` alterna](/docs/pt/plugins-reference#environment-variables). O usuário vê uma notificação de que o plugin foi recarregado. Se recarregar no lugar invalidaria o cache de prompt da sessão, Claude Code em vez disso solicita ao usuário executar `/reload-plugins`, que [avisa sobre o custo do cache e se aplica quando re-executado com `--force`](/docs/pt/prompt-caching#enabling-or-disabling-a-plugin).

~~724~~

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

726 Entradas de plugin avançadas

727</h3>

~~728~~

729Este exemplo mostra uma entrada de plugin usando muitos dos campos opcionais, incluindo caminhos personalizados para commands, agents, hooks e MCP servers:

~~730~~

731```json theme={null}

732{

733 "name": "enterprise-tools",

734 "source": {

735 "source": "github",

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

737 },

738 "description": "Ferramentas de automação de fluxo de trabalho empresarial",

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~~

778Coisas importantes a notar:

~~779~~

780* **`commands` e `agents`**: você pode especificar múltiplos diretórios ou arquivos individuais. Os caminhos são relativos à raiz do plugin e devem permanecer dentro dela.

781 * Claude Code rejeita um caminho que se resolve fora do diretório de plugin, como `./../shared.md`, com um erro [`path escapes plugin directory`](/docs/pt/errors#path-escapes-plugin-directory), e ainda carrega o plugin sem esse componente

782* **`${CLAUDE_PLUGIN_ROOT}`**: use esta variável em comandos de hook e configurações de MCP server para referenciar arquivos dentro do diretório de instalação do plugin.

783 * Veja a [tabela de substituição](/docs/pt/plugins-reference#environment-variables) para quais campos de configuração a substituem por tipo de servidor

784 * Para dependências ou estado que devem sobreviver a atualizações de plugin, use [`${CLAUDE_PLUGIN_DATA}`](/docs/pt/plugins-reference#persistent-data-directory) em vez disso

785* **`strict: false`**: como isso está definido como false, o plugin não precisa de seu próprio `plugin.json`. A entrada de marketplace define tudo. Veja [Strict mode](#strict-mode) abaixo.

~~786~~

787Por padrão, as skills de um plugin são carregadas do diretório `skills/` sob sua `source`. Os caminhos listados no campo `skills` adicionam a essa varredura:

~~788~~

789```json theme={null}

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

791```

~~792~~

793Quando várias entradas de plugin compartilham uma pasta `skills/` na raiz do marketplace (`source: "./"`), liste subdiretórios específicos em vez disso para que cada entrada carregue apenas suas próprias skills:

~~794~~

795```json theme={null}

796"source": "./",

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

798```

~~799~~

800Com uma `source` de raiz de marketplace, os caminhos listados são o conjunto completo para essa entrada, e outros diretórios na pasta `skills/` compartilhada não são carregados. Listar `./skills/` em si, ou a raiz do plugin, mantém a varredura completa. Se nenhum dos caminhos listados existir, a varredura padrão é executada em vez disso.

~~801~~

802<h3 id="strict-mode">

803 Strict mode

804</h3>

~~805~~

806O campo `strict` controla se `plugin.json` é a autoridade para definições de componentes (skills, agents, hooks, MCP servers, output styles).

~~807~~

808| Valor | Comportamento |

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

810| `true` (padrão) | `plugin.json` é a autoridade. A entrada de marketplace pode complementá-lo com componentes adicionais, e ambas as fontes são mescladas. |

811| `false` | A entrada de marketplace é a definição completa. Se o plugin também tem um `plugin.json` que declara componentes, isso é um conflito e o plugin falha ao carregar. |

~~812~~

813**Quando usar cada modo:**

~~814~~

815* **`strict: true`**: o plugin tem seu próprio `plugin.json` e gerencia seus próprios componentes. A entrada de marketplace pode adicionar skills ou hooks extras no topo. Este é o padrão e funciona para a maioria dos plugins.

816* **`strict: false`**: o operador do marketplace quer controle total. O repositório do plugin fornece arquivos brutos, e a entrada de marketplace define quais desses arquivos são expostos como skills, agents, hooks, etc. Útil quando o marketplace reestrutura ou curada os componentes de um plugin de forma diferente do que o autor do plugin pretendia.

~~817~~

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

819 Hospedar e distribuir marketplaces

820</h2>

~~821~~

822Quando os usuários adicionam um marketplace hospedado em um repositório git, ou instalam um plugin baseado em git que ele lista, Claude Code clona esse repositório de marketplace ou plugin na máquina deles. O clone nunca baixa conteúdo de [Git LFS](https://git-lfs.com), então arquivos rastreados por LFS chegam como arquivos de ponteiro. Mantenha os arquivos que seus plugins precisam fora do LFS.

~~823~~

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

825 Hospedar no GitHub (recomendado)

826</h3>

~~827~~

828GitHub é a forma recomendada para hospedar e distribuir um marketplace:

~~829~~

8301. **Criar um repositório**: configure um novo repositório para seu marketplace

8312. **Adicionar arquivo de marketplace**: crie `.claude-plugin/marketplace.json` com suas definições de plugin

8323. **Compartilhar com equipes**: os usuários adicionam seu marketplace com `/plugin marketplace add owner/repo`

~~833~~

834**Benefícios**: controle de versão integrado, rastreamento de problemas e recursos de colaboração em equipe.

~~835~~

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

837 Hospedar em outros serviços git

838</h3>

~~839~~

840Qualquer serviço de hospedagem git funciona, como GitLab, Bitbucket e servidores auto-hospedados. Os usuários adicionam com a URL completa do repositório:

~~841~~

842```shell theme={null}

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

844```

~~845~~

846<h3 id="private-repositories">

847 Repositórios privados

848</h3>

~~849~~

850Claude Code suporta instalar plugins de repositórios privados. Se você distribuir seu marketplace através de [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) em vez disso, suas credenciais git não estão envolvidas: a sincronização da organização lê o repositório de marketplace através da conexão da sua organização no GitHub ou GitLab em claude.ai. Veja [Distribuir através de configurações de organização](#distribute-through-organization-settings) para quais fontes de plugin podem ser privadas.

~~851~~

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

853 Comandos que você executa

854</h4>

~~855~~

856Quando você executa `/plugin marketplace add`, `/plugin install`, `/plugin update` ou `/plugin marketplace update`, Claude Code usa seus ajudantes de credencial git existentes, então acesso HTTPS via `gh auth login`, Keychain do macOS ou `git-credential-store` funciona da mesma forma que em seu terminal. Acesso SSH funciona desde que o host já esteja em seu arquivo `known_hosts` e a chave esteja carregada em `ssh-agent`, já que Claude Code suprime prompts SSH interativos para a impressão digital do host e passphrase da chave. O atalho `owner/repo` do GitHub clona por SSH por padrão; defina [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/pt/env-vars#variables) para cloná-los via HTTPS em vez disso.

~~857~~

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

859 Atualizações automáticas em segundo plano

860</h4>

~~861~~

862A verificação de atualização em segundo plano verifica o remoto do marketplace para novos commits com seus ajudantes de credencial git configurados, da mesma forma que os comandos que você executa. Para remotos SSH, uma chave carregada em `ssh-agent` autentica a verificação. Claude Code executa a verificação de forma não-interativa: desativa prompts de terminal do git e programas askpass, e diz aos ajudantes de credencial para não solicitar. Se a verificação pode autenticar em um repositório privado via HTTPS depende do seu ajudante:

~~863~~

864* Um ajudante que pode fornecer uma credencial armazenada sem solicitar autentica a verificação. Git Credential Manager, o ajudante Keychain do macOS e `git-credential-store` funcionam dessa forma uma vez que mantêm uma credencial para o host.

865* Um ajudante que precisa solicitá-lo não consegue responder em segundo plano. A atualização falha silenciosamente e o checkout existente permanece no lugar, então seus plugins continuam funcionando a partir do último estado sincronizado. Execute `/plugin marketplace update <name>` para atualizar o marketplace com suas credenciais.

~~866~~

867Quando a verificação encontra o checkout atualizado, Claude Code o deixa como está. Quando a verificação encontra novos commits, ou falha porque não consegue alcançar ou autenticar no remoto, Claude Code clona o marketplace novamente e troca o novo clone. Se esse clone falhar, o checkout existente permanece no lugar. O re-clone pode [expirar em repositórios grandes](#git-operations-time-out).

~~868~~

869Duas configurações fazem marketplaces privados se comportarem de forma previsível:

~~870~~

871* Defina `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para manter o checkout existente sem tentar o re-clone quando a verificação em segundo plano não consegue alcançar ou autenticar no remoto. Seus plugins continuam funcionando a partir do último estado sincronizado, e atualizações manuais com `/plugin marketplace update` ainda autenticam com suas credenciais.

872* Configure um ajudante de credencial git, por exemplo com `gh auth setup-git` para GitHub, para que a verificação em segundo plano e o re-clone possam autenticar sem solicitar.

~~873~~

874Definir um token de provedor como `GITHUB_TOKEN` em seu ambiente não habilita autenticação em segundo plano por si só. Tokens têm efeito apenas através de um ajudante de credencial configurado, por exemplo o ajudante CLI `gh`, que lê `GH_TOKEN` e `GITHUB_TOKEN`.

~~875~~

876<Note>

877 Em ambientes CI/CD, configure um ajudante de credencial git antes de instalar plugins de repositórios privados. No GitHub Actions, exporte um token com acesso de leitura ao repositório de marketplace como `GH_TOKEN`, depois execute `gh auth setup-git`. O token de workflow padrão pode apenas acessar o repositório do próprio workflow, então um marketplace privado em outro repositório precisa de um token de acesso pessoal ou token de app.

878</Note>

~~879~~

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

881 Distribuir através de configurações de organização

882</h3>

~~883~~

884Se você distribuir plugins através de [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) em um plano Team ou Enterprise, estas regras de fonte se aplicam:

~~885~~

886* No github.com e gitlab.com, o repositório de marketplace deve ser privado ou interno. A sincronização da organização lê o repositório através da conexão que corresponde ao seu host:

887 * **github.com**: o Claude GitHub App

888 * **Seu host GitHub Enterprise Server**: o [GitHub Enterprise App](/docs/pt/github-enterprise-server#admin-setup) da sua organização

889 * **gitlab.com ou sua instância GitLab auto-gerenciada**: o token de acesso na [configuração GitLab](#sync-a-gitlab-hosted-marketplace) da sua organização para esse host

890* Cada fonte de plugin deve ser do tipo `github`, `url` ou `git-subdir`, ou um [caminho relativo](#relative-paths) que comece com `./`. Se você listar um plugin por nome simples sob `metadata.pluginRoot`, a sincronização da organização o rejeita como uma fonte não suportada, então escreva o caminho, como `./plugins/deploy-tools`.

891* Uma fonte de plugin pode ser privada em três casos:

892 * Uma fonte github.com que compartilha o proprietário do repositório de marketplace

893 * Uma fonte no host GitHub Enterprise da sua organização com o GHE App instalado no repositório

894 * Uma fonte `url` ou `git-subdir` no mesmo host GitLab que o repositório de marketplace. No gitlab.com, a fonte também deve estar sob o mesmo namespace de grupo de nível superior ou usuário que o repositório de marketplace.

895* Qualquer outra fonte de plugin deve ser um repositório público no github.com, gitlab.com ou bitbucket.org, que a sincronização da organização busca sem credenciais. A sincronização da organização rejeita fontes de plugin em hosts que essas regras não cobrem.

~~896~~

897Veja [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) para o fluxo de trabalho do administrador.

~~898~~

899Para incluir plugins privados, coloque as pastas de plugin dentro do repositório de marketplace e as referencie com um [caminho relativo](#relative-paths). A sincronização da organização empacota cada plugin durante a distribuição, então os usuários nunca precisam de acesso a um repositório de fonte separado.

~~900~~

901Por exemplo, esta entrada de plugin `marketplace.json` referencia um plugin que você confirmou em `plugins/deploy-tools` no repositório de 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 Sincronizar um marketplace hospedado no GitLab

912</h4>

~~913~~

914Para sincronizar um marketplace do gitlab.com ou de uma instância GitLab auto-gerenciada, um [Owner](/docs/pt/server-managed-settings#access-control) primeiro adiciona uma configuração GitLab para esse host em [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code). As configurações GitLab estão em beta público e se aplicam apenas à sincronização de marketplace de plugin. Adicionar uma não torna repositórios GitLab disponíveis em [Claude Code na web](/docs/pt/claude-code-on-the-web#limitations). Veja [Manage plugins for your organization](https://support.claude.com/en/articles/13837433) para as etapas de configuração.

~~915~~

916Quando você adiciona o marketplace, insira a URL HTTPS do projeto, como `https://gitlab.example.com/platform/claude-plugins`. Projetos em subgrupos aninhados funcionam. A sincronização da organização lê o branch padrão do projeto. Se você ativar **Sync automatically**, apenas pushes para o branch padrão iniciam uma sincronização.

~~917~~

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

919 Manter executáveis fora do diretório bin de nível superior

920</h4>

~~921~~

922Não inclua um diretório `bin/` de nível superior em nenhum plugin que você distribua através de configurações de organização. claude.ai rejeita um plugin que tenha um, seja o plugin chegue por sincronização de marketplace ou por upload direto:

~~923~~

924* **Sincronização de marketplace**: a sincronização da organização rejeita esse plugin e sincroniza o resto do marketplace. A mensagem de erro começa com `Plugin contains a top-level bin/ directory`.

925* **Upload direto**: se você fizer upload do plugin em [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) em vez disso, claude.ai rejeita o upload com a mesma mensagem.

~~926~~

927Mantenha executáveis em outro diretório, como `scripts/`, e os referencie como `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` a partir de suas [skills, hooks ou configurações de servidor MCP](/docs/pt/plugins-reference#environment-variables).

~~928~~

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

930 Exigir marketplaces para sua equipe

931</h3>

~~932~~

933Você pode configurar seu repositório para que Claude Code adicione seu marketplace para membros da equipe uma vez que eles [confiem na pasta do projeto](/docs/pt/permissions#what-runs-before-you-trust-a-folder), sem nenhum prompt separado. Adicione seu 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~~

948Você também pode especificar quais plugins devem ser habilitados por padrão:

~~949~~

950```json theme={null}

951{

952 "enabledPlugins": {

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

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

955 }

956}

957```

~~958~~

959Para opções de configuração completas, veja [Plugin settings](/docs/pt/settings-reference#plugin-settings).

~~960~~

961<Note>

962 Se você usar uma fonte local `directory` ou `file` com um caminho relativo, o caminho é resolvido contra o checkout principal do seu repositório. Quando você executa Claude Code de um git worktree, o caminho ainda aponta para o checkout principal, então todos os worktrees compartilham o mesmo local de marketplace. O estado do marketplace é armazenado uma vez por usuário em `~/.claude/plugins/known_marketplaces.json`, não por projeto.

963</Note>

~~964~~

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

966 Pré-popular plugins para containers

967</h3>

~~968~~

969Para imagens de container e ambientes CI, você pode pré-popular um diretório de plugins no tempo de construção para que Claude Code inicie com marketplaces e plugins já disponíveis, sem clonar nada em tempo de execução. Defina a variável de ambiente `CLAUDE_CODE_PLUGIN_SEED_DIR` para apontar para este diretório.

~~970~~

971Para colocar em camadas múltiplos diretórios seed, separe caminhos com `:` em Unix ou `;` no Windows. Claude Code procura cada diretório em ordem e usa o primeiro seed que contém um determinado marketplace ou cache de plugin.

~~972~~

973O diretório seed espelha a estrutura de `~/.claude/plugins`:

~~974~~

975```

976$CLAUDE_CODE_PLUGIN_SEED_DIR/

977 known_marketplaces.json

978 marketplaces/<name>/...

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

980```

~~981~~

982Para construir um diretório seed, execute Claude Code uma vez durante a construção da imagem, instale os plugins que você precisa, depois copie o diretório `~/.claude/plugins` resultante em sua imagem e aponte `CLAUDE_CODE_PLUGIN_SEED_DIR` para ele.

~~983~~

984Para pular a etapa de cópia, defina `CLAUDE_CODE_PLUGIN_CACHE_DIR` para seu caminho de seed de destino durante a construção para que os plugins sejam instalados diretamente 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~~

991Então defina `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed` no ambiente de tempo de execução do seu container para que Claude Code leia do seed na inicialização.

~~992~~

993Na inicialização, Claude Code registra marketplaces encontrados no `known_marketplaces.json` do seed na configuração primária, e usa caches de plugin encontrados sob `cache/` no local sem re-clonar. Isso funciona tanto em modo interativo quanto em modo não-interativo com a flag `-p`.

~~994~~

995Detalhes de comportamento:

~~996~~

997* **Somente leitura**: Claude Code nunca escreve no diretório seed.

998* **Auto-updates desabilitadas**: marketplaces seed não auto-atualizam.

999* **Entradas seed têm precedência**: marketplaces declarados no seed sobrescrevem qualquer entrada correspondente na configuração do usuário em cada inicialização. Para optar por não usar um plugin seed, use `/plugin disable` em vez de remover o marketplace.

1000* **Resolução de caminho**: Claude Code localiza conteúdo de marketplace sondando `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` em tempo de execução, não confiando em caminhos armazenados dentro do JSON do seed. Isso significa que o seed funciona corretamente mesmo quando montado em um caminho diferente de onde foi construído.

1001* **Mutação é bloqueada**: executar `/plugin marketplace remove` ou `/plugin marketplace update` contra um marketplace gerenciado por seed falha com orientação para pedir ao seu administrador para atualizar a imagem seed.

1002* **Compõe com configurações**: se `extraKnownMarketplaces` ou `enabledPlugins` declaram um marketplace que já existe no seed, Claude Code usa a cópia do seed em vez de clonar.

~~1003~~

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

1005 Restrições de marketplace gerenciado

1006</h3>

~~1007~~

1008Para organizações que exigem controle rigoroso sobre fontes de plugin, administradores podem restringir quais marketplaces de plugin os usuários podem adicionar usando a configuração [`strictKnownMarketplaces`](/docs/pt/settings-reference#strictknownmarketplaces) em configurações gerenciadas. Para também rejeitar as flags CLI que carregam plugins, agentes e servidores MCP para uma única execução, combine com [`disableSideloadFlags`](/docs/pt/settings-reference#disablesideloadflags). Para criar uma lista de permissões de quais plugins de marketplaces podem aparecer como sugestões de instalação contextual, defina [`pluginSuggestionMarketplaces`](/docs/pt/settings-reference#pluginsuggestionmarketplaces).

~~1009~~

1010`strictKnownMarketplaces` corresponde ao marketplace de onde um plugin vem, não às entradas dentro dele, então os usuários ainda podem instalar um plugin com uma [fonte `command`](#command-sources) de um marketplace permitido. Para bloquear fontes de comando também, defina [`disableCommandPluginSources`](/docs/pt/settings-reference#disablecommandpluginsources).

~~1011~~

1012Quando `strictKnownMarketplaces` é configurado em configurações gerenciadas, o comportamento de restrição depende do valor:

~~1013~~

1014| Valor | Comportamento |

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

1016| Indefinido (padrão) | Sem restrições. Os usuários podem adicionar qualquer marketplace |

1017| Array vazio `[]` | Bloqueio completo. Bloqueia todas as fontes de marketplace, incluindo o marketplace oficial da Anthropic |

1018| Lista de fontes | Lista de permissões aplicada. Os usuários podem adicionar apenas marketplaces que correspondem a uma entrada |

~~1019~~

1020<h4 id="common-configurations">

1021 Configurações comuns

1022</h4>

~~1023~~

1024Desabilitar todas as adições de marketplace, incluindo o marketplace oficial da Anthropic:

~~1025~~

1026```json theme={null}

1027{

1028 "strictKnownMarketplaces": []

1029}

1030```

~~1031~~

1032Claude Code baixa os plugins [sincronizados do claude.ai](/docs/pt/plugins-reference#synced-plugins) da sua conta em vez de um marketplace, então esse bloqueio não os cobre. Para parar também, defina [`syncClaudeAiPlugins`](/docs/pt/settings-reference#syncclaudeaiplugins) como `false` em configurações gerenciadas, ou desative Skills para sua organização em claude.ai.

~~1033~~

1034Permitir apenas o marketplace oficial da Anthropic. A correspondência para uma entrada de repositório único é exata, então esta entrada não cobre variantes `ref` ou `path` do mesmo repositório:

~~1035~~

1036```json theme={null}

1037{

1038 "strictKnownMarketplaces": [

1039 {

1040 "source": "github",

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

1042 }

1043 ]

1044}

1045```

~~1046~~

1047Com esta entrada, Claude Code mantém um marketplace oficial já registrado disponível e, em uma máquina nova, registra o marketplace automaticamente na primeira vez que você inicia Claude Code interativamente.

~~1048~~

1049O registro automático não cobre todas as máquinas. Ele mais comumente perde:

~~1050~~

1051* Ambientes não-interativos que executam antes do primeiro lançamento interativo da máquina.

1052* Máquinas onde Claude Code já foi executado interativamente sob uma política que bloqueou o marketplace, como o bloqueio de array vazio. Claude Code registra a tentativa bloqueada e não tenta novamente após a política mudar.

~~1053~~

1054Nessas máquinas, adicione o marketplace a [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) no mesmo `managed-settings.json` para que Claude Code o registre automaticamente, ou execute `claude plugin marketplace add anthropics/claude-plugins-official`.

~~1055~~

1056Permitir apenas marketplaces específicos:

~~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~~

1078Permitir todos os repositórios de marketplace sob uma organização GitHub com uma entrada [owner-wildcard](/docs/pt/settings-reference#owner-wildcards). Owner wildcards requerem Claude Code v2.1.223 ou posterior.

~~1079~~

1080```json theme={null}

1081{

1082 "strictKnownMarketplaces": [

1083 {

1084 "source": "github",

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

1086 }

1087 ]

1088}

1089```

~~1090~~

1091Permitir todos os marketplaces de um servidor git interno usando correspondência de padrão regex no host. Esta é a abordagem recomendada para [GitHub Enterprise Server](/docs/pt/github-enterprise-server#plugin-marketplaces-on-ghes) ou instâncias GitLab auto-hospedadas:

~~1092~~

1093```json theme={null}

1094{

1095 "strictKnownMarketplaces": [

1096 {

1097 "source": "hostPattern",

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

1099 }

1100 ]

1101}

1102```

~~1103~~

1104Permitir marketplaces baseados em sistema de arquivos de um diretório específico usando correspondência de padrão regex no caminho:

~~1105~~

1106```json theme={null}

1107{

1108 "strictKnownMarketplaces": [

1109 {

1110 "source": "pathPattern",

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

1112 }

1113 ]

1114}

1115```

~~1116~~

1117Use `".*"` como `pathPattern` para permitir qualquer caminho de sistema de arquivos enquanto ainda controla fontes de rede com `hostPattern`.

~~1118~~

1119<Note>

1120 `strictKnownMarketplaces` restringe o que os usuários podem adicionar, mas não registra marketplaces por conta própria. Para registrar um marketplace permitido para usuários automaticamente, adicione-o a [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) no mesmo `managed-settings.json`.

~~1121~~

1122 O marketplace oficial da Anthropic é o único que Claude Code registra por conta própria, e apenas quando a lista de permissões o permite. O registro automático também perde algumas máquinas, como ambientes não-interativos e máquinas onde uma política anterior o bloqueou. Para cobrir essas máquinas, adicione o marketplace oficial a `extraKnownMarketplaces` também. Para os dois ajustes lado a lado, veja a [referência `strictKnownMarketplaces`](/docs/pt/settings-reference#strictknownmarketplaces).

1123</Note>

~~1124~~

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

1126 Como as restrições funcionam

1127</h4>

~~1128~~

1129As restrições são verificadas antes de qualquer operação de rede ou sistema de arquivos. A verificação é executada na adição de marketplace e na instalação, atualização, atualização e auto-atualização de plugin. Se um marketplace foi adicionado antes da política ser configurada e sua fonte não corresponder mais à lista de permissões, Claude Code recusa instalar ou atualizar plugins a partir dele. A mesma aplicação se aplica a `blockedMarketplaces`.

~~1130~~

1131Onde as duas listas são aplicadas depende de onde você as define:

~~1132~~

1133* **O console de administração claude.ai**: Claude Code aplica ambas as listas nas sessões que [leem configurações gerenciadas pelo servidor](/docs/pt/managed-settings#where-and-when-a-policy-applies). claude.ai também as verifica quando qualquer pessoa em sua organização adiciona um novo marketplace de um repositório git em claude.ai, ou de **Customize** no aplicativo Claude Desktop fora de sua aba Code. Isso cobre um marketplace que um membro adiciona para sua própria conta e um adicionado para toda a organização em [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins). claude.ai recusa um repositório que a lista de permissões não admite ou que a lista de bloqueio nomeia. Ele não re-verifica um marketplace que foi adicionado em qualquer lugar antes de você definir as listas, e não verifica plugins enviados.

1134* **Um arquivo de configurações gerenciadas, política de nível do SO ou outra fonte gerenciada**: Claude Code aplica ambas as listas onde lê essa fonte. claude.ai não a lê.

~~1135~~

1136Para bloquear todos os repositórios de marketplace sob um proprietário GitHub, use a forma owner-wildcard em uma entrada `blockedMarketplaces`: `{ "source": "github", "repo": "untrusted-org/*" }`. Requer Claude Code v2.1.223 ou posterior. Para as regras de correspondência, que diferem entre a lista de bloqueio e a lista de permissões, veja [Owner wildcards](/docs/pt/settings-reference#owner-wildcards).

~~1137~~

1138Quando um usuário adiciona uma URL de repositório `https://` que Claude Code [clona em vez de buscar](/docs/pt/discover-plugins#add-from-other-git-hosts), como um repositório `github.com` ou `gitlab.com` simples, Claude Code também a verifica contra as entradas `url` em `blockedMarketplaces`. Claude Code bloqueia a adição se uma entrada nomeia a mesma URL. Nessa comparação, Claude Code ignora o sufixo `.git` e qualquer ref que o usuário acrescente após `#`. Requer Claude Code v2.1.232 ou posterior. Antes de v2.1.232, Claude Code correspondia a uma entrada `url` apenas contra uma URL que buscava como um arquivo `marketplace.json` hospedado.

~~1139~~

1140A lista de permissões usa correspondência exata para a maioria dos tipos de fonte, além de entradas `github` com owner-wildcard. Para um marketplace ser permitido, todos os campos especificados devem corresponder:

~~1141~~

1142* Para fontes GitHub: `repo` é obrigatório, nomeando um repositório ou usando a forma owner-wildcard `owner/*` para cobrir todos os repositórios sob esse proprietário. Para como entradas wildcard correspondem, incluindo as regras de caso, veja [Owner wildcards](/docs/pt/settings-reference#owner-wildcards). Para entradas de repositório único, `ref` deve corresponder exatamente ou estar ausente tanto da fonte de marketplace quanto da entrada de lista de permissões, e a mesma regra se aplica a `path`

1143* Para fontes de URL: a URL completa deve corresponder exatamente

1144* Para fontes `hostPattern`: o host do marketplace é correspondido contra o padrão regex

1145* Para fontes `pathPattern`: o caminho do sistema de arquivos do marketplace é correspondido contra o padrão regex

~~1146~~

1147A correspondência exata da lista de permissões trata URLs que diferem apenas por uma barra à direita, um sufixo `.git` ou o esquema `ssh://` e `https://` como valores diferentes. Se o marketplace da sua organização pode ser clonado por mais de uma forma de URL, prefira uma entrada `hostPattern` em vez de uma URL literal para que as formas `https://`, `ssh://` e `user@host:path` todas correspondam.

~~1148~~

1149Um [marketplace hospedado em claude.ai](/docs/pt/discover-plugins#add-from-claude-ai) é correspondido por host: uma entrada `hostPattern` que corresponde a `claude.ai` o governa, em `strictKnownMarketplaces` e em `blockedMarketplaces`. Na lista de permissões, tal entrada não admite uploads pessoais de claude.ai de um membro. Requer Claude Code v2.1.273 ou posterior.

~~1150~~

1151Como `strictKnownMarketplaces` é definido em [configurações gerenciadas](/docs/pt/managed-settings), configurações individuais de usuários e projetos não podem substituir essas restrições.

~~1152~~

1153Para detalhes de configuração completos incluindo todos os tipos de fonte suportados e comparação com `extraKnownMarketplaces`, veja a [referência strictKnownMarketplaces](/docs/pt/settings-reference#strictknownmarketplaces).

~~1154~~

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

1156 Resolução de versão e canais de lançamento

1157</h3>

~~1158~~

1159As versões de plugin determinam caminhos de cache e detecção de atualização: se a versão resolvida corresponder ao que um usuário já tem, `/plugin update` e auto-atualização pulam o plugin. Para fontes baseadas em git, se você omitir `version`, Claude Code usa o SHA do commit resolvido da fonte, então os usuários recebem uma atualização sempre que esse commit muda; esta é a configuração mais simples para plugins internos ou em desenvolvimento ativo. Veja [Version management](/docs/pt/plugins-reference#version-management) para a ordem de resolução completa, incluindo fontes `archive`.

~~1160~~

1161<Warning>

1162 Definir `version` fixa o plugin para todos os tipos de fonte exceto [`command`](#command-sources), cuja versão sempre inclui um hash do que o comando produziu. Um plugin [carregado em lugar](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) de um marketplace adicionado como um diretório local também não é fixado. Se você declarar `"version": "1.0.0"` em `plugin.json` e fazer push de novos commits sem alterar essa string, usuários existentes desses tipos de fonte mantêm a cópia em cache, porque Claude Code vê a mesma versão. Aumente o campo em cada lançamento, ou omita-o para usar a versão resolvida.

~~1163~~

1164 Evite definir `version` em ambos `plugin.json` e a entrada de marketplace. O valor `plugin.json` sempre vence silenciosamente, então uma versão de manifesto obsoleta pode mascarar uma versão que você definiu em `marketplace.json`.

1165</Warning>

~~1166~~

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

1168 Configurar canais de lançamento

1169</h4>

~~1170~~

1171Para suportar canais de lançamento "stable" e "latest" para seus plugins, você pode configurar dois marketplaces que apontam para diferentes refs ou SHAs do mesmo repositório. Você pode então atribuir cada grupo de usuários seu próprio marketplace através de configurações gerenciadas de uma de duas formas:

~~1172~~

1173* Implante [configurações gerenciadas gerenciadas por endpoint](/docs/pt/managed-settings#delivery-mechanisms) separadas, como um arquivo de configurações gerenciadas ou um perfil MDM, para os dispositivos de cada grupo. [Como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#precedence-within-the-managed-tier) diz se o arquivo por grupo ou perfil se aplica em um dispositivo que também tem uma fonte em toda a organização.

1174* Defina uma [política de gateway de aplicativos Claude](/docs/pt/claude-apps-gateway-config#managed) por grupo. O gateway aplica a primeira política cuja regra de correspondência se encaixa em um usuário, então ordene as políticas para que cada usuário chegue à política do seu grupo. A `extraKnownMarketplaces` de uma política de grupo substitui o mapa da política catch-all em vez de mesclar com ele, então liste todos os marketplaces que o grupo precisa na política do grupo, não apenas seu marketplace de canal.

~~1175~~

1176Configurações gerenciadas pelo servidor do console de administração [se aplicam a todos os usuários em sua organização](/docs/pt/server-managed-settings#current-limitations), então não conseguem carregar uma atribuição por grupo.

~~1177~~

1178<Warning>

1179 Cada canal deve resolver para uma versão diferente. Se você usar versões explícitas, `plugin.json` deve declarar uma `version` diferente em cada ref fixado. Se você omitir `version`, os SHAs de commit distintos já distinguem os canais. Se dois refs resolverem para a mesma string de versão, Claude Code os trata como idênticos e pula a atualização.

1180</Warning>

~~1181~~

1182<h5 id="example">

1183 Exemplo

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 Atribuir canais a grupos de usuários

1220</h5>

~~1221~~

1222Atribua cada marketplace ao seu grupo de usuários através das configurações gerenciadas por endpoint por grupo ou política de gateway descrita em [Configurar canais de lançamento](#set-up-release-channels). Por exemplo, o grupo stable recebe:

~~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~~

1237O grupo early-access recebe `latest-tools` em vez disso:

~~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 Fixar versões de dependência

1254</h4>

~~1255~~

1256Um plugin pode restringir suas dependências a um intervalo semver para que atualizações de uma dependência não quebrem o plugin dependente. Veja [Constrain plugin dependency versions](/docs/pt/plugin-dependencies) para a convenção de git-tag `{plugin-name}--v{version}`, sintaxe de intervalo e como múltiplas restrições na mesma dependência são combinadas.

~~1257~~

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

1259 Renomear ou remover um plugin

1260</h3>

~~1261~~

1262O `name` de um plugin é seu identificador estável. Os usuários o referenciam em `enabledPlugins`, `pluginConfigs` e comandos `/plugin install`, então alterá-lo quebra cada instalação existente. Para alterar o rótulo mostrado na UI sem quebrar instalações, defina [`displayName`](#optional-plugin-fields) e mantenha `name` inalterado.

~~1263~~

1264Se você deve alterar o `name` de um plugin, ou remover um plugin do array `plugins`, adicione uma entrada de nível superior `renames` para que usuários existentes migrem em vez de ver um erro `plugin-not-found`. A migração automática requer Claude Code v2.1.193 ou posterior. Mapeie cada nome anterior para seu nome atual, ou para `null` se o plugin não existir mais. O exemplo a seguir renomeia `formatter` para `code-formatter` e registra que `legacy-linter` foi removido:

~~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 um usuário inicia Claude Code com o nome antigo ainda em suas configurações, Claude Code segue o mapa `renames`:

~~1281~~

1282* Se a entrada aponta para um novo nome, Claude Code carrega o plugin sob seu novo nome e mostra um aviso de uma linha como `Renamed to "code-formatter" in the "acme-tools" marketplace`. Ele então reescreve a chave antiga para a chave nova nos escopos de configurações do usuário, projeto e local para ambos `enabledPlugins` e `pluginConfigs`, para que o aviso apareça uma vez.

1283* Para uma entrada `null`, Claude Code descarta a chave antiga e o aviso relata que o plugin foi removido do marketplace.

1284* Se o plugin renomeado usa uma fonte remota como `github` ou `npm`, Claude Code relata `plugin-cache-miss` após o renome e o usuário deve executar `/plugin install` uma vez para buscá-lo sob o novo nome.

~~1285~~

1286Trate `renames` como histórico apenas para anexação: mantenha entradas antigas no lugar mesmo depois que você espera que cada usuário tenha migrado. Claude Code segue cadeias, então se você depois renomear `code-formatter` para `formatter-pro`, adicione uma segunda entrada em vez de editar a primeira. Um usuário que ainda tem o `formatter` original habilitado então resolve através de ambas as entradas para `formatter-pro`.

~~1287~~

1288Execute `claude plugin validate .` após editar o mapa; ele rejeita qualquer entrada cuja cadeia forma um ciclo ou não termina em `null` ou um nome listado em `plugins`.

~~1289~~

1290<Note>

1291 Configurações gerenciadas e de política são somente leitura para Claude Code, então plugins habilitados lá não podem ser reescritos automaticamente. O plugin renomeado ainda carrega cada sessão, mas o aviso de renome recorre até que um administrador atualize `enabledPlugins` no arquivo de configurações gerenciadas para usar o novo nome. O mesmo se aplica a plugins habilitados através de outras fontes somente leitura como `--add-dir`.

1292</Note>

~~1293~~

1294Versões anteriores de Claude Code ignoram o campo `renames` e relatam `plugin-not-found` para o nome antigo.

~~1295~~

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

1297 Validação e testes

1298</h2>

~~1299~~

1300Teste seu marketplace antes de compartilhar. A validação verifica a estrutura do arquivo; para testar se um plugin muda o que Claude faz em prompts realistas, execute seu conjunto de avaliação com [`claude plugin eval`](/docs/pt/plugin-evals) antes de publicar uma nova versão.

~~1301~~

1302Do seu diretório de marketplace, valide a sintaxe JSON:

~~1303~~

1304```bash theme={null}

1305claude plugin validate .

1306```

~~1307~~

1308Ou de dentro de Claude Code:

~~1309~~

1310```shell theme={null}

1311/plugin validate .

1312```

~~1313~~

1314Adicione o marketplace para testes:

~~1315~~

1316```shell theme={null}

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

1318```

~~1319~~

1320Instale um plugin de teste para verificar se tudo funciona:

~~1321~~

1322```shell theme={null}

1323/plugin install test-plugin@marketplace-name

1324```

~~1325~~

1326Para fluxos de trabalho completos de testes de plugin, veja [Testar seus plugins localmente](/docs/pt/plugins#test-your-plugins-locally). Para troubleshooting técnico, veja [Plugins reference](/docs/pt/plugins-reference).

~~1327~~

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

1329 Gerenciar marketplaces a partir da CLI

1330</h2>

~~1331~~

1332Claude Code fornece subcomandos `claude plugin marketplace` não-interativos para scripting e automação. Estes são equivalentes aos comandos `/plugin marketplace` disponíveis dentro de uma sessão interativa.

~~1333~~

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

1335 Plugin marketplace add

1336</h3>

~~1337~~

1338Adicione um marketplace de um repositório GitHub, URL git, URL remota ou caminho local.

~~1339~~

1340```bash theme={null}

1341claude plugin marketplace add <source> [options]

1342```

~~1343~~

1344**Argumentos:**

~~1345~~

1346* `<source>`: Atalho GitHub `owner/repo`, URL git, URL remota para um arquivo `marketplace.json` ou caminho de diretório local. Para fixar a um branch ou tag, anexe `@ref` ao atalho GitHub ou `#ref` a uma URL git

~~1347~~

1348Uma URL deve incluir seu esquema. A partir de Claude Code v2.1.196, um host digitado sem um, como `gitlab.example.com/team/plugins`, é rejeitado como um atalho `owner/repo` inválido e o erro informa para adicionar `https://` ou usar `./` para um caminho local. Versões anteriores o interpretavam como um caminho de repositório GitHub e falham no momento do clone com um erro de não encontrado do GitHub.

~~1349~~

1350**Opções:**

~~1351~~

1352| Opção | Descrição | Padrão |

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

1354| `--scope <scope>` | Onde declarar o marketplace: `user`, `project` ou `local`. Veja [Plugin installation scopes](/docs/pt/plugins-reference#plugin-installation-scopes) | `user` |

1355| `--sparse <paths...>` | Limitar checkout a diretórios específicos via git sparse-checkout. Útil para monorepos | |

1356| `--claudeai` | Leia o argumento como o nome de um [marketplace hospedado em claude.ai](/docs/pt/discover-plugins#add-from-claude-ai) em vez de uma fonte. Requer Claude Code v2.1.273 ou posterior | |

~~1357~~

1358Adicione um marketplace do GitHub usando atalho `owner/repo`:

~~1359~~

1360```bash theme={null}

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

1362```

~~1363~~

1364Fixe a um branch ou tag específico com `@ref`:

~~1365~~

1366```bash theme={null}

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

1368```

~~1369~~

1370Adicione de uma URL git em um host não-GitHub:

~~1371~~

1372```bash theme={null}

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

1374```

~~1375~~

1376Adicione de uma URL remota que serve o arquivo `marketplace.json` diretamente:

~~1377~~

1378```bash theme={null}

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

1380```

~~1381~~

1382Adicione de um diretório local para testes:

~~1383~~

1384```bash theme={null}

1385claude plugin marketplace add ./my-marketplace

1386```

~~1387~~

1388Declare o marketplace no escopo do projeto para que seja compartilhado com sua equipe via `.claude/settings.json`:

~~1389~~

1390```bash theme={null}

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

1392```

~~1393~~

1394Para um monorepo, limite o checkout aos diretórios que contêm conteúdo de plugin:

~~1395~~

1396```bash theme={null}

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

1398```

~~1399~~

1400Adicione um [marketplace hospedado em claude.ai](/docs/pt/discover-plugins#add-from-claude-ai) pelo nome impresso na seção `From claude.ai:` de `claude plugin marketplace list`:

~~1401~~

1402```bash theme={null}

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

1404```

~~1405~~

1406Com `--claudeai`, o comando recusa `--scope` e `--sparse`. O marketplace é hospedado para sua conta, não declarado em um arquivo de configurações, portanto você não pode compartilhá-lo através do `.claude/settings.json` de um projeto.

~~1407~~

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

1409 Plugin marketplace list

1410</h3>

~~1411~~

1412Liste todos os marketplaces configurados.

~~1413~~

1414```bash theme={null}

1415claude plugin marketplace list [options]

1416```

~~1417~~

1418**Opções:**

~~1419~~

1420| Opção | Descrição |

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

1422| `--json` | Saída como JSON |

~~1423~~

1424Com `--json`, cada entrada inclui `name`, `source`, um campo `installLocation` com o caminho do cache local onde o marketplace é armazenado, e campos específicos da fonte: `repo` para fontes GitHub, `url` para fontes git e URL, e `path` para fontes locais. Fontes GitHub e git também incluem um campo `ref` quando o marketplace foi adicionado com um branch ou tag fixado.

~~1425~~

1426Um [marketplace claude.ai](/docs/pt/discover-plugins#add-from-claude-ai) adicionado não tem um clone local, portanto sua entrada carrega seus identificadores claude.ai, `marketplaceId` e `organizationUuid`, no lugar de `installLocation`.

~~1427~~

1428Em sessões de terminal onde [plugins sincronizam de sua conta claude.ai](/docs/pt/plugins-reference#synced-plugins), a listagem de texto termina com uma seção `From claude.ai:` nomeando o que claude.ai lista para sua conta além dos marketplaces que você adicionou. Para adicionar um deles, veja [Adicionar de claude.ai](/docs/pt/discover-plugins#add-from-claude-ai). A saída `--json` cobre apenas marketplaces configurados e deixa essa seção de fora. Requer Claude Code v2.1.273 ou posterior.

~~1429~~

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

1431 Plugin marketplace remove

1432</h3>

~~1433~~

1434Remova um marketplace configurado. O alias `rm` também é aceito.

~~1435~~

1436```bash theme={null}

1437claude plugin marketplace remove <name> [options]

1438```

~~1439~~

1440**Argumentos:**

~~1441~~

1442* `<name>`: nome do marketplace a remover, conforme mostrado por `claude plugin marketplace list`. Este é o `name` de `marketplace.json`, não a fonte que você passou para `add`

~~1443~~

1444**Opções:**

~~1445~~

1446| Opção | Descrição | Padrão |

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

1448| `--scope <scope>` | Restringir remoção a um único escopo de configurações: `user`, `project` ou `local`. Veja [Plugin installation scopes](/docs/pt/plugins-reference#plugin-installation-scopes). Quando omitido, a declaração é removida de cada escopo editável. Quando fornecido, apenas a declaração desse escopo é removida; o estado compartilhado, cache e dados de plugin instalado são preservados quando o marketplace ainda está declarado em outro escopo | (todos os escopos) |

~~1449~~

1450<Warning>

1451 Remover um marketplace de seu último escopo restante também desinstala qualquer plugin que você instalou dele. Para atualizar um marketplace sem perder plugins instalados, use `claude plugin marketplace update` em vez disso.

1452</Warning>

~~1453~~

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

1455 Plugin marketplace update

1456</h3>

~~1457~~

1458Atualize marketplaces de suas fontes para recuperar novos plugins e mudanças de versão. Um marketplace adicionado com um branch ou tag `ref` é atualizado para o commit mais recente dessa ref, não para o branch padrão do repositório.

~~1459~~

1460```bash theme={null}

1461claude plugin marketplace update [name]

1462```

~~1463~~

1464**Argumentos:**

~~1465~~

1466* `[name]`: nome do marketplace a atualizar, conforme mostrado por `claude plugin marketplace list`. Atualiza todos os marketplaces se omitido

~~1467~~

1468Tanto `remove` quanto `update` falham quando executados contra um marketplace gerenciado por seed, que é somente leitura. Ao atualizar todos os marketplaces, entradas gerenciadas por seed são puladas e outros marketplaces ainda são atualizados. Para alterar plugins fornecidos por seed, peça ao seu administrador para atualizar a imagem seed. Veja [Pré-popular plugins para containers](#pre-populate-plugins-for-containers).

~~1469~~

1470<h2 id="troubleshooting">

1471 Troubleshooting

1472</h2>

~~1473~~

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

1475 Marketplace não carregando

1476</h3>

~~1477~~

1478**Sintomas**: Não consegue adicionar marketplace ou ver plugins dele

~~1479~~

1480**Soluções**:

~~1481~~

1482* Verifique se a URL do marketplace é acessível

1483* Verifique se `.claude-plugin/marketplace.json` existe no caminho especificado

1484* Garanta que a sintaxe JSON é válida usando `claude plugin validate .` ou `/plugin validate .` do diretório do marketplace. Para verificar o frontmatter de skill, agent e command, veja [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest)

1485* Para repositórios privados, confirme que você tem permissões de acesso

~~1486~~

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

1488 Erros de validação de marketplace

1489</h3>

~~1490~~

1491Execute `claude plugin validate .` ou `/plugin validate .` do seu diretório de marketplace para verificar problemas. Quando apontado para um diretório de marketplace, o validador verifica `marketplace.json` para erros de schema, nomes de plugin duplicados e travessia de caminho de fonte. Para cada entrada cuja `source` é um caminho local, ele também valida o próprio `plugin.json` daquele plugin e avisa quando a `version` da entrada não corresponde à do `plugin.json`. Problemas encontrados no `plugin.json` de um plugin são prefixados com o índice da entrada, na forma `plugins[2] plugin.json →`.

~~1492~~

1493A partir de Claude Code v2.1.196, a passagem por entrada também:

~~1494~~

1495* inclui plugins cuja `source` é `.`

1496* executa quando `marketplace.json` está fora de um diretório `.claude-plugin`, resolvendo fontes contra o próprio diretório do arquivo

1497* relata os problemas de cada entrada mesmo quando outra parte do arquivo tem erros de schema

~~1498~~

1499Versões anteriores pulam plugins na raiz do marketplace e apenas descem de um `.claude-plugin/marketplace.json`.

~~1500~~

1501Do diretório de um marketplace, Claude Code não abre os arquivos de skill, agent, command ou hook dos plugins. Para encontrar erros nesses arquivos, veja [Validate a plugin or a directory without a manifest](#validate-a-plugin-or-a-directory-without-a-manifest). A tabela abaixo lista os erros mais comuns de um diretório de marketplace, com a causa e correção para cada um:

~~1502~~

1503| Erro | Causa | Solução |

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

1505| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | O diretório que você nomeou não tem `.claude-plugin/marketplace.json` ou `plugin.json`, e nenhum arquivo de skill, agent ou command para verificar | Execute a partir da raiz do marketplace, ou crie `.claude-plugin/marketplace.json` com os campos obrigatórios |

1506| `Invalid JSON syntax: Unexpected token...` | Erro de sintaxe JSON em marketplace.json | Verifique vírgulas ausentes, vírgulas extras ou strings não citadas |

1507| `Duplicate plugin name "x" found in marketplace` | Dois plugins compartilham o mesmo nome | Dê a cada plugin um valor `name` único |

1508| `plugins[0].source: Path contains ".."` | Um segmento do caminho de fonte é `..` | Use caminhos relativos à raiz do marketplace sem segmentos `..`. Veja [Relative paths](#relative-paths) |

1509| `Marketplace name cannot contain control or bidirectional-formatting characters` | O `name` do marketplace contém um caractere de formatação bidirecional Unicode ou um caractere de controle, como um escape ou uma quebra de linha | Remova o caractere do nome. Antes de v2.1.247, esses caracteres produziam o erro `Marketplace name impersonates an official Anthropic/Claude marketplace` |

1510| `Plugin name cannot contain control or bidirectional-formatting characters` | Um `name` de plugin contém um caractere de formatação bidirecional Unicode ou um caractere de controle, como um escape ou uma quebra de linha | Remova o caractere do nome. Antes de v2.1.247, Claude Code não executava essa verificação |

~~1511~~

1512**Avisos** (não bloqueadores):

~~1513~~

1514* `Marketplace has no plugins defined`: adicione pelo menos um plugin ao array `plugins`

1515* `No marketplace description provided`: adicione uma `description` de nível superior para ajudar os usuários a entender seu marketplace

1516* `Plugin name "x" is not kebab-case`: renomeie para apenas letras minúsculas, dígitos e hífens (por exemplo, `my-plugin`). Claude Code aceita outras formas, mas a sincronização de marketplace do claude.ai as rejeita.

1517* `Marketplace name "x" is reserved in Claude Desktop`: o marketplace é nomeado `org`, `org-provisioned` ou `unknown`, em qualquer casing. Claude Code aceita esses nomes, mas a sincronização de marketplace gerenciada do Claude Desktop rejeita o marketplace inteiro. Renomeie o marketplace. Antes de v2.1.221, `claude plugin validate` não executava essa verificação.

1518* `Marketplace name "x" is not accepted by Claude Desktop` ou `Plugin name "x" is not accepted by Claude Desktop`: Claude Desktop aceita nomes de até 128 caracteres feitos de letras, dígitos, `.`, `_` e `-`, começando com uma letra ou dígito. Claude Code aceita outras formas, mas a sincronização de marketplace gerenciada do Claude Desktop rejeita um marketplace cujo nome falha na verificação e silenciosamente descarta uma entrada de plugin cujo nome falha. Renomeie o marketplace ou plugin. Antes de v2.1.221, `claude plugin validate` não executava essas verificações.

~~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~~

1524Para encontrar arquivos de skill, agent e command cujo frontmatter não analisa, execute `claude plugin validate` e nomeie o diretório que os contém. Claude Code não procura fora do diretório que você nomeia. Toda execução exceto uma contra um plugin que tem um `plugin.json` requer Claude Code v2.1.233 ou posterior.

~~1525~~

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

1527 Pick the directory to name

1528</h5>

~~1529~~

1530Claude Code verifica diferentes arquivos dependendo de qual diretório você nomeia. Encontre o que você quer verificar na primeira coluna e execute o comando dessa linha:

~~1531~~

1532| Para verificar | Execute | Claude Code verifica |

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

1534| Um plugin que tem um `plugin.json` | `claude plugin validate ./plugins/my-plugin` | `plugin.json`, `hooks/hooks.json` e os diretórios `skills`, `agents` e `commands` na raiz do plugin |

1535| Um diretório de skills, agents ou commands, como um plugin que ainda não tem `plugin.json` | `claude plugin validate .claude/skills`, `~/.claude/agents` ou `./my-plugin/agents` | Cada arquivo de skill, agent ou command naquele diretório |

1536| Uma pasta cujo skill é seu `SKILL.md` raiz | `claude plugin validate ./skills`, nomeando o diretório `skills` que contém a pasta | O `SKILL.md` raiz de cada pasta. O diretório que contém deve ser nomeado `skills`; uma pasta sob outro nome, como `plugins/`, não tem uma execução que verifica seu `SKILL.md` raiz |

1537| Os três diretórios de um projeto de uma vez | `claude plugin validate .claude`, ou a raiz do projeto quando não tem manifesto `.claude-plugin/` | `.claude/skills`, `.claude/agents` e `.claude/commands` |

1538| Seus diretórios de nível de usuário | `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 Check a plugin whose skill is its root `SKILL.md`

1542</h5>

~~1543~~

1544Quando você executa `claude plugin validate` contra um diretório de plugin, Claude Code não verifica um `SKILL.md` na raiz do plugin. Quando o plugin fica em um diretório nomeado `skills`, execute o comando duas vezes:

~~1545~~

1546* Nomeie aquele diretório `skills` para verificar o `SKILL.md` raiz do plugin.

1547* Nomeie o diretório do plugin para verificar o resto.

~~1548~~

1549Quando o plugin fica sob outro nome, como `plugins/`, a execução do diretório `skills` não está disponível e nenhuma execução verifica seu `SKILL.md` raiz.

~~1550~~

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

1552 Check files behind symlinks

1553</h5>

~~1554~~

1555Quando você executa `claude plugin validate`, Claude Code não segue symlinks dentro do diretório que você nomeia. O que ele faz depende de onde o link está:

~~1556~~

1557* **Um diretório `skills`, `agents` ou `commands` vinculado sob a raiz do plugin ou `.claude`**: Claude Code avisa que nada nele foi lido.

1558* **Uma entrada vinculada dentro de um diretório `skills`, `agents` ou `commands`**: Claude Code a pula e avisa, por diretório, quantas entradas pulou que uma sessão carregaria.

1559* **O diretório `skills`, `agents` ou `commands` que você nomeia é ele próprio um symlink, ou seu diretório pai `.claude` é**: Claude Code relata um erro e não verifica nada nele. Nomeie o diretório real em vez disso.

~~1560~~

1561Em dois casos de skills, a execução passa com avisos. Para verificar os arquivos vinculados, execute novamente e nomeie um diretório que os contém diretamente:

~~1562~~

1563* **Um plugin cujo diretório `skills` [vincula aos skills de um plugin irmão](/docs/pt/plugins-reference#share-files-within-a-marketplace-with-symlinks)**: nomeie o diretório do plugin irmão.

1564* **Uma [entrada de skill vinculada](/docs/pt/skills#where-skills-live) em `~/.claude/skills` ou `.claude/skills`**: Claude Code segue a entrada em uma sessão. Para verificá-la, nomeie um diretório chamado `skills` que contém a pasta real.

~~1565~~

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

1567 Read the validation results

1568</h5>

~~1569~~

1570Uma execução limpa termina com `Validation passed`.

~~1571~~

1572`No manifest found in directory` significa que Claude Code não encontrou `plugin.json` ou `marketplace.json` lá, e nenhum arquivo de skill, agent ou command nos diretórios que ele sonda sob ele. Nomeie o diretório `skills`, `agents` ou `commands` que contém seus arquivos em vez disso.

~~1573~~

1574Dois dos erros que Claude Code relata dessas execuções, com a correção para cada um:

~~1575~~

1576* `YAML frontmatter failed to parse: ...`: corrija o YAML no bloco frontmatter do arquivo de skill, agent ou command. Até você fazer isso, uma sessão lê nenhum campo frontmatter do arquivo

1577* `Invalid JSON syntax: ...` em `hooks/hooks.json`: corrija a sintaxe JSON. Até você fazer isso, uma sessão carrega o plugin sem os hooks naquele arquivo. Claude Code relata esse erro apenas em uma execução de plugin

~~1578~~

1579Em uma execução de plugin, Claude Code também avisa sobre um `CLAUDE.md` na raiz do plugin. Para caminhos que você define através dos [component path fields](/docs/pt/plugins-reference#component-path-fields) em `plugin.json`, Claude Code verifica que cada caminho existe mas não lê os arquivos lá.

~~1580~~

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

1582 Falhas de instalação de plugin

1583</h3>

~~1584~~

1585**Sintomas**: Marketplace aparece mas a instalação do plugin falha

~~1586~~

1587**Soluções**:

~~1588~~

1589* Verifique se as URLs de fonte do plugin são acessíveis

1590* Verifique se os diretórios de plugin contêm arquivos obrigatórios

1591* Para fontes GitHub, garanta que repositórios são públicos ou você tem acesso

1592* Teste fontes de plugin manualmente clonando/baixando

1593* Se a fonte fixa tanto `ref` quanto `sha`, uma branch ou tag upstream deletada não bloqueia a instalação na maioria dos hosts git, incluindo GitHub, GitLab e Bitbucket. Em servidores que não suportam busca de commits por SHA, como AWS CodeCommit, o `ref` ainda deve existir e o commit fixado deve ser alcançável a partir dele. Se a instalação ainda falhar, confirme que o commit fixado ainda existe no repositório

~~1594~~

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

1596 Falha de autenticação de repositório privado

1597</h3>

~~1598~~

1599**Sintomas**: Erros de autenticação ao instalar plugins de repositórios privados

~~1600~~

1601**Soluções**:

~~1602~~

1603Para instalação manual e atualizações:

~~1604~~

1605* Verifique se você está autenticado com seu provedor git (por exemplo, execute `gh auth status` para GitHub)

1606* Verifique se seu ajudante de credencial está configurado: `git config --global credential.helper`

1607* Execute `git ls-remote <marketplace-url>` para testar se git consegue autenticar por conta própria. Se git pedir um nome de usuário ou senha, armazene a credencial primeiro: para GitHub sobre HTTPS, execute `gh auth setup-git`, e para remotes SSH, carregue sua chave em `ssh-agent`

~~1608~~

1609Para atualizações automáticas em segundo plano:

~~1610~~

1611* A verificação em segundo plano usa seus ajudantes de credencial git configurados mas nunca solicita, então seu ajudante deve conseguir responder com uma credencial armazenada. Remotes SSH com uma chave carregada em `ssh-agent` também autenticam

1612* Se seu ajudante precisa solicitar você, a atualização em segundo plano falha silenciosamente e o checkout existente fica no lugar. Entre em seu ajudante primeiro para que ele mantenha uma credencial para o host. Para GitHub, execute `gh auth login`, depois `gh auth setup-git`

1613* Quando a verificação encontra novos commits, ou não consegue alcançar ou autenticar no remoto, Claude Code re-clona o marketplace com as mesmas credenciais. A re-clonagem pode expirar em repositórios grandes

1614* Defina `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para manter o checkout existente sem tentar a re-clonagem quando a verificação em segundo plano não conseguir alcançar ou autenticar no remoto

1615* Se a re-clonagem expirar em um repositório grande, aumente o limite com [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)

1616* Ou atualize marketplaces privados manualmente com `/plugin marketplace update <name>`, que usa suas credenciais

~~1617~~

1618Antes de v2.1.280, a verificação em segundo plano executava sem seus ajudantes de credencial e não conseguia autenticar em repositórios privados sobre HTTPS.

~~1619~~

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

1621 Atualizações de marketplace falham em ambientes offline

1622</h3>

~~1623~~

1624**Sintomas**: Em um ambiente offline ou airgapped, a atualização de marketplace em segundo plano não consegue alcançar o remoto e Claude Code repetidamente tenta uma re-clonagem que não consegue ter sucesso.

~~1625~~

1626**Causa**: A atualização em segundo plano verifica o remoto do marketplace para novos commits, e quando a verificação não consegue alcançar o remoto, Claude Code tenta clonar o marketplace novamente. Offline, o clone falha da mesma forma e o checkout existente fica no lugar. Antes de v2.1.274, a atualização executava `git pull` no checkout existente, movia o checkout para o lado para re-clonar quando o pull falhava, e o restaurava depois em base de melhor esforço.

~~1627~~

1628A atualização é executada em segundo plano após a inicialização, então não atrasa a inicialização. Cada sessão ainda repete a tentativa falhada, e cada operação git pode esperar o [timeout de 120 segundos](#git-operations-time-out).

~~1629~~

1630**Solução**: Defina `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para pular a tentativa de re-clonagem e continuar usando o checkout existente quando a verificação não conseguir alcançar o remoto:

~~1631~~

1632```bash theme={null}

1633export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1634```

~~1635~~

1636Para implantações totalmente offline onde o repositório nunca será alcançável, use [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) para pré-popular o diretório de plugins no tempo de construção em vez disso.

~~1637~~

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

1639 Operações Git expiram

1640</h3>

~~1641~~

1642**Sintomas**: Instalação de plugin ou atualizações de marketplace falham com um erro de timeout como `Git clone timed out after 120s`.

~~1643~~

1644**Causa**: Claude Code usa um timeout de 120 segundos para todas as operações git, incluindo clonagem de repositórios de plugin e re-clonagem de um marketplace para atualizá-lo. Repositórios grandes ou conexões de rede lentas podem exceder este limite.

~~1645~~

1646**Solução**: Aumente o timeout usando a variável de ambiente `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. O valor está em milissegundos:

~~1647~~

1648```bash theme={null}

1649export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutos

1650```

~~1651~~

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

1653 Plugins com caminhos relativos falham em marketplaces baseados em URL

1654</h3>

~~1655~~

1656**Sintomas**: Adicionou um marketplace via URL como `https://example.com/marketplace.json`, mas plugins com fontes de caminho relativo como `"./plugins/my-plugin"` falham ao instalar com `its marketplace entry path does not stay inside the marketplace directory`. Plugins já instalados falham ao carregar com `Plugin source path refused`. Ambas as mensagens têm uma [entrada de referência de erro](/docs/pt/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).

~~1657~~

1658**Causa**: adicionar um marketplace baseado em URL baixa apenas o próprio arquivo `marketplace.json`, e Claude Code não busca arquivos de plugin por caminho relativo daquele servidor. Caminhos relativos na entrada de marketplace referenciam arquivos no servidor remoto que não foram baixados.

~~1659~~

1660**Soluções**:

~~1661~~

1662* **Use fontes externas**: altere entradas de plugin para qualquer [plugin source](#plugin-sources) outro que não seja um caminho relativo:

1663 ```json theme={null}

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

1665 ```

1666* **Use um marketplace baseado em Git**: Hospede seu marketplace em um repositório Git e adicione-o com a URL git. Marketplaces baseados em Git clonam o repositório inteiro, tornando caminhos relativos funcionarem corretamente.

~~1667~~

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

1669 Arquivos não encontrados após instalação

1670</h3>

~~1671~~

1672**Sintomas**: Plugin instala mas referências a arquivos falham, especialmente arquivos fora do diretório do plugin

~~1673~~

1674**Causa**: Claude Code copia plugins instalados para um diretório de cache, a menos que o plugin carregue no local. Uma [`command` source em link mode](#copy-mode-and-link-mode) carrega no local, e assim também uma [relative path source](#relative-paths) em um marketplace adicionado de um diretório local. Caminhos que referenciam arquivos fora do diretório do plugin copiado (como `../shared-utils`) não funcionarão porque esses arquivos não são copiados.

~~1675~~

1676**Soluções**: Veja [Plugin caching and file resolution](/docs/pt/plugins-reference#plugin-caching-and-file-resolution) para workarounds incluindo symlinks e reestruturação de diretório.

~~1677~~

1678Para ferramentas de debugging adicionais e problemas comuns, veja [Debugging and development tools](/docs/pt/plugins-reference#debugging-and-development-tools).

~~1679~~

1680<h2 id="see-also">

1681 Veja também

1682</h2>

~~1683~~

1684* [Descobrir e instalar plugins pré-construídos](/docs/pt/discover-plugins) - Instalando plugins de marketplaces existentes

1685* [Plugins](/docs/pt/plugins) - Criando seus próprios plugins

1686* [Plugins reference](/docs/pt/plugins-reference) - Especificações técnicas completas e esquemas

1687* [Plugin settings](/docs/pt/settings-reference#plugin-settings) - Opções de configuração de plugin

1688* [strictKnownMarketplaces reference](/docs/pt/settings-reference#strictknownmarketplaces) - Restrições de marketplace gerenciado