Hospedar e manter um marketplace

​

Host your marketplace

​

Register the marketplace for everyone in a repository

​

Avoid relative-path entries in a URL-hosted marketplace

​

Edit plugins in place on a shared directory

​

Keep plugin files out of Git LFS

​

Share files within a marketplace with symlinks

• Dentro do próprio diretório do plugin: o symlink é preservado como um symlink relativo no cache, para que continue resolvendo para o alvo copiado em tempo de execução.
• Em outro lugar dentro do mesmo marketplace: o symlink é desreferenciado. O conteúdo do alvo é copiado para o cache em seu lugar. Isso permite que o diretório skills/ de um meta-plugin vincule a skills definidas por outros plugins no marketplace.
• Fora do marketplace: o symlink é ignorado por segurança.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Distribute through organization settings

• Repositório de marketplace: em github.com e gitlab.com, deve ser privado ou interno
• Plugin sources: cada plugin source deve ser do tipo github, url ou git-subdir, ou um relative path que comece com ./
• Diretório bin/ de nível superior: claude.ai rejeita um plugin que tem um e sincroniza o resto do marketplace. A mensagem de erro começa com Plugin contains a top-level bin/ directory. Mantenha executáveis em outro diretório, como scripts/, e referencie-os como ${CLAUDE_PLUGIN_ROOT}/scripts/<name> a partir de seus hooks ou configurações de servidor MCP

​

Grant access to a private marketplace

• GitHub owner/repo: Claude Code testa ssh -T git@github.com e clona sobre SSH quando o teste é bem-sucedido. Se o teste falhar ou o próprio clone SSH falhar, ele clona sobre HTTPS. Os usuários em máquinas sem uma chave SSH do GitHub podem definir CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 para pular o teste e clonar sobre HTTPS.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

• SSH: a chave deve funcionar sem um prompt de passphrase, por exemplo porque está carregada em ssh-agent. O host já deve estar em known_hosts.
• HTTPS: Claude Code deixa o helper de credencial git do usuário ativado, mas proíbe-o de solicitar. Uma credencial que o helper já armazena funciona; uma que ele teria que pedir falha. No GitHub, gh auth login seguido de gh auth setup-git armazena uma.

​

Serve users who have no git-host account

• archive: um zip baixado sobre HTTPS. Os usuários não precisam de git nem de uma conta, apenas acesso de rede à URL. Requer Claude Code v2.1.224 ou posterior. Fixe cada archive com sha256 para que Claude Code recuse um download alterado. Para enviar credenciais com o download, veja Authenticate archive downloads.
• Um repositório git público: Claude Code clona um source url ou git-subdir público sobre HTTPS sem credenciais quando a entrada fornece uma URL https://. Para um source github ou um source git-subdir escrito como owner/repo, os usuários sem uma chave SSH do GitHub definem CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

​

What background auto-update does with credentials

• Remotes SSH: uma chave carregada em ssh-agent autentica a verificação.
• Remotes HTTPS com uma credencial armazenada: um helper que pode fornecer uma credencial armazenada sem solicitar autentica a verificação. Git Credential Manager, o helper Keychain do macOS e git-credential-store funcionam dessa forma uma vez que mantêm uma credencial para o host.
• Remotes HTTPS com um helper que precisa solicitar: o helper não pode responder em segundo plano. A atualização falha silenciosamente e o checkout existente permanece no lugar, para que os plugins do usuário continuem funcionando a partir do último estado sincronizado.

• O checkout está atualizado: Claude Code o deixa como está.
• A verificação encontra novos commits ou falha porque não consegue alcançar ou autenticar para o remoto: Claude Code clona o marketplace novamente e substitui o checkout existente pelo novo clone. Se esse clone falhar, o checkout existente permanece no lugar. O re-clone pode time out on large repositories.

• Armazenar uma credencial: faça login no helper de credencial primeiro para que ele mantenha uma credencial para o host. Para GitHub, execute gh auth login, depois gh auth setup-git.
• Manter o checkout em falha: se o usuário definir CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code mantém o checkout existente sem tentar o re-clone quando a verificação de fundo não consegue alcançar ou autenticar para o remoto. Os plugins continuam funcionando a partir do último estado sincronizado.

​

Roll out to a whole company

• Entry sources que não precisam de conta git: Serve users who have no git-host account
• Um diretório de plugins pré-preenchido: Seed containers and CI, que também serve usuários que não têm conta de host git
• Configurações de organização claude.ai: Distribute through organization settings, onde as credenciais git dos seus usuários não estão envolvidas

​

Keep users up to date

