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 liste 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/review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/skills/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": "review-plugin",
  "description": "Adiciona uma skill /review para revisões rápidas de código",
  "version": "1.0.0"
}

{
  "name": "my-plugins",
  "owner": {
    "name": "Seu Nome"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Adiciona uma skill /review para revisões rápidas de código"
    }
  ]
}

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

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

​

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 servidor MCP 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.
• strict: false: Como isso está definido como falso, o plugin não precisa de seu próprio plugin.json. A entrada do marketplace define tudo.

​

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

​

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

​

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

​

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 seja válida usando claude plugin validate ou /plugin validate
• Para repositórios privados, confirme que você tem permissões de acesso

​

Erros de validação do 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 "x" uses npm source which is not yet fully implemented: use fontes github ou caminhos locais

​

Falhas de instalação de plugin

• Verifique se as URLs de origem do plugin são acessíveis
• Verifique se os diretórios de plugin contêm arquivos obrigatórios
• Para fontes GitHub, garanta que os repositórios sejam públicos ou você tenha 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 auxiliar 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 necessárias (acesso de leitura ao repositório)
• Para GitHub, garanta que o token tenha o escopo repo para repositórios privados
• Para GitLab, garanta que o token tenha pelo menos escopo read_repository
• Verifique se o token não expirou

​

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

  Perguntar à IA

  { "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
• Referência de plugins - Especificações técnicas completas e esquemas
• Plugin settings - Opções de configuração de plugin
• Referência strictKnownMarketplaces - Restrições de marketplace gerenciado