Skip to main content
Uma dependência de plugin é outro plugin do qual seu plugin depende, como um cujo servidor MCP ou skill ele chama. Cada dependência rastreia a versão mais recente que seu marketplace fornece, a menos que você declare uma restrição de versão, um intervalo de versão semântica como ^2.0 ou ~2.1.0 que você testou. Esta página é para autores de plugins que declaram dependências em plugin.json e para mantenedores de marketplace que marcam versões.
Estes casos são cobertos em outras páginas:
Para adicionar uma restrição, comece em Declare uma dependência com uma restrição de versão. Se você mantém um plugin do qual outros dependem, marque suas versões para que suas restrições possam ser resolvidas.

​
Declare dependências

Sem uma restrição de versão, uma dependência se move para cada nova versão que seu marketplace publica na próxima vez que os usuários atualizam. Se essa versão renomear uma ferramenta MCP que seu plugin chama, seu plugin quebra para todos que atualizam. Com uma restrição como ~2.1.0 em uma dependência de uma fonte baseada em git, os usuários que têm seu plugin instalado continuam recebendo patches 2.1.x da dependência e nunca se movem para 2.2. Para atualizar em seu próprio cronograma, teste contra uma versão mais recente e depois publique uma nova versão do seu plugin com uma restrição mais ampla.

​
Declare uma dependência com uma restrição de versão

Liste as dependências no array dependencies do plugin.json do seu plugin. O manifesto a seguir declara uma dependência sem versão e uma dependência com restrição:
.claude-plugin/plugin.json
Uma entrada pode ser uma string: apenas o nome do plugin, como "audit-logger" neste manifesto, ou "name@marketplace" para resolvê-lo em outro marketplace. Com uma string simples, seu plugin depende de qualquer versão que o marketplace desse plugin forneça. Para definir uma restrição de versão, use um objeto com estes campos, cada um uma string: Um intervalo não corresponde a versões de pré-lançamento como 2.0.0-beta.1 a menos que você opte por um sufixo de pré-lançamento como ^2.0.0-0.

​
Agrupe plugins para uma equipe

Para permitir que engenheiros instalem um conjunto curado de plugins com um comando, publique um plugin cujo manifesto contenha um name e um array dependencies. Um manifesto de plugin precisa apenas de name, portanto este é um plugin válido, e instalá-lo instala todas as dependências. Por exemplo, uma equipe de plataforma pode publicar bundles específicos de função em um marketplace interno para que engenheiros executem um claude plugin install em vez de instalar cada plugin separadamente:
.claude-plugin/plugin.json
Para adicionar um plugin ao conjunto padrão mais tarde, publique uma nova versão backend-standard com a dependência extra. Quando o marketplace não atualiza automaticamente por padrão, os engenheiros ativam a atualização automática para o marketplace ou atualizam manualmente:
  • Ativar atualização automática para o marketplace: a próxima atualização automática move o bundle para a nova versão e instala todas as dependências que ele adiciona.
  • Atualizar manualmente: execute claude plugin update backend-standard em um shell, depois /reload-plugins em uma sessão aberta para instalar as dependências recém-adicionadas.
Para as etapas do lado do engenheiro, veja Manter plugins atualizados. Para implantar um bundle para todos em uma organização, um administrador o adiciona a enabledPlugins nas configurações gerenciadas. Veja Pré-instalar e exigir plugins.

​
Depender de um plugin de outro marketplace

