Plugins do Claude Code: instalar, verificar e remover

Um plugin reúne instruções ou ferramentas que você quer levar entre projetos. Para testar a instalação, comece com um pacote próprio: uma única skill, chamada explicitamente, que devolve um marcador conhecido. Não é preciso confiar em hooks de um pacote desconhecido.

O exemplo usa macOS/Linux com o Claude Code instalado e configurado. No Windows, crie os mesmos JSON e Markdown no editor; os comandos de shell usam Bash ou Zsh. A resposta do modelo exige conexão funcional. A validação da estrutura é independente.

Crie os três arquivos

Em um diretório novo e vazio:

mkdir -p plugin-lab/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/skills/ping

Salve o manifesto em plugin-lab/plugins/load-check/.claude-plugin/plugin.json:

{
  "name": "load-check",
  "version": "1.0.0",
  "description": "Local plugin loading exercise"
}

Em plugin-lab/plugins/load-check/skills/ping/SKILL.md:

---
description: Return a marker to verify this local plugin is loaded.
disable-model-invocation: true
---

Return exactly PLUGIN_READY. Do not use tools or change files.

Em plugin-lab/.claude-plugin/marketplace.json:

{
  "name": "local-load-lab",
  "owner": {"name": "Local developer"},
  "plugins": [
    {"name": "load-check", "source": "./plugins/load-check"}
  ]
}

O marketplace aponta para o pacote. Dentro dele, .claude-plugin contém o manifesto; skills fica ao lado. Colocar skills dentro de .claude-plugin contraria a estrutura documentada.

Valide e instale

No diretório inicial, execute:

claude --version
claude plugin validate ./plugin-lab/plugins/load-check
claude plugin validate ./plugin-lab
claude

Se houver erro de validação, corrija o arquivo indicado. Uma estrutura válida não comprova a qualidade das instruções nem a segurança de qualquer plugin.

Na sessão do Claude Code:

/plugin marketplace add ./plugin-lab
/plugin install load-check@local-load-lab

Escolha Local no painel de instalação para limitar o teste ao projeto atual. Leia onde a configuração será gravada antes de confirmar. Se o resumo pedir uma recarga, execute /reload-plugins. A sequência consta no guia de marketplaces.

Confira a skill carregada

/plugin list
/load-check:ping

O primeiro comando deve listar o pacote instalado; o segundo deve devolver PLUGIN_READY. O nome completo /load-check:ping inclui o plugin e diferencia a skill de outra com o mesmo nome.

Confira também o diretório de trabalho: a skill não deve alterar arquivos. A frase que proíbe ferramentas é uma instrução ao modelo, não uma barreira de permissões do sistema. Use as permissões do Claude Code para controlar o acesso.

Se o comando não aparecer, confira, nesta ordem, o nome no manifesto, a localização de skills/ping/SKILL.md, o escopo, o estado enabled e a necessidade de recarga. Teste separadamente o marketplace e a inicialização com --plugin-dir.

Desative, atualize e remova

claude plugin disable load-check@local-load-lab --scope local
claude plugin enable load-check@local-load-lab --scope local
claude plugin update load-check@local-load-lab --scope local
claude plugin uninstall load-check@local-load-lab --scope local

Execute um comando por vez no mesmo projeto e confira cada resultado. --scope local corresponde ao escopo escolhido; sem ele, update e uninstall usam user por padrão. Reinicie após atualizar se o CLI pedir. Depois de desativar ou remover, abra outra sessão e confirme que a skill sumiu. Depois de ativar, repita o teste.

Para testar uma mudança, altere o marcador na skill de origem e aumente a versão do pacote. Depois atualize o marketplace e o plugin instalado conforme as instruções de gerenciamento. A edição do arquivo original pode não alterar uma cópia instalada em cache.

Antes de instalar um pacote de terceiros

Examine o conteúdo. Uma skill de texto, um hook de shell e um servidor MCP têm consequências distintas. Revise comandos, endereços de serviços externos e instruções que peçam segredos. Não dê permissões extras apenas para eliminar uma mensagem de erro.

No projeto real, repita o ciclo: escopo conhecido, componente visível, ação esperada, inspeção dos arquivos e um jeito claro de desativar. Consulte a referência de plugins para o formato completo e os recursos do validador.