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.

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 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.
3. Hospedar o marketplace: fazer push para GitHub, GitLab ou outro host git. Veja Hospedar e distribuir marketplaces.
4. Compartilhar com usuários: usuários adicionam seu marketplace com /plugin marketplace add e instalam plugins individuais. Veja Descobrir e instalar 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á.

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

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

{
"name": "quality-review-plugin",
"description": "Adiciona uma skill quality-review para revisões rápidas de código",
"version": "1.0.0",
"author": {
"name": "Seu Nome"
}
}

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

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

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

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 abaixo para todos os campos disponíveis.

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

Campos do proprietário

Campos opcionais

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, como description, version, author, commands e hooks, além destes campos específicos do marketplace: source, category, tags, strict, relevance, headers e headersHelper.

Campos obrigatórios

Campos de plugin opcionais

Campos de metadados padrão:

Tanto 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:

• Para um campo que você define na entrada, os usuários veem o valor da entrada, mesmo quando plugin.json define um diferente.
• Para um campo que a entrada deixa indefinido, os usuários veem o valor de plugin.json.

Antes da instalação, Claude Code pode ler plugin.json apenas para entradas com uma fonte de caminho relativo, 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.

Campos de configuração de componentes:

Campos de autenticação de arquivo:

Defina estes quando a entrada tiver uma archive source em um servidor que requer credenciais.

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.

Claude Code copia cada plugin instalado para o cache de plugin versionado local em ~/.claude/plugins/cache, exceto para uma fonte command em modo link, que Claude Code usa no lugar. Claude Code também instala as dependências de pacote Node.js elegíveis do plugin na cópia em cache.

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.

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

Caminhos relativos

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