Por padrão, Claude Code não instala uma dependência de um marketplace diferente do próprio plugin declarante, a menos que o usuário já tenha essa dependência instalada e ativada no mesmo escopo. Este padrão impede que um marketplace instale silenciosamente plugins de uma fonte que o usuário não revisou. Para permitir a instalação, adicione o nome do marketplace de destino a allowCrossMarketplaceDependenciesOn no marketplace.json do marketplace raiz. O marketplace raiz é aquele que hospeda o plugin que o usuário está instalando. Apenas a lista de permissões do marketplace raiz se aplica. O seguinte marketplace.json permite que deploy-kit dependa de um plugin de your-shared-marketplace:
.claude-plugin/marketplace.json
Se allowCrossMarketplaceDependenciesOn estiver faltando ou não incluir o marketplace de destino, Claude Code não instala a dependência. Quando a dependência é declarada na entrada do marketplace, a própria instalação é recusada com uma mensagem que começa com Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist e nomeia o campo a definir. Quando é declarada em plugin.json, a instalação é concluída sem a dependência e seu plugin falha ao carregar. A verificação da lista de permissões não se aplica a uma dependência que já está ativada. Se um usuário instalar audit-logger de your-shared-marketplace primeiro, no mesmo escopo, deploy-kit então instala sem qualquer alteração na lista de permissões.

​
Teste um plugin e sua dependência localmente

Se você está desenvolvendo um plugin e o plugin do qual ele depende ao mesmo tempo, inicie Claude Code a partir do seu shell e carregue ambos com --plugin-dir:
A cópia local da dependência satisfaz a entrada de dependência do seu plugin, portanto você não precisa instalar a dependência de seu marketplace.
  • Sem version necessária: o plugin.json local também não precisa de uma version, porque uma restrição de versão não é verificada contra uma cópia local.
  • Entradas que nomeiam um marketplace: uma entrada que nomeia um marketplace também corresponde à cópia local no Claude Code v2.1.242 ou posterior.
Até você instalar a dependência de seu marketplace, seu plugin para de carregar sempre que a cópia local é desativada ou ausente:
  • Você desativou a cópia local: seu plugin é desativado no próximo carregamento de plugin, com um erro que termina com is disabled — enable it or remove the dependency. Quando o erro nomeia a dependência como <name>@inline, esse identificador se refere à cópia --plugin-dir.
  • Você iniciou uma sessão sem a flag --plugin-dir da dependência: o erro relata a dependência como não instalada. Passe a flag novamente ou instale a dependência de seu marketplace.
Quando ambos os plugins estão em uma pasta pai, você pode passar essa pasta para --plugin-dir uma vez. Se a pasta não for ela mesma um plugin, Claude Code carrega cada pasta filha que tem um .claude-plugin/plugin.json. Requer Claude Code v2.1.265 ou posterior.

​
Libere um plugin do qual outros dependem

Se você mantém um plugin do qual outros plugins dependem com uma restrição de versão, marque suas versões para que essas restrições possam ser resolvidas. Uma restrição é resolvida contra tags git no repositório que hospeda o plugin. Marque o repositório que a fonte do plugin do plugin em marketplace.json aponta:
  • Fonte github, url, ou git-subdir: o repositório do próprio plugin, portanto o autor do plugin cria as tags
  • Caminho relativo como ./plugins/secrets-vault: o repositório do marketplace, portanto o mantenedor do marketplace cria as tags

​
Crie uma tag de versão

Marque cada versão como <plugin-name>--v<version>, onde <version> corresponde ao campo version no plugin.json desse commit. O prefixo plugin-name permite que um repositório de marketplace hospede vários plugins com históricos de versão independentes. Crie a tag a partir do diretório do plugin, com um remote origin configurado para receber a tag enviada, usando claude plugin tag:
O comando constrói o nome da tag a partir do manifesto do plugin. Antes de criar a tag, ele executa estas verificações:
  • Valida o plugin
  • Verifica se plugin.json e a entrada do marketplace concordam sobre a versão, quando o diretório do plugin está dentro de um checkout de marketplace
  • Requer uma árvore de trabalho limpa sob o diretório do plugin
  • Recusa se a tag já existe
Uma execução bem-sucedida imprime Created tag secrets-vault--v2.1.0. Com --push, também imprime Pushed to origin. Sem --push, imprime o comando git push para você executar. Passe --dry-run para ver o plano sem criar nada. A referência claude plugin tag lista as flags restantes. Você também pode executar git tag secrets-vault--v2.1.0 diretamente, desde que mantenha a version em plugin.json e na entrada do marketplace em sincronização você mesmo.

​
Restrinja uma dependência que tem uma fonte não-git

