Criar e distribuir um marketplace de plugins

​

Visão geral

1. Criar plugins: construir um ou mais plugins com commands, 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).

​

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

​

Criar o arquivo de marketplace

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

​

Campos obrigatórios

​

Campos do proprietário

​

Metadados 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": "[email protected]"
  },
  "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. 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 Modo strict abaixo.

​

Modo strict

• strict: true: o plugin tem seu próprio plugin.json e gerencia seus próprios componentes. A entrada de marketplace pode adicionar commands 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 commands, 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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Testar localmente antes da distribuição

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

​

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

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

​

Configurar canais de lançamento

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

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

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

​

Validação e testes

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

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 e o frontmatter está bem formado usando claude plugin validate ou /plugin validate
• Para repositórios privados, confirme que você tem permissões de acesso

​

Erros de validação de marketplace

• Marketplace has no plugins defined: adicione pelo menos um plugin ao array plugins
• No marketplace description provided: adicione metadata.description 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

​

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

• 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

​

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