{
  "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 <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.

Um nome simples é um único nome de diretório sem /, como "formatter". Para escrever nomes simples em vez de caminhos ./, defina metadata.pluginRoot 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.

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.

Repositórios GitHub

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

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

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Repositórios Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

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

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

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.

{
  "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:

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

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.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Para fixar a uma versão específica, adicione o campo version:

{
  "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:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Arquivos zip

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

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

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

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

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

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

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

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Se o arquivo baixado não corresponder ao pino, Claude Code recusa a instalação e relata Plugin archive integrity check failed.

As fontes de arquivo aceitam estes campos:

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

Autenticar downloads de arquivo

Para 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. No Claude Code v2.1.238 ou posterior, você pode defini-lo na entrada do plugin em vez disso, ao lado de source.

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

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

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

Adicionar um headersHelper a uma entrada de plugin

Esta 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, 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:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

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

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

Escrever o comando headersHelper

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

• Texto do comando: no máximo 500 caracteres de ASCII imprimível, sem execução de quatro ou mais espaços.
• 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.
• 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. 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.
• 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.
• 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.

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

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Quando Claude Code pula um comando headersHelper ou descarta sua saída

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

• 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.
• 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.
• 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.
• 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 dependendo de qual arquivo a declara.
• 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 igualmente, e envia apenas os headers desse arquivo.
• Configurações gerenciadas bloqueiam o comando: definir disableCommandPluginSources como true bloqueia comandos headersHelper, e 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.

Como usuários aceitam um comando headersHelper

Um 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. Em um shell não-interativo, passe --yes para aceitá-lo.

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

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

Em 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:

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

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

Um headersHelper de fonte url de marketplace é declarado em um arquivo de configurações, como uma entrada 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:

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

Para uma entrada de plugin inline 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.

Fontes de comando

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

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

{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

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

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

• 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/
• O diretório é aquele em que Claude Code foi iniciado, ou um de seus pais
• No Windows, o caminho é um caminho UNC

As fontes de comando aceitam estes campos:

Modo de cópia e modo de link

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

Defina "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 para um plugin em modo link, então imprima um diretório que já contém qualquer node_modules que o plugin precisa.

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

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

Como usuários aceitam o comando

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

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

Administradores podem bloquear fontes de comando em toda uma organização com a configuração gerenciada disableCommandPluginSources. Se uma organização definir allowManagedHooksOnly, Claude Code bloqueia fontes de comando por padrão.

Quando Claude Code re-executa o comando

O 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:

• Cada vez que o usuário instala ou atualiza o plugin
• 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 do marketplace
• Na inicialização ou em /reload-plugins, quando a versão instalada de um plugin habilitado está faltando do cache de plugin

Claude Code pula as duas execuções em segundo plano quando o usuário define CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Instalações e atualizações explícitas ainda executam o comando com essa variável definida.

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

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:

{
  "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 e devem permanecer dentro dela.
  • Claude Code rejeita um caminho que se resolve fora do diretório de plugin, como ./../shared.md, com um erro path escapes plugin directory, e ainda carrega o plugin sem esse componente
• ${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.
  • Veja a tabela de substituição para quais campos de configuração a substituem por tipo de servidor
  • Para dependências ou estado que devem sobreviver a atualizações de plugin, use ${CLAUDE_PLUGIN_DATA} 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 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:

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

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

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

Hospedar no GitHub (recomendado)

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:

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

Repositórios privados

Claude Code suporta instalar plugins de repositórios privados. Se você distribuir seu marketplace através de Organization 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 do Claude GitHub App ou do GitHub Enterprise App da sua organização, e uma fonte de plugin que não consegue autenticar deve ser pública. Veja Distribuir através de configurações de organização para as regras completas.

Comandos que você executa

Quando 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 para cloná-los via HTTPS em vez disso.

Atualizações automáticas em segundo plano

Por padrão, a atualização em segundo plano desabilita ajudantes de credencial git para seu git pull, então o pull não consegue autenticar em repositórios privados via HTTPS mesmo quando um ajudante está configurado. Remotos SSH não são afetados: uma chave carregada em ssh-agent autentica pulls em segundo plano da mesma forma que os comandos que você executa. Quando o pull em segundo plano falha, Claude Code volta a re-clonar o marketplace do zero. O re-clone usa suas credenciais git armazenadas, mas pode expirar em repositórios grandes, então atualizações automáticas de marketplace privado podem falhar intermitentemente.

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

• Defina CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para manter o clone existente quando o pull em segundo plano falha, em vez de deletar e re-clonar. Seus plugins continuam funcionando a partir do último estado sincronizado, e atualizações manuais com /plugin marketplace update ainda fazem pull com suas credenciais.
• Configure um ajudante de credencial git, por exemplo com gh auth setup-git para GitHub, para que o fallback de re-clone possa autenticar sem solicitar.

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

Para fazer o pull em segundo plano autenticar via HTTPS, configure uma reescrita de URL git global. A reescrita incorpora um token na URL remota, então tem efeito mesmo que o pull em segundo plano desabilite ajudantes de credencial, e um pull bem-sucedido pula o fallback de re-clone. O exemplo a seguir reescreve a URL do repositório de marketplace para incluir um token de acesso:

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

Escope a reescrita para o repositório de marketplace ou caminho de organização. Uma reescrita cuja base é apenas o host se aplica a cada fetch e push para esse host na máquina e substitui suas credenciais normais, incluindo pushes para seus próprios repositórios.

Cada provedor espera um nome de usuário diferente na URL reescrita, e o mesmo escopo de caminho se aplica a cada provedor. Para servidores auto-hospedados, substitua o nome do host pelo nome do host do seu servidor:

A reescrita armazena o token em texto simples em seu gitconfig, então use um token com acesso somente leitura ao repositório de marketplace.

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

Se você distribuir plugins através de Organization settings > Plugins em um plano Team ou Enterprise, estas regras de fonte se aplicam:

• O repositório de marketplace deve ser privado ou interno. A sincronização da organização o lê através do Claude GitHub App ou do GitHub Enterprise App da sua organização.
• Cada fonte de plugin deve ser do tipo github, url ou git-subdir, ou um caminho relativo 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.
• Uma fonte de plugin pode ser privada em dois casos:
  • Uma fonte github.com que compartilha o proprietário do repositório de marketplace
  • Uma fonte no host GitHub Enterprise da sua organização com o GHE App instalado no repositório
• A sincronização da organização busca todas as outras fontes sem credenciais, então repositórios github.com sob um proprietário diferente e repositórios em outros hosts, como GitLab ou Bitbucket, devem ser públicos.

Veja Manage plugins for your organization para o fluxo de trabalho do administrador.

Para incluir plugins privados, coloque as pastas de plugin dentro do repositório de marketplace e as referencie com um caminho relativo. 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.

Por exemplo, esta entrada de plugin marketplace.json referencia um plugin que você confirmou em plugins/deploy-tools no repositório de marketplace:

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

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

Nã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:

• 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.
• Upload direto: se você fizer upload do plugin em Organization settings > Plugins em vez disso, claude.ai rejeita o upload com a mesma mensagem.

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

Exigir marketplaces para sua equipe

Você 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, sem nenhum prompt separado. Adicione seu marketplace a .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

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

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Para opções de configuração completas, veja Plugin settings.

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/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

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á:

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/<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.
• 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 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. Para criar uma lista de permissões de quais plugins de marketplaces podem aparecer como sugestões de instalação contextual, defina pluginSuggestionMarketplaces.

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 de um marketplace permitido. Para bloquear fontes de comando também, defina disableCommandPluginSources.

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

Configurações comuns

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

{
  "strictKnownMarketplaces": []
}

Permitir 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:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

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

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

• Ambientes não-interativos que executam antes do primeiro lançamento interativo da máquina.
• 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.

Nessas máquinas, adicione o marketplace a extraKnownMarketplaces no mesmo managed-settings.json para que Claude Code o registre automaticamente, ou execute claude plugin marketplace add anthropics/claude-plugins-official.

Permitir apenas marketplaces específicos:

{
  "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 repositórios de marketplace sob uma organização GitHub com uma entrada owner-wildcard. Owner wildcards requerem Claude Code v2.1.223 ou posterior.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

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 ou instâncias GitLab auto-hospedadas:

{
  "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:

{
  "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.

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.

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

Quando um usuário adiciona uma URL de repositório https:// que Claude Code clona em vez de buscar, 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.

A 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:

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

Como strictKnownMarketplaces é definido em configurações gerenciadas, 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.

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. 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 para a ordem de resolução completa, incluindo fontes archive.

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 cada grupo de usuários seu próprio marketplace através de configurações gerenciadas de uma de duas formas:

• Implante configurações gerenciadas gerenciadas por endpoint separadas, como um arquivo de configurações gerenciadas ou um perfil MDM, para os dispositivos de cada grupo. Como Claude Code combina fontes gerenciadas diz se o arquivo por grupo ou perfil se aplica em um dispositivo que também tem uma fonte em toda a organização.
• Defina uma política de gateway de aplicativos Claude 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.

Configurações gerenciadas pelo servidor do console de administração se aplicam a todos os usuários em sua organização, então não conseguem carregar uma atribuição por grupo.

Exemplo

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Atribuir canais a grupos de usuários

Atribua 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. Por exemplo, o grupo stable recebe:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

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

{
  "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 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 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:

{
  "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.

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.

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

claude plugin validate .

Ou de dentro de Claude Code:

/plugin validate .

Adicione o marketplace para testes:

/plugin marketplace add ./path/to/marketplace

Instale um plugin de teste para verificar se tudo funciona:

/plugin install test-plugin@marketplace-name

Para fluxos de trabalho completos de testes de plugin, veja Testar seus plugins localmente. Para troubleshooting técnico, veja 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.

claude plugin marketplace add <source> [options]

Argumentos:

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

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:

Adicione um marketplace do GitHub usando atalho owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

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

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

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

Adicione de um diretório local para testes:

claude plugin marketplace add ./my-marketplace

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

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:

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

Plugin marketplace list

Liste todos os marketplaces configurados.

claude plugin marketplace list [options]

Opções:

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

Plugin marketplace remove

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

claude plugin marketplace remove <name> [options]

Argumentos:

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

Opções:

Plugin marketplace update

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

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.

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 . do diretório do marketplace. Para verificar o frontmatter de skill, agent e command, veja Validate a plugin or a directory without a manifest
• 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.

Do 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. A tabela abaixo lista os erros mais comuns de um diretório de marketplace, com a causa e correção para cada um:

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

Validate a plugin or a directory without a manifest

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

Pick the directory to name

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

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

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

• Nomeie aquele diretório skills para verificar o SKILL.md raiz do plugin.
• Nomeie o diretório do plugin para verificar o resto.

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

Check files behind symlinks

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

• Um diretório skills, agents ou commands vinculado sob a raiz do plugin ou .claude: Claude Code avisa que nada nele foi lido.
• 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.
• 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.

Em 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:

• Um plugin cujo diretório skills vincula aos skills de um plugin irmão: nomeie o diretório do plugin irmão.
• Uma entrada de skill vinculada 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.

Read the validation results

Uma execução limpa termina com Validation passed.

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.

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

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

Em 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 em plugin.json, Claude Code verifica que cada caminho existe mas não lê os arquivos lá.

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: git config --global credential.helper
• 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

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

• Por padrão, atualizações em segundo plano desabilitam ajudantes de credencial git para o pull, então o pull não consegue autenticar sobre HTTPS. Remotes SSH com uma chave carregada em ssh-agent ainda autenticam. Um pull falhado dispara uma re-clonagem do zero, que usa suas credenciais armazenadas mas pode expirar em repositórios grandes
• Defina CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para manter o clone existente quando o pull em segundo plano falhar
• Configure um ajudante de credencial git, por exemplo gh auth setup-git, então o fallback de re-clonagem consegue autenticar
• Se a re-clonagem expirar em um repositório grande, aumente o limite com CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configure uma reescrita de URL git escopo para o repositório de marketplace para que o pull em segundo plano autentique diretamente
• Ou atualize marketplaces privados manualmente com /plugin marketplace update <name>, que usa suas credenciais

Atualizações de marketplace falham em ambientes offline

Sintomas: git pull do marketplace falha em segundo plano e Claude Code tenta repetidamente uma re-clonagem que não consegue ter sucesso.

Causa: Por padrão, quando um git pull falha, Claude Code tenta uma re-clonagem do zero. Em ambientes offline ou airgapped, re-clonar falha da mesma forma, e a restauração do cache anterior depois é melhor esforço. A atualização é executada em segundo plano após a inicialização, então não atrasa a inicialização, mas cada sessão repete as tentativas falhadas e cada operação git pode esperar o timeout de 120 segundos.

Solução: Defina CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para pular a tentativa de re-clonagem e continuar usando o cache existente quando o pull falhar:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Para implantações totalmente offline onde o repositório nunca será alcançável, use CLAUDE_CODE_PLUGIN_SEED_DIR 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:

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

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.

Soluções:

• Use fontes externas: altere entradas de plugin para qualquer plugin source outro que não seja um caminho relativo:

  { "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, exceto para uma command source em link mode. 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.

Soluções: Veja 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.

Veja também

• Descobrir e instalar plugins pré-construídos - Instalando plugins de marketplaces existentes
• Plugins - Criando seus próprios plugins
• Plugins reference - Especificações técnicas completas e esquemas
• Plugin settings - Opções de configuração de plugin
• strictKnownMarketplaces reference - Restrições de marketplace gerenciado