A resolução baseada em tag se aplica apenas a fontes baseadas em git. Para uma dependência com uma fonte de plugin npm, archive, ou command, a restrição não controla qual versão é buscada. Ainda é verificada quando o plugin carrega, e o plugin dependente é desativado se a versão instalada não a satisfaz. Para fontes npm, archive, e command, a versão verificada é a version no plugin.json da dependência. Defina uma lá antes de restringir essa dependência, porque um plugin.json que não define versão satisfaz nenhuma restrição. Claude Code nunca instala uma dependência com uma fonte command em si, portanto os usuários a instalam primeiro. Também nunca executa o headersHelper de uma dependência, portanto os usuários também instalam uma dependência cuja entrada de marketplace define um antes de instalar seu plugin. Além de claude plugin install, estas operações também instalam qualquer dependência declarada faltante, e os limites command e headersHelper se aplicam a elas também:
  • /reload-plugins
  • Auto-atualização do marketplace do plugin dependente
  • Re-executar claude plugin install no plugin dependente
  • claude plugin marketplace add

​
Como as dependências se comportam para seus usuários

Estas seções descrevem como Claude Code resolve, verifica e combina as restrições que você declara uma vez que seu plugin é instalado junto com outros.

​
Como uma restrição é resolvida contra tags

Quando um usuário instala um plugin que declara { "name": "secrets-vault", "version": "~2.1.0" }, a dependência instala a partir da tag secrets-vault--v mais alta que satisfaz ~2.1.0 no repositório que hospeda secrets-vault. Quando nenhuma tag satisfaz o intervalo, a instalação falha ou usa a cópia atual do marketplace:
  • Plugin com seu próprio repositório: a instalação falha com uma mensagem contendo Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
  • Plugin referenciado por um caminho relativo: a instalação usa a cópia atual do marketplace em vez disso, e a restrição é verificada quando o plugin carrega. Se essa cópia estiver fora do intervalo, o plugin dependente permanece desativado e claude plugin list mostra Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.
Para um plugin que o marketplace referencia por um caminho relativo, um marketplace que você adicionou como um caminho de pasta local também resolve restrições contra as tags git dessa pasta, quando a pasta é um repositório git. Isto requer Claude Code v2.1.196 ou posterior. Uma pasta local que não é um repositório git não tem tags, portanto Claude Code instala a dependência a partir do conteúdo atual da pasta em vez disso.

​
Confirme a versão resolvida

Para confirmar qual versão uma restrição foi resolvida, execute claude plugin list em seu shell. Uma dependência resolvida por tag mostra sua versão com um sufixo de commit de 12 caracteres, como 2.1.0-8713c5b11005. As verificações de restrição usam a versão da tag em vez da version em plugin.json, mesmo se plugin.json nesse commit ficar para trás. Se você forçar a movimentação de uma tag para um commit diferente, a próxima instalação busca o conteúdo desse commit em vez de reutilizar uma cópia em cache obsoleta. Veja Versões e atualizações para como a versão de um plugin se torna sua chave de cache.

​
Combine restrições de vários plugins

Quando vários plugins instalados restringem a mesma dependência, a dependência é resolvida para a versão mais alta que satisfaz todos os seus intervalos. Combinações comuns são resolvidas assim: A atualização automática busca uma dependência restrita na tag git mais alta que satisfaz o intervalo de cada plugin instalado, em vez de na versão mais recente do marketplace. Se os intervalos dos plugins instalados não se sobrepõem, a atualização automática deixa essa dependência em sua versão atual, e a aba Errors do /plugin mostra uma entrada nomeando o plugin restritivo. Se eles se sobrepõem mas nenhuma tag cai no intervalo, a atualização automática busca a cópia atual do marketplace e pula a atualização quando a version dessa cópia cai fora do intervalo de qualquer plugin instalado. Quando um usuário desinstala o último plugin que restringe uma dependência, a dependência não é mais restrita a um intervalo de versão e retoma o rastreamento de sua entrada de marketplace na próxima atualização.

​
Veja também