Criar e distribuir um marketplace de plugins

​

Visão geral

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.

​

Passo a passo: criar um marketplace local

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

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

​

Criar o arquivo de marketplace

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

​

Entradas de plugin

​

Campos obrigatórios

​

Campos de plugin opcionais

​

Fontes de plugin

​

Caminhos relativos

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

​

Repositórios GitHub

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

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

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

​

Subdiretórios Git

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

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

​

Pacotes npm

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

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

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

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

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

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

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

​

Strict mode

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

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

​

Hospedar em outros serviços git

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

​

Repositórios privados

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

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

​

Testar localmente antes da distribuição

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

​

Exigir marketplaces para sua equipe

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

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

​

Pré-popular plugins para containers

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

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

• 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

​

Configurações comuns

{
  "strictKnownMarketplaces": []
}

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

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

​

Como as restrições funcionam

• 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

​

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

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

​

Configurar canais de lançamento

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

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

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

​

Fixar versões de dependência

​

Renomear ou remover um plugin

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

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

​

Validação e testes

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Gerenciar marketplaces a partir da CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

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

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

claude plugin marketplace add ./my-marketplace

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

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

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

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

​

Plugin marketplace update

claude plugin marketplace update [name]

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

​

Troubleshooting

​

Marketplace não carregando

• 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

• 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

• 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

• 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

• 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

• 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

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Operações Git expiram

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutos

​

Plugins com caminhos relativos falham em marketplaces baseados em URL

• 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

​

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