Skip to main content
Use esta página quando um plugin não carregou, carregou uma cópia diferente da esperada, ou não pegou uma atualização, e você quer ver qual fonte, escopo de configurações ou arquivo em disco decidiu isso. Ela fornece as regras que Claude Code aplica quando uma sessão inicia e cada vez que você executa /reload-plugins. Você também pode pedir ao Claude para ler esta página e diagnosticar sua configuração.
Estes casos são cobertos em outras páginas:
Comece com Verificar qual estágio um plugin atingiu para os três estágios pelos quais um plugin instalado passa, ou vá para a seção que corresponde ao que você está vendo:

​
Verificar qual estágio um plugin atingiu

Uma entrada enabledPlugins se torna um plugin que você pode usar em estágios: suas configurações a declaram, Claude Code a busca para disco, e a sessão em execução a carrega. Quando um plugin não se comporta como um arquivo de configurações sugere, verifique qual estágio ele atingiu:
  • Declarado, em configurações: enabledPlugins diz quais plugins devem estar ligados, e extraKnownMarketplaces diz quais marketplaces devem existir. Quando você executa claude plugin marketplace add, Claude Code escreve o marketplace para extraKnownMarketplaces em suas configurações de usuário, bem como para disco
  • Buscado, em disco sob ~/.claude/plugins/: os registros do que Claude Code buscou, e os arquivos buscados em si:
    • known_marketplaces.json registra cada marketplace que Claude Code buscou, com sua source, installLocation, lastUpdated e autoUpdate. Há um known_marketplaces.json por usuário, então um marketplace que você adiciona em um projeto está disponível em cada projeto
    • installed_plugins.json registra cada instalação com seu scope, installPath e version
    • cache/ contém os arquivos do plugin
  • Carregado, na sessão em execução: o conjunto de plugins que Claude Code carregou na inicialização ou no último /reload-plugins. Mudanças em configurações ou em disco não chegam a esta camada até você executar /reload-plugins ou iniciar uma nova sessão. É por isso que claude plugin update termina com Restart to apply changes. e atualizações em segundo plano o solicitam com Run /reload-plugins to apply

​
Plugins e marketplaces que não estão em disco no início da sessão

Plugins carregam no início da sessão a partir de installed_plugins.json e do cache sem usar a rede. Após a sessão iniciar, Claude Code verifica os marketplaces declarados em segundo plano:
  • Um marketplace que configurações declaram mas known_marketplaces.json não tem: Claude Code o clona, depois recarrega plugins e baixa plugins habilitados que ainda não estão em cache
  • Um marketplace declarado cuja fonte mudou em configurações: Claude Code o busca novamente da nova fonte e mostra Plugins changed. Run /reload-plugins to activate.
Um plugin habilitado que nenhum caminho buscou e que não tem diretório de cache utilizável mostra Plugin "<name>" not cached at <path> na aba Errors do /plugin, e claude plugin list adiciona — run /plugin to refresh à mesma linha. Para a correção, veja Plugin "<name>" not cached at <path>.

​
Encontrar de onde um plugin veio

Todo plugin tem um id da forma <name>@<origin>, que é o que você vê em arquivos de configurações e em claude plugin list --json. A parte após @ diz onde Claude Code encontrou o plugin: Para um plugin de marketplace, <name> é o nome da entrada em marketplace.json; para @inline e @skills-dir é o name no manifesto do plugin. Os nomes de origem nesta tabela são reservados, então nenhum marketplace pode ser nomeado inline, skills-dir ou synced.

​
Nome da entrada e nome do manifesto

Um plugin de marketplace tem dois nomes, e eles podem diferir:
  • O nome da entrada em marketplace.json: a chave de instalação e habilitação. É o que você escreve em enabledPlugins, o que o diretório de cache é nomeado, e o que claude plugin list mostra
  • O name no manifesto: sob o qual os componentes do plugin são nomeados, e o que conflitos de nome comparam

​
Plugins compartilhados através de um repositório