​

Turn on auto-update

• Diga aos usuários para ativá-lo: cada usuário vai para Marketplaces em /plugin, seleciona seu marketplace e seleciona Enable auto-update.
• Peça a um administrador para defini-lo: se um administrador definir "autoUpdate": true na entrada extraKnownMarketplaces do seu marketplace em configurações gerenciadas, está ativado para todos que recebem essas configurações. Veja Set update policy.

​

Release a new version

• Bump version em cada lançamento: os usuários permanecem em sua cópia em cache até a string mudar. Se você definir "version": "1.0.0" e fazer push de novos commits sem alterá-lo, os usuários não os recebem.
• Omita version: os usuários rastreiam seus commits em vez disso. Deixe version fora de plugin.json e da entrada do marketplace.

​

Hold users on one version

• ref e sha na entrada do plugin: ref nomeia uma branch ou tag e sha nomeia um commit para um source github, url ou git-subdir. Veja Plugin sources.
• #<ref> no comando add: os usuários que adicionam your-org/your-marketplace#stable obtêm essa branch ou tag do catálogo. Para duas linhas de lançamento ao mesmo tempo, veja Run release channels.
• Tags <plugin>--v<version>: um intervalo de versão de uma dependência se resolve contra essas tags. Veja Release a plugin that others depend on.

​

Change the command of a command source

• Sem mais execuções de fundo: a once-per-session run do comando para para esse usuário, então a nova saída da ferramenta não os alcança.
• Uma entrada na aba Errors do /plugin: a entrada mostra o novo comando e o comando claude plugin update para executar.

​

Run release channels

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

Rename or remove a plugin

​

Migrate users with a renames map

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Entrada renomeada: o plugin carrega sob seu novo nome. claude plugin list e os detalhes do plugin em /plugin mostram Renamed to "code-formatter" in the "your-marketplace" marketplace uma vez, e Claude Code reescreve a chave antiga para a nova em enabledPlugins e pluginConfigs nos escopos de configurações do usuário, projeto e local.
• Entrada null: a chave antiga é removida desses escopos e o usuário vê Removed from the "your-marketplace" marketplace.
• Ativado em configurações gerenciadas: o plugin ainda carrega sob seu novo nome, mas Claude Code não pode reescrever configurações gerenciadas, então o aviso recorre até que um administrador atualize enabledPlugins lá.

​

Uninstall removed plugins from users’ machines

1. Compara o que os usuários instalaram a partir de seu marketplace contra as entradas e o mapa renames, e trata qualquer plugin que não esteja listado nem renomeado como removido.
2. Desinstala cada plugin removido do usuário, projeto e escopos locais. Os plugins que apenas configurações gerenciadas instalaram permanecem no lugar.
3. Lista cada plugin removido em um cabeçalho Flagged em /plugin com o status Removed from marketplace.

​

Authenticate archive downloads

• O source url do marketplace: o source url que você registrou o marketplace a partir de, como uma entrada extraKnownMarketplaces.
• A entrada do plugin: em Claude Code v2.1.238 ou posterior, você pode defini-lo na entrada marketplace.json do plugin em vez disso, ao lado de source.

​

Add a headersHelper to a plugin entry

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

Write the headersHelper command

• Texto do comando: no máximo 500 caracteres de ASCII imprimível, sem uma sequência de quatro ou mais espaços.
• Saída: imprima um objeto JSON de nomes de headers e valores de string em stdout, depois saia com 0 dentro de 10 segundos.
• Shell e diretório de trabalho: Claude Code executa o comando através de sh ou através de cmd.exe no Windows. O diretório de trabalho é o diretório de configuração, que é ~/.claude ou CLAUDE_CONFIG_DIR. Dê um caminho absoluto ou um comando em PATH, porque um caminho relativo se resolve contra esse diretório, não o projeto do usuário.
• Variáveis que Claude Code remove: quando o comando é definido em uma entrada marketplace.json ou no .claude/settings.json ou .claude/settings.local.json de um projeto, Claude Code remove do ambiente cada variável cujo nome parece uma credencial, pela mesma regra que aplica a um headersHelper MCP. ANTHROPIC_API_KEY e MY_REGISTRY_TOKEN são ambos removidos, então tenha o comando ler sua credencial de um arquivo ou um armazenamento de credenciais. Esta remoção não se aplica a um comando definido em configurações de usuário, um arquivo --settings ou configurações gerenciadas.
• Variáveis que Claude Code define: CLAUDE_CODE_MARKETPLACE_URL e CLAUDE_CODE_MARKETPLACE_NAME para o comando de um source url, e CLAUDE_CODE_PLUGIN_NAME e CLAUDE_CODE_PLUGIN_ARCHIVE_URL para o comando de uma entrada. CLAUDE_CODE_MARKETPLACE_NAME não está definido na primeira busca depois que um usuário adiciona um marketplace por URL, porque essa busca é o que fornece o nome.

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

