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 (repositórios git, caminhos locais e muito mais). 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 um 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
disable-model-invocation: true
---

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

{
"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 source (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, hooks, etc.), além destes campos específicos do marketplace: source, category, tags e strict.

Campos obrigatórios

Campos de plugin opcionais

Campos de metadados padrão:

Campos de configuração de componentes:

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.

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, então 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.

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.

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

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.
• ${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} 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, e quaisquer caminhos listados sob skills adicionam a essa varredura. A exceção é uma fonte de raiz de marketplace como source: "./", onde várias entradas de plugin compartilham uma pasta skills/. Nesse caso, listar subdiretórios específicos sob skills torna essa lista o conjunto completo para a entrada, e outros diretórios sob skills/ não são carregados. Listar o próprio diretório skills/ 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 fornece o método de distribuição mais fácil:

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

Defina o token em sua configuração de shell (por exemplo, .bashrc, .zshrc) ou passe-o ao executar Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Testar localmente antes da distribuição

Teste seu marketplace localmente antes de compartilhar:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

Para a gama completa de comandos add (GitHub, URLs Git, caminhos locais, URLs remotas), veja Adicionar 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:

{
  "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 o primeiro seed que contém um determinado marketplace ou cache de plugin vence.

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.

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:

{
  "strictKnownMarketplaces": []
}

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

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

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.

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.

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 grupo de usuários apropriado através de configurações gerenciadas. 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.

Validação e testes

Teste seu marketplace antes de compartilhar.

Valide a sintaxe JSON do seu marketplace:

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

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

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. 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 apenas marketplace.json: schema, nomes de plugin duplicados, travessia de caminho de fonte e incompatibilidades de versão contra cada plugin.json referenciado.

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:

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

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

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