Para compartilhar um plugin através de um repositório, liste-o sob enabledPlugins em .claude/settings.json ou coloque-o sob .claude/skills/. Claude Code não verifica o diretório .claude/plugins/ de um projeto. Uma sessão em nuvem não adiciona os marketplaces que um repositório lista sob extraKnownMarketplaces, porque isso requer o diálogo de confiança do workspace, que uma sessão em nuvem nunca mostra. Um plugin de diretório de skills com escopo de projeto carrega apenas a partir do .claude/skills/ do diretório de trabalho primário da sessão, e apenas depois que você aceita o diálogo de confiança do workspace para essa pasta. Ele não procura diretórios pai até a raiz do repositório da forma que skills e comandos simples fazem. Se você iniciar a partir de um subdiretório, um plugin na raiz do repositório não carrega. Inicie a partir da raiz do repositório em vez disso, ou mova a sessão para lá com /cd na v2.1.246 ou posterior. Um plugin com escopo de projeto é verificado no repositório e chega a cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de você, ele carrega apenas após a mesma verificação de confiança que se aplica às regras de permissão de projeto em .claude/settings.json. Confiar em uma pasta pai ou executar com -p não é suficiente. Componentes que executam código são ainda mais restritos:
  • Servidores MCP que ele declara passam pela mesma aprovação por servidor que um .mcp.json de projeto
  • Servidores MCP que ele declara como um pacote MCP, um arquivo .mcpb ou .dxt, ou de um arquivo fora do diretório do plugin são ignorados. Declare-os inline ou em um .mcp.json dentro do diretório do plugin
  • Monitores em segundo plano não carregam
Plugins com escopo pessoal não têm nenhuma dessas restrições. Para como escrever plugins --plugin-dir e de diretório de skills, veja Criar plugins.

​
Plugins sincronizados de claude.ai

Um plugin que você liga para sua conta claude.ai também carrega em Claude Code, ao lado dos plugins que você instala a partir de marketplaces. Isso inclui plugins que sua organização liga para seus membros. Cada um desses plugins carrega como <name>@synced, sem marketplace e sem registro de instalação. Em sessões de terminal, as skills, agentes, hooks, servidores MCP e servidores LSP de um plugin sincronizado todos carregam, com a mesma confiança que um plugin de marketplace que você instalou. Para os componentes que Cowork carrega, veja Plugins em claude.ai e em Cowork em claude.com. Plugins sincronizados carregam em sessões Cowork e em sessões de terminal onde você se conecta com sua conta claude.ai:
  • Cowork: Claude Code os baixa para o ambiente próprio da sessão quando a sessão inicia
  • Sessões de terminal: cada vez que você inicia Claude Code, ele sincroniza uma vez em segundo plano, baixando plugins novos e atualizados e removendo aqueles que você ou sua organização desligou. A sincronização em sessões de terminal requer Claude Code v2.1.273 ou posterior

​
Tempo de sincronização em sessões de terminal

Como a sincronização de terminal é executada em segundo plano, ela pode terminar após sua sessão ter iniciado. Quando ela adiciona, atualiza ou remove um plugin sincronizado em uma sessão interativa, você vê Plugins changed. Run /reload-plugins to activate. Execute /reload-plugins para carregar a mudança nessa sessão, ou deixe para a próxima vez que você iniciar Claude Code. Se você habilitar um plugin em claude.ai enquanto uma sessão está em execução, o plugin baixa na próxima vez que você iniciar Claude Code.

​
Requisitos de conexão para sincronização de terminal

Em seu terminal, plugins sincronizam apenas em sessões onde você se conecta com sua conta claude.ai. Se você se conectou em uma versão anterior de Claude Code, essa conexão não cobre plugins até Claude Code renová-la em segundo plano. Para obter acesso mais cedo, execute /login novamente. A sincronização de plugins então inicia na próxima vez que você iniciar Claude Code.

​
Controlar quais plugins sincronizados carregam

Você pode desligar plugins sincronizados um de cada vez, exceto um plugin que sua organização exige, ou desligar cada plugin sincronizado na máquina:
  • Um plugin: claude plugin disable <name>@synced em seu shell e a aba Installed do /plugin em uma sessão ambos salvam "<name>@synced": false em seu enabledPlugins de nível de usuário. Para manter o plugin fora de um projeto em cada ambiente, defina a mesma chave no .claude/settings.json comprometido do projeto
  • Cada plugin sincronizado em uma máquina: defina syncClaudeAiPlugins como false em suas configurações de usuário, ou sua organização o define em configurações gerenciadas. Claude Code para de baixar, e na próxima vez que você o inicia, ele move os plugins que já sincronizou para ~/.claude/plugins/.trash/ e não os carrega mais. Se sua organização desligar Skills em claude.ai, plugins param de sincronizar também
  • Um plugin que sua organização exige: um plugin que sua organização marca como obrigatório em claude.ai carrega mesmo se você o desabilitou anteriormente. claude plugin disable o recusa com Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it., e claude plugin list o marca required by your org