When Claude Code skips a headersHelper command or drops its output

• Comando falha: se o comando sair com não-zero, executar por mais de 10 segundos ou imprimir qualquer coisa que não seja um objeto JSON de valores de string, a busca ou download para o qual o comando foi executado não acontece.
• URL do marketplace não começa com https://: o comando desse source url não é executado e as solicitações carregam apenas os headers listados em seu campo headers.
• Redirecionamento deixa a origem: quando um download é redirecionado para fora da origem da URL do archive, a solicitação redirecionada não carrega valores de headers de nenhum source url do marketplace ou entrada de plugin.
• Entrada define um header de roteamento ou identidade: Claude Code descarta nomes de roteamento de solicitação e identidade de cliente como Host, Cookie e X-Forwarded-* de headers de uma entrada e saída de comando, e mantém nomes de autenticação como Authorization. Cada entrada marketplace.json é filtrada dessa forma. Para uma entrada de plugin inline em configurações, veja extraKnownMarketplaces.
• Comando definido em configurações de um diretório --add-dir: o comando é ignorado, em um source url e em uma entrada de plugin inline igualmente, e apenas os headers desse arquivo são enviados.
• Configurações gerenciadas bloqueiam o comando: definir disableCommandPluginSources para true bloqueia comandos headersHelper, e allowManagedHooksOnly também os bloqueia a menos que disableCommandPluginSources seja explicitamente false. Sob um desses bloqueios, Claude Code ainda executa o comando para um marketplace que as próprias configurações gerenciadas declaram.

​

How users accept a headersHelper command

​

Installs and updates that refuse a command instead of asking

• Instalando vários plugins ao mesmo tempo, a partir de uma sugestão de plugin ou como dependência de outro plugin: Claude Code recusa o plugin que tem o comando e direciona o usuário para a própria visualização desse plugin em /plugin. Os outros plugins em uma instalação em massa ainda instalam. Um plugin que depende do plugin recusado falha em instalar até que o usuário instale o plugin recusado por conta própria.
• Background auto-update ou início de sessão para um plugin cujo archive nunca foi baixado: Claude Code lista o plugin na aba Errors do /plugin para que o usuário saiba instalá-lo ou atualizá-lo por conta própria.

​

When a marketplace url source’s command runs

​

Depend on and recommend other plugins

• Intervalos de versão: uma dependência pode carregar um intervalo semver.
• Dependências entre marketplaces: uma dependência de outro marketplace instala apenas quando seu marketplace lista esse marketplace em allowCrossMarketplaceDependenciesOn.

​

Work around what a marketplace can’t do

• Restringir o que mais os usuários instalam: a lista de permissões do marketplace é uma configuração gerenciada, strictKnownMarketplaces. Veja Restrict what users can install.
• Instalar ou ativar um plugin sem o usuário pedir: nenhum campo de entrada instala um plugin. enabledPlugins gerenciado faz isso para uma frota; veja Pre-install and require plugins.
• Mostrar entradas diferentes para usuários diferentes: as entradas não carregam campo de audiência, e cada usuário que adiciona o marketplace vê o catálogo inteiro. Hospede marketplaces separados para audiências separadas.
• Marcar um plugin como descontinuado: não há estado de descontinuação. A opção é remover a entrada, mapear seu nome para null em renames e opcionalmente definir forceRemoveDeletedPlugins.
• Ativar auto-update para seus usuários: cada usuário o ativa em Marketplaces em /plugin ou um administrador define autoUpdate em configurações gerenciadas. Veja Turn on auto-update.
• Carregar credenciais git: nenhum campo de marketplace mantém um token git. O acesso a um marketplace ou plugin hospedado em git segue a configuração git do usuário, por Grant access to a private marketplace. Para sources archive, uma entrada pode definir headers ou headersHelper em vez disso.

​

Next steps

• Marketplace reference: campos marketplace.json, tipos de source e mensagens de validação
• Manage plugins for your organization: exija, restrinja ou semeie seu marketplace nas máquinas da sua organização
• Plugin dependencies: marque lançamentos para que plugins que dependem do seu possam resolver versões
• Troubleshoot plugins: os erros que seus usuários veem ao adicionar ou atualizar a partir de seu marketplace