Mercados de plugins - Claude Docs

Mercados de plugins são catálogos de plugins disponíveis que facilitam a descoberta, instalação e gerenciamento de extensões do Claude Code. Este guia mostra como usar mercados existentes e criar o seu próprio para distribuição em equipe.

Visão geral

Um mercado é um arquivo JSON que lista plugins disponíveis e descreve onde encontrá-los. Os mercados fornecem:

Descoberta centralizada: Navegue por plugins de múltiplas fontes em um só lugar
Gerenciamento de versões: Rastreie e atualize versões de plugins automaticamente
Distribuição em equipe: Compartilhe plugins necessários em sua organização
Fontes flexíveis: Suporte para repositórios git, repositórios GitHub, caminhos locais e gerenciadores de pacotes

Pré-requisitos

Claude Code instalado e em execução
Familiaridade básica com formato de arquivo JSON
Para criar mercados: Repositório Git ou ambiente de desenvolvimento local

Adicionar e usar mercados

Adicione mercados usando os comandos /plugin marketplace para acessar plugins de diferentes fontes:

Adicionar mercados do GitHub

Adicionar um repositório GitHub contendo .claude-plugin/marketplace.json

/plugin marketplace add owner/repo

Adicionar repositórios Git

Adicionar qualquer repositório git

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

Adicionar mercados locais para desenvolvimento

Adicionar diretório local contendo .claude-plugin/marketplace.json

/plugin marketplace add ./my-marketplace

Adicionar caminho direto para arquivo marketplace.json

/plugin marketplace add ./path/to/marketplace.json

Adicionar marketplace.json remoto via URL

/plugin marketplace add https://url.of/marketplace.json

Instalar plugins de mercados

Depois de adicionar mercados, instale plugins diretamente:

Instalar de qualquer mercado conhecido

/plugin install plugin-name@marketplace-name

Navegar plugins disponíveis interativamente

/plugin

Verificar instalação do mercado

Após adicionar um mercado:

Listar mercados: Execute /plugin marketplace list para confirmar que foi adicionado
Navegar plugins: Use /plugin para ver plugins disponíveis do seu mercado
Testar instalação: Tente instalar um plugin para verificar se o mercado funciona corretamente

Configurar mercados de equipe

Configure a instalação automática de mercados para projetos de equipe especificando mercados necessários em .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  }
}

Quando membros da equipe confiam na pasta do repositório, o Claude Code instala automaticamente esses mercados e quaisquer plugins especificados no campo enabledPlugins.

Crie seu próprio mercado

Construa e distribua coleções de plugins personalizadas para sua equipe ou comunidade.

Pré-requisitos para criação de mercado

Repositório Git (GitHub, GitLab ou outro hospedagem git)
Compreensão do formato de arquivo JSON
Um ou mais plugins para distribuir

Criar o arquivo do mercado

Crie .claude-plugin/marketplace.json na raiz do seu repositório:

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "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 do mercado

Campos obrigatórios

Campo	Tipo	Descrição
`name`	string	Identificador do mercado (kebab-case, sem espaços)
`owner`	object	Informações do mantenedor do mercado
`plugins`	array	Lista de plugins disponíveis

Metadados opcionais

Campo	Tipo	Descrição
`metadata.description`	string	Breve descrição do mercado
`metadata.version`	string	Versão do mercado
`metadata.pluginRoot`	string	Caminho base para fontes de plugins relativos

Entradas de plugins

Entradas de plugins são baseadas no esquema de manifesto de plugin (com todos os campos tornados opcionais) mais campos específicos do mercado (source, category, tags, strict), com name sendo obrigatório.

Campos obrigatórios:

Campo	Tipo	Descrição
`name`	string	Identificador do plugin (kebab-case, sem espaços)
`source`	string\|object	De onde buscar o plugin

Campos opcionais do plugin

Campos de metadados padrão:

Campo	Tipo	Descrição
`description`	string	Breve descrição do plugin
`version`	string	Versão do plugin
`author`	object	Informações do autor do plugin
`homepage`	string	Homepage do plugin ou URL de documentação
`repository`	string	URL do repositório de código fonte
`license`	string	Identificador de licença SPDX (ex: MIT, Apache-2.0)
`keywords`	array	Tags para descoberta e categorização de plugins
`category`	string	Categoria do plugin para organização
`tags`	array	Tags para pesquisabilidade
`strict`	boolean	Exigir plugin.json na pasta do plugin (padrão: true) ¹

Campos de configuração de componentes:

Campo	Tipo	Descrição
`commands`	string\|array	Caminhos personalizados para arquivos ou diretórios de comandos
`agents`	string\|array	Caminhos personalizados para arquivos de agentes
`hooks`	string\|object	Configuração de hooks personalizados ou caminho para arquivo de hooks
`mcpServers`	string\|object	Configurações de servidor MCP ou caminho para configuração MCP

^{1 - Quando strict: true (padrão), o plugin deve incluir um arquivo de manifesto plugin.json, e os campos do mercado complementam esses valores. Quando strict: false, o plugin.json é opcional. Se estiver ausente, a entrada do mercado serve como o manifesto completo do plugin.}

Fontes de plugins

Caminhos relativos

Para plugins no mesmo repositório:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Repositórios GitHub

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

Repositórios Git

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

Entradas de plugins avançadas

Entradas de plugins podem sobrescrever localizações padrão de componentes e fornecer metadados adicionais. Note que ${CLAUDE_PLUGIN_ROOT} é uma variável de ambiente que resolve para o diretório de instalação do plugin (para detalhes veja Variáveis de ambiente):

{
  "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": "[email protected]"
  },
  "homepage": "https://docs.company.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
}

Relacionamento de esquema: Entradas de plugins usam o esquema de manifesto de plugin com todos os campos tornados opcionais, mais campos específicos do mercado (source, strict, category, tags). Isso significa que qualquer campo válido em um arquivo plugin.json também pode ser usado em uma entrada de mercado. Quando strict: false, a entrada do mercado serve como o manifesto completo do plugin se nenhum plugin.json existir. Quando strict: true (padrão), os campos do mercado complementam o arquivo de manifesto próprio do plugin.

Hospedar e distribuir mercados

Escolha a melhor estratégia de hospedagem para suas necessidades de distribuição de plugins.

Hospedar no GitHub (recomendado)

O GitHub fornece o método de distribuição mais fácil:

Criar um repositório: Configure um novo repositório para seu mercado
Adicionar arquivo do mercado: Crie .claude-plugin/marketplace.json com suas definições de plugins
Compartilhar com equipes: Membros da equipe adicionam 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 para distribuição de mercado, usando uma URL para um repositório git arbitrário. Por exemplo, usando GitLab:

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

Usar mercados locais para desenvolvimento

Teste seu mercado localmente antes da distribuição:

Adicionar mercado local para teste

/plugin marketplace add ./my-local-marketplace

Testar instalação de plugin

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

Gerenciar operações de mercado

Listar mercados conhecidos

Listar todos os mercados configurados

/plugin marketplace list

Mostra todos os mercados configurados com suas fontes e status.

Atualizar metadados do mercado

/plugin marketplace update marketplace-name

Atualiza listagens de plugins e metadados da fonte do mercado.

Remover um mercado

/plugin marketplace remove marketplace-name

Remove o mercado da sua configuração.

Remover um mercado desinstalará quaisquer plugins que você instalou dele.

Solução de problemas de mercados

Problemas comuns de mercados

Mercado não carregando

Sintomas: Não consegue adicionar mercado ou ver plugins dele Soluções:

Verifique se a URL do mercado está acessível
Confirme que .claude-plugin/marketplace.json existe no caminho especificado
Garanta que a sintaxe JSON é válida usando claude plugin validate
Para repositórios privados, confirme que você tem permissões de acesso

Falhas na instalação de plugins

Sintomas: Mercado aparece mas a instalação do plugin falha Soluções:

Verifique se as URLs de fonte do plugin estão acessíveis
Confirme que os diretórios do plugin contêm arquivos necessários
Para fontes GitHub, garanta que os repositórios são públicos ou você tem acesso
Teste fontes de plugins manualmente clonando/baixando