Para remover um plugin em claude.ai, veja Gerenciar plugins instalados.

​
Encontrar onde um plugin está habilitado

Você pode definir uma entrada enabledPlugins em qualquer uma de seis fontes. A tabela as lista de precedência mais baixa para mais alta, e quem cada uma se aplica. Para os próprios arquivos de configurações, veja Arquivos de configurações e quem eles afetam. Essas fontes se mesclam chave por chave. Para cada id de plugin, o valor que se aplica é o de fonte de precedência mais alta que menciona o id. Uma fonte que não menciona o id deixa o valor da fonte de precedência mais baixa em efeito.

​
Desabilitado em configurações de usuário mas ainda carrega

Se você definir um plugin como false em ~/.claude/settings.json e ele ainda carregar, um true em uma fonte de precedência mais alta o está substituindo. A linha do plugin em claude plugin list e em /plugin mostra Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting. A mensagem nomeia a fonte que o substituiu: project, project, gitignored para .claude/settings.local.json, cli flag ou managed. Para optar por não participar de um plugin habilitado por projeto em sua máquina, defina o id como false em .claude/settings.local.json, que tem precedência mais alta que o arquivo do projeto.

​
Habilitado em configurações de projeto mas não instalado

Quando o único true de um plugin está em .claude/settings.json do projeto, Claude Code não o busca para uma máquina onde ele não está instalado, a menos que sua entrada de marketplace tenha uma fonte de caminho relativo ou um diretório seed já o contenha. Em vez disso, a aba Errors do /plugin mostra Plugin "<name>" is enabled in project settings but isn't installed here. Um plugin de caminho relativo não precisa de registro de instalação porque carrega do próprio marketplace. Claude Code busca um plugin com uma fonte externa apenas quando uma dessas fontes o define como true:
  • Suas configurações de usuário
  • Um .claude/settings.local.json que git não rastreia
  • O sinalizador --settings
  • Configurações gerenciadas

​
Encontrar plugins em disco

Claude Code mantém arquivos de plugin e registros de estado sob uma raiz de plugins, que é ~/.claude/plugins a menos que você defina CLAUDE_CODE_PLUGIN_CACHE_DIR. Cada caminho na tabela é relativo a essa raiz. Como ${CLAUDE_PLUGIN_ROOT} aponta para um diretório de versão, o caminho raiz de um plugin muda a cada versão. Mantenha os arquivos duráveis de um plugin em ${CLAUDE_PLUGIN_DATA} em vez disso.

​
Plugins in-place e copiados

Claude Code carrega alguns plugins in-place de onde você os mantém e copia o resto para o cache, de acordo com sua origem:
  • Plugins --plugin-dir e de diretório de skills: o diretório carrega in-place e nunca é copiado. Um arquivo --plugin-url ou um .zip de --plugin-dir é extraído para um diretório temporário de sessão primeiro
  • Plugins de caminho relativo em um marketplace que você adicionou de um diretório local: o plugin carrega in-place de seu caminho dentro da pasta do marketplace. Suas edições no diretório de origem têm efeito no próximo início de sessão ou /reload-plugins, e você não precisa aumentar a versão. Os processos de hook do plugin e servidores MCP e LSP recebem um CLAUDE_PLUGIN_ROOT que aponta para o diretório de origem. Para suas dependências de pacote Node.js, veja Quando a instalação de dependência é executada
  • Plugins de fonte command em modo de link: o diretório que o comando imprimiu carrega in-place, através de links na entrada de cache
  • Cada outro plugin de marketplace: Claude Code copia o plugin para cache/<marketplace>/<plugin>/<version>/ na instalação e carrega essa cópia. Arquivos fora do diretório do plugin não são copiados, então quando um script dentro de um plugin copiado lê um caminho acima da raiz do plugin, como ../shared, ele não os encontra

​
Caminhos que escapam do diretório do plugin

Se um plugin carrega in-place ou de uma cópia em cache, Claude Code não deixa que ele declare componentes fora de seu próprio diretório. Ele rejeita um caminho de componente que se resolve fora da raiz do plugin, se o caminho é declarado em plugin.json ou em uma entrada de marketplace:
  • Um caminho que aponta para fora do plugin como escrito, como ../shared-utils
  • Um symlink que leva para fora do plugin, outro que links entre plugins dentro de um marketplace
  • Em macOS e Linux, um caminho que contém uma barra invertida em qualquer lugar nele, mesmo quando o caminho fica dentro do plugin. Componentes declarados com caminhos de barra invertida portanto carregam apenas em Windows, então escreva caminhos de componentes com barras normais, como ./commands/deploy.md
