> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Criar e distribuir um marketplace de plugins > Crie e hospede marketplaces de plugins para distribuir extensões Claude Code em equipes e comunidades. Um **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. Procurando instalar plugins de um marketplace existente? Veja [Descobrir e instalar plugins pré-construídos](/pt/discover-plugins).

Visão geral

Criar e distribuir um marketplace envolve: 1. **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](/pt/plugins) para detalhes sobre como criá-los. 2. **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). 3. **Hospedar o marketplace**: fazer push para GitHub, GitLab ou outro host git. Veja [Hospedar e distribuir marketplaces](#host-and-distribute-marketplaces). 4. **Compartilhar com usuários**: usuários adicionam seu marketplace com `/plugin marketplace add` e instalam plugins individuais. Veja [Descobrir e instalar plugins](/pt/discover-plugins). Depois 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`.

Passo a passo: criar um marketplace local

Este 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á. ```bash theme={null} mkdir -p my-marketplace/.claude-plugin mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review ``` Crie um arquivo `SKILL.md` que define o que a skill `quality-review` faz. ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null} --- description: Revisar código para bugs, segurança e desempenho --- Revise o código que selecionei ou as alterações recentes para: - Possíveis bugs ou casos extremos - Preocupações de segurança - Problemas de desempenho - Melhorias de legibilidade Seja conciso e acionável. ``` Crie um arquivo `plugin.json` que descreve o plugin. O manifesto vai no diretório `.claude-plugin/`. ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null} { "name": "quality-review-plugin", "description": "Adiciona uma skill quality-review para revisões rápidas de código", "version": "1.0.0" } ``` Definir `version` significa que os usuários só recebem atualizações quando você altera este campo, então aumente-o em cada lançamento. Se você omitir `version` e hospedar este marketplace no git, cada commit conta automaticamente como uma nova versão. Veja [Resolução de versão](#version-resolution-and-release-channels) para escolher a abordagem correta. Crie o catálogo de marketplace que lista seu plugin. ```json my-marketplace/.claude-plugin/marketplace.json theme={null} { "name": "my-plugins", "owner": { "name": "Seu Nome" }, "plugins": [ { "name": "quality-review-plugin", "source": "./plugins/quality-review-plugin", "description": "Adiciona uma skill quality-review para revisões rápidas de código" } ] } ``` Adicione o marketplace e instale o plugin. ```shell theme={null} /plugin marketplace add ./my-marketplace /plugin install quality-review-plugin@my-plugins ``` Selecione algum código em seu editor e execute sua nova skill. As skills do plugin são nomeadas com o nome do plugin. ```shell theme={null} /quality-review-plugin:quality-review ``` Para saber mais sobre o que os plugins podem fazer, incluindo hooks, agents, MCP servers e LSP servers, veja [Plugins](/pt/plugins). **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. Isso significa que os plugins não podem referenciar arquivos fora de seu diretório usando caminhos como `../shared-utils`, porque esses arquivos não serão copiados. Se você precisar compartilhar arquivos entre plugins, use symlinks. Veja [Plugin caching and file resolution](/pt/plugins-reference#plugin-caching-and-file-resolution) para detalhes.

Criar o arquivo de marketplace

Crie `.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. Cada 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. ```json theme={null} { "name": "company-tools", "owner": { "name": "DevTools Team", "email": "devtools@example.com" }, "plugins": [ { "name": "code-formatter", "source": "./plugins/formatter", "description": "Formatação automática de código ao salvar", "version": "2.1.0", "author": { "name": "DevTools Team" } }, { "name": "deployment-tools", "source": { "source": "github", "repo": "company/deploy-plugin" }, "description": "Ferramentas de automação de implantação" } ] } ```

Esquema de marketplace

Campos obrigatórios

| Campo | Tipo | Descrição | Exemplo | | :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | | `name` | string | Identificador de marketplace (kebab-case, sem espaços). 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: adicionar um segundo marketplace com o mesmo nome 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"` | | `owner` | object | Informações do mantenedor do marketplace ([veja campos abaixo](#owner-fields)) | | | `plugins` | array | Lista de plugins disponíveis | Veja abaixo | **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`. Nomes que imitam marketplaces oficiais, como `official-claude-plugins` ou `anthropic-tools-v2`, também são bloqueados.

Campos do proprietário

| Campo | Tipo | Obrigatório | Descrição | | :------ | :----- | :---------- | :----------------------------- | | `name` | string | Sim | Nome do mantenedor ou equipe | | `email` | string | Não | Email de contato do mantenedor |

Campos opcionais

| Campo | Tipo | Descrição | | :------------------------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$schema` | string | URL do JSON Schema para autocompletar e validação do editor. Claude Code ignora este campo no momento do carregamento. | | `description` | string | Breve descrição do marketplace | | `version` | string | Versão do manifesto do marketplace | | `metadata.pluginRoot` | string | Diretório base adicionado aos caminhos de fonte de plugin relativos (por exemplo, `"./plugins"` permite escrever `"source": "formatter"` em vez de `"source": "./plugins/formatter"`) | | `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](/pt/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). | | `renames` | object | {/* min-version: 2.1.193 */}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. | `description` e `version` também são aceitos sob `metadata` para compatibilidade com versões anteriores.

Entradas de plugin

Cada entrada de plugin no array `plugins` descreve um plugin e onde encontrá-lo. Você pode incluir qualquer campo do [esquema de manifesto de plugin](/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` e `relevance`.

Campos obrigatórios

| Campo | Tipo | Descrição | | :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Identificador de plugin (kebab-case, sem espaços). Isso é público: os usuários o veem ao instalar (por exemplo, `/plugin install my-plugin@marketplace`). | | `source` | string\|object | Onde buscar o plugin (veja [Fontes de plugin](#plugin-sources) abaixo) |

Campos de plugin opcionais

**Campos de metadados padrão:** | Campo | Tipo | Descrição | | :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `displayName` | string | {/* min-version: 2.1.143 */}Nome legível por humanos exibido em superfícies de UI. Volta para `name` quando omitido. Pode conter espaços e qualquer capitalização. Não é usado para namespacing ou lookup. Requer Claude Code v2.1.143 ou posterior. | | `description` | string | Breve descrição do plugin | | `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. Omita para usar o SHA do commit do git. Veja [Resolução de versão](#version-resolution-and-release-channels). | | `author` | object | Informações do autor do plugin (`name` obrigatório, `email` opcional) | | `homepage` | string | URL da página inicial ou documentação do plugin | | `repository` | string | URL do repositório de código-fonte | | `license` | string | Identificador de licença SPDX (por exemplo, MIT, Apache-2.0) | | `keywords` | array | Tags para descoberta e categorização de plugins | | `category` | string | Categoria do plugin para organização | | `tags` | array | Tags para pesquisabilidade | | `strict` | boolean | Controla se `plugin.json` é a autoridade para definições de componentes (padrão: true). Veja [Strict mode](#strict-mode) abaixo. | | `relevance` | object | {/* min-version: 2.1.152 */}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](/pt/plugin-relevance). Requer Claude Code v2.1.152 ou posterior. | | `defaultEnabled` | boolean | {/* min-version: 2.1.154 */}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](/pt/plugins-reference#default-enablement). Requer Claude Code v2.1.154 ou posterior. | **Campos de configuração de componentes:** | Campo | Tipo | Descrição | | :----------- | :------------- | :-------------------------------------------------------------------------- | | `skills` | string\|array | Caminhos personalizados para diretórios de skill contendo `/SKILL.md` | | `commands` | string\|array | Caminhos personalizados para arquivos de skill `.md` simples ou diretórios | | `agents` | string\|array | Caminhos personalizados para arquivos de agent | | `hooks` | string\|object | Configuração de hooks personalizada ou caminho para arquivo de hooks | | `mcpServers` | string\|object | Configurações de MCP server ou caminho para config de MCP | | `lspServers` | string\|object | Configurações de LSP server ou caminho para config de LSP |

Fontes de plugin

As 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`. Depois que um plugin é clonado ou copiado para a máquina local, ele é copiado para o cache de plugin versionado local em `~/.claude/plugins/cache`. | Fonte | Tipo | Campos | Notas | | ---------------- | --------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Caminho relativo | `string` (por exemplo, `"./my-plugin"`) | nenhum | Diretório local dentro do repositório de marketplace. Deve começar com `./`. Resolvido relativamente à raiz do marketplace, não ao diretório `.claude-plugin/` | | `github` | object | `repo`, `ref?`, `sha?` | | | `url` | object | `url`, `ref?`, `sha?` | Fonte de URL Git | | `git-subdir` | object | `url`, `path`, `ref?`, `sha?` | Subdiretório dentro de um repositório git. Clona esparsamente para minimizar largura de banda para monorepos | | `npm` | object | `package`, `version?`, `registry?` | Instalado via `npm install` | **Fontes de marketplace vs fontes de plugin**: Estes são conceitos diferentes que controlam coisas diferentes. * **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`. Suporta `ref` (branch/tag) mas não `sha`. * **Fonte de plugin**: onde buscar um plugin individual listado no marketplace. Definido no campo `source` de cada entrada de plugin dentro de `marketplace.json`. Suporta tanto `ref` (branch/tag) quanto `sha` (commit exato). 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. Os 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. Na 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.

Caminhos relativos

Para plugins no mesmo repositório, use um caminho começando com `./`: ```json theme={null} { "name": "my-plugin", "source": "./plugins/my-plugin" } ``` Os caminhos são resolvidos relativamente à raiz do marketplace, que é o diretório contendo `.claude-plugin/`. No exemplo acima, `./plugins/my-plugin` aponta para `/plugins/my-plugin`, mesmo que `marketplace.json` viva em `/.claude-plugin/marketplace.json`. Não use `../` para referenciar caminhos fora da raiz do marketplace. Caminhos relativos são resolvidos 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 apenas esse arquivo é baixado. Para distribuição baseada em URL, use fontes GitHub, npm ou URL git. Veja [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) para detalhes.

Repositórios GitHub

```json theme={null} { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo" } } ``` Você pode fixar a um branch, tag ou commit específico: ```json theme={null} { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo", "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } ``` | Campo | Tipo | Descrição | | :----- | :----- | :---------------------------------------------------------------------------------- | | `repo` | string | Obrigatório. Repositório GitHub no formato `owner/repo` | | `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) | | `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

Repositórios Git

```json theme={null} { "name": "git-plugin", "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git" } } ``` Você pode fixar a um branch, tag ou commit específico: ```json theme={null} { "name": "git-plugin", "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git", "ref": "main", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } ``` | Campo | Tipo | Descrição | | :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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 | | `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) | | `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

Subdiretórios Git

Use `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. ```json theme={null} { "name": "my-plugin", "source": { "source": "git-subdir", "url": "https://github.com/acme-corp/monorepo.git", "path": "tools/claude-plugin" } } ``` Você pode fixar a um branch, tag ou commit específico: ```json theme={null} { "name": "my-plugin", "source": { "source": "git-subdir", "url": "https://github.com/acme-corp/monorepo.git", "path": "tools/claude-plugin", "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } ``` O campo `url` também aceita atalho GitHub (`owner/repo`) ou URLs SSH (`git@github.com:owner/repo.git`). | Campo | Tipo | Descrição | | :----- | :----- | :------------------------------------------------------------------------------------------------------------------ | | `url` | string | Obrigatório. URL do repositório Git, atalho GitHub `owner/repo` ou URL SSH | | `path` | string | Obrigatório. Caminho do subdiretório dentro do repositório contendo o plugin (por exemplo, `"tools/claude-plugin"`) | | `ref` | string | Opcional. Branch ou tag Git (padrão é o branch padrão do repositório) | | `sha` | string | Opcional. SHA de commit git completo de 40 caracteres para fixar a uma versão exata |

Pacotes npm

Plugins distribuídos como pacotes npm são instalados usando `npm install`. Isso funciona com qualquer pacote no registro npm público ou um registro privado que sua equipe hospeda. ```json theme={null} { "name": "my-npm-plugin", "source": { "source": "npm", "package": "@acme/claude-plugin" } } ``` Para fixar a uma versão específica, adicione o campo `version`: ```json theme={null} { "name": "my-npm-plugin", "source": { "source": "npm", "package": "@acme/claude-plugin", "version": "2.1.0" } } ``` Para instalar de um registro privado ou interno, adicione o campo `registry`: ```json theme={null} { "name": "my-npm-plugin", "source": { "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0.0", "registry": "https://npm.example.com" } } ``` | Campo | Tipo | Descrição | | :--------- | :----- | :------------------------------------------------------------------------------------------------------ | | `package` | string | Obrigatório. Nome do pacote ou pacote com escopo (por exemplo, `@org/plugin`) | | `version` | string | Opcional. Versão ou intervalo de versão (por exemplo, `2.1.0`, `^2.0.0`, `~1.5.0`) | | `registry` | string | Opcional. URL de registro npm personalizado. Padrão é o registro npm do sistema (tipicamente npmjs.org) |

Entradas de plugin avançadas

Este exemplo mostra uma entrada de plugin usando muitos dos campos opcionais, incluindo caminhos personalizados para commands, agents, hooks e MCP servers: ```json theme={null} { "name": "enterprise-tools", "source": { "source": "github", "repo": "company/enterprise-plugin" }, "description": "Ferramentas de automação de fluxo de trabalho empresarial", "version": "2.1.0", "author": { "name": "Enterprise Team", "email": "enterprise@example.com" }, "homepage": "https://docs.example.com/plugins/enterprise-tools", "repository": "https://github.com/company/enterprise-plugin", "license": "MIT", "keywords": ["enterprise", "workflow", "automation"], "category": "productivity", "commands": [ "./commands/core/", "./commands/enterprise/", "./commands/experimental/preview.md" ], "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"], "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" } ] } ] }, "mcpServers": { "enterprise-db": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"] } }, "strict": false } ``` Coisas importantes a notar: * **`commands` e `agents`**: você pode especificar múltiplos diretórios ou arquivos individuais. Os caminhos são relativos à raiz do plugin. * **`${CLAUDE_PLUGIN_ROOT}`**: use esta variável em hooks e configurações de MCP server para referenciar arquivos dentro do diretório de instalação do plugin. Isso é necessário porque os plugins são copiados para um local de cache quando instalados. Para dependências ou estado que devem sobreviver a atualizações de plugin, use [`${CLAUDE_PLUGIN_DATA}`](/pt/plugins-reference#persistent-data-directory) em vez disso. * **`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. Por 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: ```json theme={null} "skills": ["./skills/", "./extra-skills/"] ``` Quando 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: ```json theme={null} "source": "./", "skills": ["./skills/code-review", "./skills/docs"] ``` Com 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.

Strict mode

O campo `strict` controla se `plugin.json` é a autoridade para definições de componentes (skills, agents, hooks, MCP servers, output styles). | Valor | Comportamento | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `true` (padrão) | `plugin.json` é a autoridade. A entrada de marketplace pode complementá-lo com componentes adicionais, e ambas as fontes são mescladas. | | `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. | **Quando usar cada modo:** * **`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. * **`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.

Hospedar e distribuir marketplaces

GitHub é a forma recomendada para hospedar e distribuir um marketplace: 1. **Criar um repositório**: configure um novo repositório para seu marketplace 2. **Adicionar arquivo de marketplace**: crie `.claude-plugin/marketplace.json` com suas definições de plugin 3. **Compartilhar com equipes**: os usuários adicionam seu marketplace com `/plugin marketplace add owner/repo` **Benefícios**: controle de versão integrado, rastreamento de problemas e recursos de colaboração em equipe.

Hospedar em outros serviços git

Qualquer serviço de hospedagem git funciona, como GitLab, Bitbucket e servidores auto-hospedados. Os usuários adicionam com a URL completa do repositório: ```shell theme={null} /plugin marketplace add https://gitlab.com/company/plugins.git ```

Repositórios privados

Claude Code suporta instalar plugins de repositórios privados. Para instalação manual e atualizações, 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. As atualizações automáticas em segundo plano são executadas na inicialização sem ajudantes de credencial, já que prompts interativos bloqueariam Claude Code de iniciar. Para habilitar atualizações automáticas para marketplaces privados, defina o token de autenticação apropriado em seu ambiente: | Provedor | Variáveis de ambiente | Notas | | :-------- | :--------------------------- | :--------------------------------------------- | | GitHub | `GITHUB_TOKEN` ou `GH_TOKEN` | Token de acesso pessoal ou token de GitHub App | | GitLab | `GITLAB_TOKEN` ou `GL_TOKEN` | Token de acesso pessoal ou token de projeto | | Bitbucket | `BITBUCKET_TOKEN` | Senha de app ou token de acesso ao repositório | Defina o token em sua configuração de shell (por exemplo, `.bashrc`, `.zshrc`) ou passe-o ao executar Claude Code: ```bash theme={null} export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx ``` Para ambientes CI/CD, configure o token como uma variável de ambiente secreta. GitHub Actions fornece automaticamente `GITHUB_TOKEN` para repositórios na mesma organização.

Testar localmente antes da distribuição

Teste seu marketplace localmente antes de compartilhar: ```shell theme={null} /plugin marketplace add ./my-marketplace /plugin install quality-review-plugin@my-plugins ``` Para a gama completa de comandos add (GitHub, URLs Git, caminhos locais, URLs remotas), veja [Adicionar marketplaces](/pt/discover-plugins#add-marketplaces).

Exigir marketplaces para sua equipe

Você pode configurar seu repositório para que os membros da equipe sejam automaticamente solicitados a instalar seu marketplace quando confiarem na pasta do projeto. Adicione seu marketplace a `.claude/settings.json`: ```json theme={null} { "extraKnownMarketplaces": { "company-tools": { "source": { "source": "github", "repo": "your-org/claude-plugins" } } } } ``` Você também pode especificar quais plugins devem ser habilitados por padrão: ```json theme={null} { "enabledPlugins": { "code-formatter@company-tools": true, "deployment-tools@company-tools": true } } ``` Para opções de configuração completas, veja [Plugin settings](/pt/settings#plugin-settings). 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.

Pré-popular plugins para containers

Para 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. Para 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. O diretório seed espelha a estrutura de `~/.claude/plugins`: ``` $CLAUDE_CODE_PLUGIN_SEED_DIR/ known_marketplaces.json marketplaces//... cache////... ``` Para 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. Para 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á: ```bash theme={null} CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins ``` Entã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. Na 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`. Detalhes de comportamento: * **Somente leitura**: o diretório seed nunca é escrito. As atualizações automáticas são desabilitadas para marketplaces seed já que git pull falharia em um sistema de arquivos somente leitura. * **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. * **Resolução de caminho**: Claude Code localiza conteúdo de marketplace sondando `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces//` 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. * **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. * **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.

Restrições de marketplace gerenciado

Para 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`](/pt/settings#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`](/pt/settings#available-settings). Quando `strictKnownMarketplaces` é configurado em configurações gerenciadas, o comportamento de restrição depende do valor: | Valor | Comportamento | | ------------------- | ------------------------------------------------------------------------------------------------- | | Indefinido (padrão) | Sem restrições. Os usuários podem adicionar qualquer marketplace | | Array vazio `[]` | Bloqueio completo. Os usuários não podem adicionar novos marketplaces | | Lista de fontes | Os usuários podem apenas adicionar marketplaces que correspondem exatamente à lista de permissões |

Configurações comuns

Desabilitar todas as adições de marketplace: ```json theme={null} { "strictKnownMarketplaces": [] } ``` Permitir apenas marketplaces específicos: ```json theme={null} { "strictKnownMarketplaces": [ { "source": "github", "repo": "acme-corp/approved-plugins" }, { "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }, { "source": "url", "url": "https://plugins.example.com/marketplace.json" } ] } ``` Permitir 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](/pt/github-enterprise-server#plugin-marketplaces-on-ghes) ou instâncias GitLab auto-hospedadas: ```json theme={null} { "strictKnownMarketplaces": [ { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" } ] } ``` Permitir marketplaces baseados em sistema de arquivos de um diretório específico usando correspondência de padrão regex no caminho: ```json theme={null} { "strictKnownMarketplaces": [ { "source": "pathPattern", "pathPattern": "^/opt/approved/" } ] } ``` Use `".*"` como `pathPattern` para permitir qualquer caminho de sistema de arquivos enquanto ainda controla fontes de rede com `hostPattern`. `strictKnownMarketplaces` restringe o que os usuários podem adicionar, mas não registra marketplaces por conta própria. Para tornar marketplaces permitidos disponíveis automaticamente sem usuários executarem `/plugin marketplace add`, combine com [`extraKnownMarketplaces`](/pt/settings#extraknownmarketplaces) no mesmo `managed-settings.json`. Veja [Usando ambos juntos](/pt/settings#strictknownmarketplaces).

Como as restrições funcionam

As 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`. A lista de permissões usa correspondência exata para a maioria dos tipos de fonte. Para um marketplace ser permitido, todos os campos especificados devem corresponder exatamente: * Para fontes GitHub: `repo` é obrigatório, e `ref` ou `path` também devem corresponder se especificados na lista de permissões * Para fontes de URL: a URL completa deve corresponder exatamente * Para fontes `hostPattern`: o host do marketplace é correspondido contra o padrão regex * Para fontes `pathPattern`: o caminho do sistema de arquivos do marketplace é correspondido contra o padrão regex A correspondência exata não normaliza URLs: uma barra à direita, sufixo `.git` ou forma `ssh://` versus `https://` são tratados 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 todas as formas correspondam. Como `strictKnownMarketplaces` é definido em [configurações gerenciadas](/pt/settings#settings-files), configurações individuais de usuários e projetos não podem substituir essas restrições. Para detalhes de configuração completos incluindo todos os tipos de fonte suportados e comparação com `extraKnownMarketplaces`, veja a [referência strictKnownMarketplaces](/pt/settings#strictknownmarketplaces).

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

As 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. Claude Code resolve a versão de um plugin a partir do primeiro destes que está definido: 1. `version` no `plugin.json` do plugin 2. `version` na entrada de marketplace do plugin 3. O SHA do commit git da fonte do plugin Para os tipos de fonte baseados em git `github`, `url`, `git-subdir` e caminhos relativos dentro de um marketplace hospedado em git, você pode omitir `version` inteiramente e cada novo commit é tratado como uma nova versão. Esta é a configuração mais simples para plugins internos ou em desenvolvimento ativo. Definir `version` fixa o plugin. Se `plugin.json` declara `"version": "1.0.0"`, fazer push de novos commits sem alterar essa string não faz nada para usuários existentes, porque Claude Code vê a mesma versão e mantém a cópia em cache. Aumente o campo em cada lançamento, ou omita-o para usar o SHA do commit. 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`.

Configurar canais de lançamento

Para 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 os dois marketplaces a diferentes grupos de usuários através de [configurações gerenciadas](/pt/settings#settings-files). 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.
Exemplo
```json theme={null} { "name": "stable-tools", "plugins": [ { "name": "code-formatter", "source": { "source": "github", "repo": "acme-corp/code-formatter", "ref": "stable" } } ] } ``` ```json theme={null} { "name": "latest-tools", "plugins": [ { "name": "code-formatter", "source": { "source": "github", "repo": "acme-corp/code-formatter", "ref": "latest" } } ] } ```
Atribuir canais a grupos de usuários
Atribua cada marketplace ao grupo de usuários apropriado através de configurações gerenciadas. Por exemplo, o grupo stable recebe: ```json theme={null} { "extraKnownMarketplaces": { "stable-tools": { "source": { "source": "github", "repo": "acme-corp/stable-tools" } } } } ``` O grupo early-access recebe `latest-tools` em vez disso: ```json theme={null} { "extraKnownMarketplaces": { "latest-tools": { "source": { "source": "github", "repo": "acme-corp/latest-tools" } } } } ```

Fixar versões de dependência

Um 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 [Restringir versões de dependência de plugin](/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.

Renomear ou remover um plugin

O `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. Se 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: ```json theme={null} { "name": "acme-tools", "owner": { "name": "Acme" }, "plugins": [ { "name": "code-formatter", "source": "./plugins/code-formatter" } ], "renames": { "formatter": "code-formatter", "legacy-linter": null } } ``` Quando um usuário inicia Claude Code com o nome antigo ainda em suas configurações, Claude Code segue o mapa `renames`: * 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. * Para uma entrada `null`, Claude Code descarta a chave antiga e o aviso relata que o plugin foi removido do marketplace. * 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. Trate `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`. Execute `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`. 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`. Versões anteriores de Claude Code ignoram o campo `renames` e relatam `plugin-not-found` para o nome antigo.

Validação e testes

Teste seu marketplace antes de compartilhar. Valide a sintaxe JSON do seu marketplace: ```bash theme={null} claude plugin validate . ``` Ou de dentro de Claude Code: ```shell theme={null} /plugin validate . ``` Adicione o marketplace para testes: ```shell theme={null} /plugin marketplace add ./path/to/marketplace ``` Instale um plugin de teste para verificar se tudo funciona: ```shell theme={null} /plugin install test-plugin@marketplace-name ``` Para fluxos de trabalho completos de testes de plugin, veja [Testar seus plugins localmente](/pt/plugins#test-your-plugins-locally). Para troubleshooting técnico, veja [Plugins reference](/pt/plugins-reference).

Gerenciar marketplaces a partir da CLI

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

Plugin marketplace add

Adicione um marketplace de um repositório GitHub, URL git, URL remota ou caminho local. ```bash theme={null} claude plugin marketplace add [options] ``` **Argumentos:** * ``: 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 Uma 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. **Opções:** | Opção | Descrição | Padrão | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----- | | `--scope ` | Onde declarar o marketplace: `user`, `project` ou `local`. Veja [Plugin installation scopes](/pt/plugins-reference#plugin-installation-scopes) | `user` | | `--sparse ` | Limitar checkout a diretórios específicos via git sparse-checkout. Útil para monorepos | | Adicione um marketplace do GitHub usando atalho `owner/repo`: ```bash theme={null} claude plugin marketplace add acme-corp/claude-plugins ``` Fixe a um branch ou tag específico com `@ref`: ```bash theme={null} claude plugin marketplace add acme-corp/claude-plugins@v2.0 ``` Adicione de uma URL git em um host não-GitHub: ```bash theme={null} claude plugin marketplace add https://gitlab.example.com/team/plugins.git ``` Adicione de uma URL remota que serve o arquivo `marketplace.json` diretamente: ```bash theme={null} claude plugin marketplace add https://example.com/marketplace.json ``` Adicione de um diretório local para testes: ```bash theme={null} claude plugin marketplace add ./my-marketplace ``` Declare o marketplace no escopo do projeto para que seja compartilhado com sua equipe via `.claude/settings.json`: ```bash theme={null} claude plugin marketplace add acme-corp/claude-plugins --scope project ``` Para um monorepo, limite o checkout aos diretórios que contêm conteúdo de plugin: ```bash theme={null} claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins ```

Plugin marketplace list

Liste todos os marketplaces configurados. ```bash theme={null} claude plugin marketplace list [options] ``` **Opções:** | Opção | Descrição | | :------- | :-------------- | | `--json` | Saída como JSON | Com `--json`, cada entrada inclui `name`, `source` 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.

Plugin marketplace remove

Remova um marketplace configurado. O alias `rm` também é aceito. ```bash theme={null} claude plugin marketplace remove [options] ``` **Argumentos:** * ``: 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` **Opções:** | Opção | Descrição | Padrão | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- | | `--scope ` | Restringir remoção a um único escopo de configurações: `user`, `project` ou `local`. Veja [Plugin installation scopes](/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) | 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.

Plugin marketplace update

Atualize marketplaces de suas fontes para recuperar novos plugins e mudanças de versão. ```bash theme={null} claude plugin marketplace update [name] ``` **Argumentos:** * `[name]`: nome do marketplace a atualizar, conforme mostrado por `claude plugin marketplace list`. Atualiza todos os marketplaces se omitido Tanto `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).

Troubleshooting

Marketplace não carregando

**Sintomas**: Não consegue adicionar marketplace ou ver plugins dele **Soluções**: * Verifique se a URL do marketplace é acessível * Verifique se `.claude-plugin/marketplace.json` existe no caminho especificado * Garanta que a sintaxe JSON é válida usando `claude plugin validate` ou `/plugin validate`. Para verificar o frontmatter de skill, agent e command, execute o comando contra cada diretório de plugin * Para repositórios privados, confirme que você tem permissões de acesso

Erros de validação de marketplace

Execute `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 →`. A partir de Claude Code v2.1.196, a passagem por entrada também: * inclui plugins cuja `source` é `.` * executa quando `marketplace.json` está fora de um diretório `.claude-plugin`, resolvendo fontes contra o próprio diretório do arquivo * relata os problemas de cada entrada mesmo quando outra parte do arquivo tem erros de schema Versões anteriores pulam plugins na raiz do marketplace e apenas descem de um `.claude-plugin/marketplace.json`. Para validar o `plugin.json` de um plugin individual e seus arquivos de skill, agent, command e hook, execute o comando contra o diretório do plugin em si, por exemplo `claude plugin validate ./plugins/my-plugin`. Erros comuns: | Erro | Causa | Solução | | :------------------------------------------------ | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | `File not found: .claude-plugin/marketplace.json` | Manifesto ausente | Crie `.claude-plugin/marketplace.json` com campos obrigatórios | | `Invalid JSON syntax: Unexpected token...` | Erro de sintaxe JSON em marketplace.json | Verifique vírgulas ausentes, vírgulas extras ou strings não citadas | | `Duplicate plugin name "x" found in marketplace` | Dois plugins compartilham o mesmo nome | Dê a cada plugin um valor `name` único | | `plugins[0].source: Path contains ".."` | Caminho de fonte contém `..` | Use caminhos relativos à raiz do marketplace sem `..`. Veja [Caminhos relativos](#relative-paths) | | `YAML frontmatter failed to parse: ...` | YAML inválido em um arquivo de skill, agent ou command | Corrija a sintaxe YAML no bloco frontmatter. Em tempo de execução este arquivo carrega sem metadados. Relatado apenas ao validar um diretório de plugin | | `Invalid JSON syntax: ...` (hooks.json) | `hooks/hooks.json` malformado | Corrija a sintaxe JSON. Um `hooks/hooks.json` malformado previne o plugin inteiro de carregar. Relatado apenas ao validar um diretório de plugin | **Avisos** (não bloqueadores): * `Marketplace has no plugins defined`: adicione pelo menos um plugin ao array `plugins` * `No marketplace description provided`: adicione uma `description` de nível superior para ajudar os usuários a entender seu marketplace * `Plugin name "x" is not kebab-case`: o nome do plugin contém letras maiúsculas, espaços ou caracteres especiais. 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.

Falhas de instalação de plugin

**Sintomas**: Marketplace aparece mas a instalação do plugin falha **Soluções**: * Verifique se as URLs de fonte do plugin são acessíveis * Verifique se os diretórios de plugin contêm arquivos obrigatórios * Para fontes GitHub, garanta que repositórios são públicos ou você tem acesso * Teste fontes de plugin manualmente clonando/baixando * 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

Falha de autenticação de repositório privado

**Sintomas**: Erros de autenticação ao instalar plugins de repositórios privados **Soluções**: Para instalação manual e atualizações: * Verifique se você está autenticado com seu provedor git (por exemplo, execute `gh auth status` para GitHub) * Verifique se seu ajudante de credencial está configurado corretamente: `git config --global credential.helper` * Tente clonar o repositório manualmente para verificar se suas credenciais funcionam Para atualizações automáticas em segundo plano: * Defina o token apropriado em seu ambiente: `echo $GITHUB_TOKEN` * Verifique se o token tem as permissões obrigatórias (acesso de leitura ao repositório) * Para GitHub, garanta que o token tem o escopo `repo` para repositórios privados * Para GitLab, garanta que o token tem pelo menos escopo `read_repository` * Verifique se o token não expirou

Atualizações de marketplace falham em ambientes offline

**Sintomas**: `git pull` do marketplace falha e Claude Code limpa o cache existente, causando plugins ficarem indisponíveis. **Causa**: Por padrão, quando um `git pull` falha, Claude Code remove o clone obsoleto e tenta re-clonar. Em ambientes offline ou airgapped, re-clonar falha da mesma forma, deixando o diretório de marketplace vazio. **Solução**: Defina `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` para manter o cache existente quando o pull falhar em vez de limpá-lo: ```bash theme={null} export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 ``` Com esta variável definida, Claude Code retém o clone obsoleto do marketplace em falha de `git pull` e continua usando o último estado conhecido como bom. Para 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.

Operações Git expiram

**Sintomas**: Instalação de plugin ou atualizações de marketplace falham com um erro de timeout como "Git clone timed out after 120s" ou "Git pull timed out after 120s". **Causa**: Claude Code usa um timeout de 120 segundos para todas as operações git, incluindo clonagem de repositórios de plugin e puxar atualizações de marketplace. Repositórios grandes ou conexões de rede lentas podem exceder este limite. **Solução**: Aumente o timeout usando a variável de ambiente `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. O valor está em milissegundos: ```bash theme={null} export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutos ```

Plugins com caminhos relativos falham em marketplaces baseados em URL

**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 erros "path not found". **Causa**: Marketplaces baseados em URL apenas baixam o próprio arquivo `marketplace.json`. Eles não baixam arquivos de plugin do servidor. Caminhos relativos na entrada de marketplace referenciam arquivos no servidor remoto que não foram baixados. **Soluções**: * **Use fontes externas**: Altere entradas de plugin para usar fontes GitHub, npm ou URL git em vez de caminhos relativos: ```json theme={null} { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } } ``` * **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.

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

**Sintomas**: Plugin instala mas referências a arquivos falham, especialmente arquivos fora do diretório do plugin **Causa**: Plugins são copiados para um diretório de cache em vez de serem usados no local. Caminhos que referenciam arquivos fora do diretório do plugin (como `../shared-utils`) não funcionarão porque esses arquivos não são copiados. **Soluções**: Veja [Plugin caching and file resolution](/pt/plugins-reference#plugin-caching-and-file-resolution) para workarounds incluindo symlinks e reestruturação de diretório. Para ferramentas de debugging adicionais e problemas comuns, veja [Debugging and development tools](/pt/plugins-reference#debugging-and-development-tools).

Veja também

* [Descobrir e instalar plugins pré-construídos](/pt/discover-plugins) - Instalando plugins de marketplaces existentes * [Plugins](/pt/plugins) - Criando seus próprios plugins * [Plugins reference](/pt/plugins-reference) - Especificações técnicas completas e esquemas * [Plugin settings](/pt/settings#plugin-settings) - Opções de configuração de plugin * [strictKnownMarketplaces reference](/pt/settings#strictknownmarketplaces) - Restrições de marketplace gerenciado