Validação e teste

Teste seu mercado antes de compartilhar:

Validar sintaxe JSON do mercado

claude plugin validate .

Adicionar mercado para teste

/plugin marketplace add ./path/to/marketplace

Instalar plugin de teste

/plugin install test-plugin@marketplace-name

Para fluxos de trabalho completos de teste de plugins, veja Teste seus plugins localmente. Para solução de problemas técnicos, veja Referência de plugins.

Próximos passos

Para usuários de mercados

Descobrir mercados da comunidade: Pesquise no GitHub por coleções de plugins do Claude Code
Contribuir com feedback: Relate problemas e sugira melhorias aos mantenedores de mercados
Compartilhar mercados úteis: Ajude sua equipe a descobrir coleções valiosas de plugins

Para criadores de mercados

Construir coleções de plugins: Crie mercados temáticos em torno de casos de uso específicos
Estabelecer versionamento: Implemente políticas claras de versionamento e atualização
Engajamento da comunidade: Colete feedback e mantenha comunidades ativas de mercados
Documentação: Forneça arquivos README claros explicando o conteúdo do seu mercado

Para organizações

Mercados privados: Configure mercados internos para ferramentas proprietárias
Políticas de governança: Estabeleça diretrizes para aprovação de plugins e revisão de segurança
Recursos de treinamento: Ajude equipes a descobrir e adotar plugins úteis efetivamente

Veja também

Plugins - Instalando e usando plugins
Referência de plugins - Especificações técnicas completas e esquemas
Desenvolvimento de plugins - Criando seus próprios plugins
Configurações - Opções de configuração de plugins

Começando

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

​Visão geral

​Pré-requisitos

​Adicionar e usar mercados

​Adicionar mercados do GitHub

​Adicionar repositórios Git

​Adicionar mercados locais para desenvolvimento

​Instalar plugins de mercados

​Verificar instalação do mercado

​Configurar mercados de equipe

​Crie seu próprio mercado

​Pré-requisitos para criação de mercado

​Criar o arquivo do mercado

​Esquema do mercado

​Campos obrigatórios

​Metadados opcionais

​Entradas de plugins

​Campos opcionais do plugin

​Fontes de plugins

​Caminhos relativos

​Repositórios GitHub

​Repositórios Git

​Entradas de plugins avançadas

​Hospedar e distribuir mercados

​Hospedar no GitHub (recomendado)

​Hospedar em outros serviços git

​Usar mercados locais para desenvolvimento

​Gerenciar operações de mercado

​Listar mercados conhecidos

​Atualizar metadados do mercado

​Remover um mercado

​Solução de problemas de mercados

​Problemas comuns de mercados

​Mercado não carregando

​Falhas na instalação de plugins

​Validação e teste

​Próximos passos

​Para usuários de mercados

​Para criadores de mercados

​Para organizações

​Veja também

Visão geral

Pré-requisitos

Adicionar e usar mercados

Adicionar mercados do GitHub

Adicionar repositórios Git

Adicionar mercados locais para desenvolvimento

Instalar plugins de mercados

Verificar instalação do mercado

Configurar mercados de equipe

Crie seu próprio mercado

Pré-requisitos para criação de mercado

Criar o arquivo do mercado

Esquema do mercado

Campos obrigatórios

Metadados opcionais

Entradas de plugins

Campos opcionais do plugin

Fontes de plugins

Caminhos relativos

Repositórios GitHub

Repositórios Git

Entradas de plugins avançadas

Hospedar e distribuir mercados

Hospedar no GitHub (recomendado)

Hospedar em outros serviços git

Usar mercados locais para desenvolvimento

Gerenciar operações de mercado

Listar mercados conhecidos

Atualizar metadados do mercado

Remover um mercado

Solução de problemas de mercados

Problemas comuns de mercados

Mercado não carregando

Falhas na instalação de plugins

Validação e teste

Próximos passos

Para usuários de mercados

Para criadores de mercados

Para organizações

Veja também