Um caminho rejeitado aparece como um erro path escapes plugin directory, e o plugin carrega sem esse componente.

​
Limpeza de versões anteriores

Quando você atualiza ou desinstala um plugin, Claude Code escreve um marcador .orphaned_at no diretório de versão anterior. Ele remove esse diretório em uma limpeza em segundo plano 14 dias depois, então uma sessão que já carregou a versão antiga continua em execução. A varredura é executada apenas enquanto installed_plugins.json registra pelo menos uma instalação. Depois que você desinstala seu último plugin, diretórios órfãos ficam até você instalar outro.

​
Dependências de pacote Node.js

Quando Claude Code copia um plugin para o cache, ele também instala as dependências de pacote Node.js do plugin lá, então os hooks e servidores MCP do plugin podem carregá-las. Esta seção cobre os pacotes npm e Bun que um plugin declara em seu próprio package.json. Para plugins que dependem de outros plugins, veja versões de dependência de plugin.

​
Quando a instalação de dependência é executada

Claude Code executa a instalação dentro do diretório de versão copiado cada vez que cria um:
  • Quando você instala um plugin
  • Quando Claude Code atualiza um plugin para uma nova versão
  • No início da sessão quando um plugin habilitado ainda não está em cache, como em uma máquina nova
Para um plugin de caminho relativo carregado in-place de um marketplace de diretório local, Claude Code não instala as dependências no diretório de origem. Instale-as lá você mesmo, ou de um hook para ${CLAUDE_PLUGIN_DATA}. A instalação é executada apenas quando o diretório raiz do plugin contém tanto um package.json quanto um lockfile suportado. O lockfile decide qual comando Claude Code executa: Se um plugin contém mais de um desses lockfiles, Claude Code usa a primeira correspondência, verificando em ordem: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json. Claude Code pula a instalação para lockfiles Yarn e pnpm e para um bunfig.toml ao lado do lockfile Bun:
  • Se seu plugin tem apenas um yarn.lock ou pnpm-lock.yaml, substitua-o por um lockfile npm
  • Se um bunfig.toml está no mesmo diretório que o lockfile Bun, remova o bunfig.toml, ou substitua o lockfile Bun por um lockfile npm
Inclua um lockfile npm para alcançar a maioria dos usuários. Claude Code executa o gerenciador de pacotes do lockfile correspondente do PATH do usuário e não tenta o outro lockfile em vez disso se esse gerenciador de pacotes está faltando. Para um plugin distribuído através de uma fonte npm, use npm-shrinkwrap.json, porque npm exclui package-lock.json de pacotes publicados.

​
Limites na instalação de dependência

Claude Code restringe essa instalação de dependência para que nenhum código do plugin ou seus pacotes seja executado durante ela, e limita quanto tempo ela pode levar:
  • Resolução congelada: Bun e npm instalam exatamente o que o lockfile fixa, e falham em vez de re-resolver versões quando package.json e o lockfile discordam
  • Sem scripts de ciclo de vida: --ignore-scripts mantém scripts preinstall, install e postinstall de serem executados, então dependências que constroem módulos nativos nesses scripts baixam mas não compilam durante essa instalação
  • Tempo limite de 60 segundos: Claude Code para uma instalação que é executada mais tempo e a trata como falha
Claude Code busca um plugin de fonte npm antes dessa instalação de dependência, e nenhum dos scripts de instalação próprios do pacote é executado durante a busca. Veja fonte de plugin npm. Você não pode desligar a instalação automática. Nenhuma configuração ou variável de ambiente a desabilita. Em redes restritas, veja os requisitos de acesso à rede para os hosts a permitir.

​
Quando a instalação de dependência falha ou é ignorada

Uma instalação falha ou ignorada nunca bloqueia o plugin, e cada caso deixa um sinal diferente:
  • Uma instalação falha, ou uma ignorada por causa de um lockfile Yarn ou pnpm ou um bunfig.toml, aparece como um aviso na saída claude --debug
  • Um plugin com um package.json e nenhum lockfile é ignorado sem uma entrada de log
  • Uma instalação com tempo limite pode deixar uma árvore node_modules parcial na cópia em cache
Quando a instalação automática não pode fornecer uma dependência, instale-a de um hook para o diretório de dados persistentes. Isso inclui pacotes que precisam de seus scripts de ciclo de vida para construir, dependências Python e plugins bloqueados com Yarn ou pnpm.

​
Versões e atualizações

Se o autor de um plugin empurrou novos commits e claude plugin update imprime <name> is already at the latest version (<version>)., a versão que Claude Code computa para o plugin é inalterada, então nada muda em disco. Claude Code computa uma versão para cada plugin que instala, e essa versão é como ele detecta uma atualização. claude plugin update e auto-atualização em segundo plano computam a versão novamente e pulam o plugin quando ela corresponde ao que installed_plugins.json registra. A versão também nomeia o diretório de cache do plugin. Um manifesto que fixa "version" é uma forma da versão computada ficar a mesma através de commits. Veja Como Claude Code computa a versão para a ordem de resolução. Um plugin carregado in-place de um marketplace de diretório local carrega seus arquivos de origem atuais em cada início de sessão, qualquer que seja sua string de versão. Para um plugin de um marketplace hospedado em claude.ai, a versão que claude.ai registra para o plugin é sua versão, e o version do manifesto não é lido.

​
Como Claude Code computa a versão

Para um marketplace que você adicionou por fonte, Claude Code escolhe a regra pelo tipo source da entrada de marketplace do plugin. A referência de marketplace lista os tipos de fonte. Para cada tipo de fonte nessa lista exceto command:
  1. O campo version no manifesto do plugin vem primeiro
  2. Então o campo version na entrada de marketplace do plugin
  3. Quando nenhum é definido, a versão vem do tipo de fonte:
Claude Code não tira a versão de um repositório que enclausura o caminho de instalação, como um ~/.claude gerenciado por git. Para uma fonte command, Claude Code sempre deriva a versão do que o comando produziu: um hash de 12 caracteres por si só, ou <manifest version>-<hash> quando o manifesto define um. A version da entrada de marketplace é ignorada para fontes de comando. Para o que o hash cobre, veja Modo de cópia e modo de link. Como o manifesto vem primeiro, um manifesto que fixa "version": "1.0.0" mantém cada usuário na cópia em cache até seu autor mudar a string, quantos commits eles empurrem. Para deixar usuários rastrearem commits em vez disso, deixe version fora tanto do manifesto quanto da entrada. Hospedar um marketplace cobre qual escolha se encaixa em qual configuração de lançamento.

​
Quando Claude Code atualiza um marketplace antes de uma instalação

Quando você instala um plugin, Claude Code o procura em sua cópia local do catálogo de marketplace. Você pode executar /plugin install em uma sessão ou claude plugin install em seu shell, e nomear o plugin com ou sem seu marketplace. A tabela mostra quais dessas combinações atualizam a cópia local. A atualização antes de uma instalação name@marketplace não depende da configuração de auto-atualização do marketplace ou de DISABLE_AUTOUPDATER. Quando a atualização falha, a instalação prossegue do catálogo em cache e claude plugin install relata marketplace not refreshed. Claude Code pula a atualização antes de uma instalação name@marketplace quando:
  • O marketplace foi adicionado de uma fonte local file ou directory, ou é definido inline em configurações com uma fonte settings
  • Um diretório seed fornece o marketplace
  • Claude Code atualizou o marketplace nos últimos 30 segundos
  • Você definiu CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
  • Configurações gerenciadas bloqueiam o marketplace, nesse caso Claude Code também recusa a instalação

​
Quando auto-atualização é executada

Em uma sessão interativa, depois que você envia sua primeira mensagem, Claude Code aguarda um atraso aleatório de até dez minutos. Ele então atualiza cada marketplace com auto-atualização ligada e atualiza os plugins instalados deles em disco. A sessão em execução mantém as versões que carregou, e você vê Plugin updated: <name> · Run /reload-plugins to apply. Se você recarrega ou não, as novas versões carregam no seu próximo lançamento.

​
Quais marketplaces e plugins auto-atualizam

Se um marketplace auto-atualiza segue o primeiro destes que é definido:
  1. autoUpdate em sua entrada extraKnownMarketplaces em um arquivo de configurações
  2. autoUpdate em sua entrada known_marketplaces.json, que o botão Enable auto-update sob /plugin Marketplaces escreve. Quando um arquivo de configurações também declara o marketplace sob extraKnownMarketplaces, o botão escreve autoUpdate para essa entrada de configurações também
  3. O padrão: ligado para marketplaces oficiais da Anthropic como claude-plugins-official, desligado para knowledge-work-plugins e first-party-plugins, ligado para marketplaces adicionados de claude.ai, e desligado para cada outro marketplace
Se você definir DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1 ou CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, a passagem inteira é desligada e o botão Enable auto-update é ocultado, a menos que você também defina FORCE_AUTOUPDATE_PLUGINS=1. A referência de variáveis de ambiente cobre o efeito mais amplo de cada variável. Auto-atualização também pula um plugin cuja entrada de marketplace declara um headersHelper. Instalações e atualizações que recusam um comando em vez de perguntar explica quando tal plugin aparece na aba Errors do /plugin e como você o atualiza de lá. Quando um plugin copiado atualiza no meio da sessão, comandos de hook, monitores, servidores MCP e servidores LSP continuam usando o caminho da versão anterior. Execute /reload-plugins para mudar hooks, servidores MCP e servidores LSP para o novo caminho. Monitores requerem reinicialização de sessão.

​
Quando uma fonte de comando é re-executada

Plugins com uma fonte command não esperam pela passagem de auto-atualização. O diretório impresso reflete o estado da ferramenta no momento em que o comando foi executado, então Claude Code executa o comando que você aceitou novamente nestes momentos:
  • Cada vez que você instala ou atualiza o plugin
  • Uma vez por sessão para cada plugin habilitado com fonte de comando, em segundo plano, pouco depois que a sessão inicia. Esta execução não depende da configuração de auto-atualização do marketplace ou de DISABLE_AUTOUPDATER
  • Na inicialização ou em /reload-plugins, quando a versão instalada de um plugin habilitado está faltando do cache de plugin
Claude Code pula as duas execuções em segundo plano quando você define CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Instalações e atualizações explícitas ainda executam o comando com essa variável definida. Quando a saída com hash do comando mudou, Claude Code instala o resultado como uma nova versão e o recarrega na sessão interativa em execução, mudando os mesmos componentes que /reload-plugins muda. Você vê uma notificação de que o plugin foi recarregado. Se recarregar in-place invalidaria o cache de prompt da sessão, Claude Code em vez disso o solicita a executar /reload-plugins, que avisa sobre o custo do cache e se aplica quando re-executado com --force.

​
Conflitos de nome

Quando plugins habilitados de diferentes origens compartilham um nome de manifesto, esta ordem decide qual carrega, de precedência mais alta para mais baixa:
  1. Um plugin cujo id aparece em configurações gerenciadas enabledPlugins, como true ou false. Uma cópia --plugin-dir cujo nome de manifesto corresponde à parte de nome do id não é carregada, e você vê --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings
  2. Um plugin --plugin-dir, --plugin-url ou CLAUDE_CODE_PLUGIN_DIRS habilitado. Ele substitui um plugin de marketplace instalado com o mesmo nome ou um plugin de diretório de skills:
    • Um plugin de marketplace instalado: substituído silenciosamente. claude plugin list ainda mostra a linha de marketplace como habilitada, porque essa linha reflete suas configurações. Apenas o log que Claude Code escreve sob ~/.claude/debug/ quando você inicia com --debug registra Plugin "<name>" from --plugin-dir overrides installed version
    • Um plugin de diretório de skills: substituído com uma linha de aba Errors do /plugin que lê Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence
  3. Um plugin de marketplace instalado. Um plugin de diretório de skills com o mesmo nome recebe a mesma linha Not loaded, nomeando o plugin instalado
  4. Um plugin de diretório de skills. Entre dois destes, a cópia sob ~/.claude/skills/ carrega e a cópia do .claude/skills/ do projeto é descartada, com uma linha que diz qual caminho a sombreou
  5. Um plugin sincronizado de claude.ai. Quando um plugin habilitado de qualquer outra origem corresponde a seu nome, Claude Code carrega esse plugin e relata a cópia sincronizada como não carregada. Para usar a cópia claude.ai em vez disso, desabilite sua própria cópia
Como a ordem compara nomes de manifesto, um plugin --plugin-dir nomeado hello-plugin substitui hello@example-marketplace quando o manifesto desse plugin também diz "name": "hello-plugin".

​
Manter um plugin de sessão única de carregar

Para manter um plugin --plugin-dir de sombrear qualquer coisa, ou desligá-lo quando um processo pai passa o sinalizador para você, defina seu id como false em qualquer arquivo de configurações. Para um plugin cujo nome de manifesto é hello-plugin, a entrada é "enabledPlugins": {"hello-plugin@inline": false}. Um plugin de sessão única desabilitado não sombra, então a cópia de marketplace ou diretório de skills carrega em vez disso.

​
Próximos passos