Manual de Referência de Plugins: Empacotando Sua Configuração para Distribuição

📚 Navegação da Série: O capítulo anterior 37 Pontos de Controle (Checkpoints) ensinou você a "salvar e restaurar" sessões, revertendo alterações de código para pontos seguros. Este capítulo eleva o nível — enquanto o Capítulo 24 ensinou a "usar plugins de terceiros", este capítulo ensina a "criar seus próprios plugins": como estruturar diretórios, a função de cada campo no plugin.json, quais componentes podem ser empacotados, como gerenciar dependências e como criar um marketplace para distribuir soluções para o time. Este é o guia de referência aprofundado para plugins.

Ao executar claude plugin details para um plugin, a saída costuma exibir métricas importantes: este plugin consome cerca de ~180 tokens por sessão de forma permanente, e suas duas skills consomem adicionais ~2400 e ~1800 tokens respectivamente quando acionadas.

Mesmo parecendo pequeno e inofensivo, um plugin consome recursos de contexto apenas por estar ativo na sessão. Compreender essa estrutura ajuda a perceber que: um plugin não é uma caixa preta — ele é composto por categorias de componentes bem definidas, com consumo, localização e gatilhos documentados. Dominar essa anatomia é essencial para criar plugins limpos e eficientes.

No Capítulo 24, passamos pela jornada de uso de plugins de terceiros: adicionar marketplaces, instalar plugins, atualizar com /reload-plugins e validar a confiança. Este capítulo não repetirá esses pontos, focando na arquitetura interna, desenvolvimento e publicação de plugins. O Capítulo 24 ensinou a dirigir; este ensinará a desmontar o motor e construir seu próprio veículo.

Por ser um guia de referência, o conteúdo possui alta densidade de especificações. Não há necessidade de decorar tudo de imediato; siga as instruções para criar seu primeiro plugin prático, use-o localmente e consulte as tabelas de referência conforme necessário ao longo do desenvolvimento.

Ao ler este capítulo, você obterá:

• A estrutura padrão de diretórios de um plugin e por que a pasta .claude-plugin/ deve conter exclusivamente o arquivo plugin.json.
• A lista de campos do manifesto plugin.json: dados obrigatórios, metadados, caminhos de componentes, configurações de usuário e dependências, compilados em tabelas.
• O local apropriado e as restrições para cada componente empacotável (skills, comandos, agentes, hooks, servidores MCP, LSP e monitores).
• A importância das variáveis de ambiente de caminhos como ${CLAUDE_PLUGIN_ROOT} e os riscos de ignorá-las.
• O fluxo completo de criação, teste local, criação de marketplace e distribuição de plugins para o time com exemplos de comandos e saídas esperadas.
• Soluções para os dois desafios comuns de publicação: versionamento de cache e gerenciamento de dependências.

---

01 Estrutura Padrão de um Plugin: Organizando Diretórios

No Capítulo 24, vimos a forma mais simples de um plugin — o arquivo plugin.json acompanhado de pastas de componentes. Para criar um plugin profissional, é importante organizar a estrutura de diretórios para evitar problemas de carregamento.

Regra de diretório: um plugin é uma pasta contendo um arquivo de manifesto que define sua identidade, com os componentes distribuídos em pastas filhas na raiz do projeto.

Analogia: Um conjunto de peças de Lego. A caixa do brinquedo contém duas partes principais — o manual de montagem, que descreve o nome do conjunto e as peças inclusas, e os compartimentos internos organizados, separando blocos por tipo (rodas em um compartimento, janelas em outro). A estrutura do plugin segue essa lógica: o arquivo plugin.json funciona como o manual, e as pastas skills/, agents/ e hooks/ funcionam como os compartimentos. O manual tem sua pasta dedicada, enquanto os compartimentos de peças ficam acessíveis na raiz.

A estrutura padrão de pastas de um plugin completo é apresentada a seguir (com foco nos componentes principais):

my-plugin/
├── .claude-plugin/           # Diretório de metadados
│   └── plugin.json           # Manifesto (manual) — apenas este arquivo fica aqui
├── skills/                   # Skills, cada uma em <nome>/SKILL.md
│   └── code-reviewer/
│       └── SKILL.md
├── commands/                 # Versão simplificada em markdown de Skills (legado)
│   └── status.md
├── agents/                   # Definições de subagentes
│   └── security-reviewer.md
├── hooks/                    # Definições de Hooks
│   └── hooks.json
├── .mcp.json                 # Definição de servidores MCP
├── .lsp.json                 # Configuração de servidores LSP
├── bin/                      # Binários executáveis adicionados ao PATH
├── scripts/                  # Scripts de automação e Hooks
└── settings.json             # Configurações padrão do plugin

Aqui está a regra de ouro de diretório destacada na documentação onde os iniciantes costumam errar:

O diretório .claude-plugin/ deve conter apenas o arquivo plugin.json. Todos os outros diretórios de recursos (como commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) devem estar localizados diretamente na raiz do plugin, e não dentro de .claude-plugin/.

Em termos práticos: a pasta .claude-plugin/ deve conter exclusivamente o arquivo plugin.json, com skills/, agents/ e hooks/ salvos na raiz do plugin, no mesmo nível de .claude-plugin/. Salvar as pastas de componentes dentro de .claude-plugin/ é um erro comum que impede o Claude Code de indexar os recursos, mesmo carregando o manifesto com sucesso. Lembre-se da caixa de Lego: o manual fica em seu próprio compartimento, e as peças ficam organizadas na raiz.

Outro detalhe importante da documentação: arquivos CLAUDE.md na raiz do plugin não são lidos como contexto do projeto. Para fornecer instruções ao Claude, o plugin deve utilizar componentes como skills, agentes ou hooks. Não confunda com o CLAUDE.md do projeto principal analisado no Capítulo 18.

💡 Resumo em uma frase: A estrutura do plugin é composta pelo manifesto (.claude-plugin/plugin.json) e pastas de componentes na raiz; a pasta .claude-plugin/ deve conter apenas o manifesto, mantendo os componentes fora dela.

---

02 Entendendo as Diretivas do plugin.json

Com a estrutura organizada, analise os campos do manifesto plugin.json. Ele define a identidade e as configurações de carregamento do plugin.

Nota de simplificação: o arquivo de manifesto é opcional. Se você omitir o plugin.json, o Claude Code tentará identificar os componentes inspecionando as pastas padrão (skills/, agents/ etc.) e nomeará o plugin com base no nome do diretório. O manifesto é exigido apenas se você precisar definir metadados específicos ou caminhos de componentes personalizados. No entanto, para publicar e distribuir plugins, a escrita do manifesto é recomendada.

Analogia: A guia de importação. Ao enviar mercadorias para outro país, o pacote deve acompanhar uma guia descrevendo o conteúdo, fabricante, número do lote e itens inclusos. A alfândega (Claude Code) usa essa guia para validar, registrar e liberar os itens. O plugin.json é essa guia: nome, autor, versão e componentes declarados em um único arquivo.

Único Campo Obrigatório

Ao optar por escrever o manifesto, apenas o campo name é de preenchimento obrigatório:

Diretiva	Tipo	Descrição
name	string	Identificador único do plugin em formato kebab-case (letras minúsculas e hífens), sem espaços

O campo name é fundamental porque define o namespace (prefixo de escopo) dos componentes do plugin. Se um plugin chamado plugin-dev contiver um agente agent-creator, ele será referenciado na CLI como plugin-dev:agent-creator, e suas skills serão chamadas via /plugin-dev:nome-da-skill. Os namespaces evitam colisões de nomes — permitindo instalar múltiplos plugins que possuam componentes com o mesmo nome sem causar conflitos.

Metadados de Identificação

Embora não afetem o comportamento técnico, ajudam os usuários a identificar e gerenciar os plugins:

Diretiva	Descrição
displayName	Nome amigável de exibição exibido na interface. Aceita maiúsculas e espaços; se omitido, o sistema usará o valor do campo name.
version	Versão do plugin seguindo a especificação de versionamento semântico (SemVer). Controla o gerenciamento de cache de atualizações do usuário (assunto analisado na seção 8).
description	Resumo da utilidade do plugin, exibido em pesquisas e comandos de instalação.
author	Dados do autor (name / email / url).
homepage / repository / license	Endereço do site do projeto / Repositório Git / Tipo de licença de uso.
keywords	Termos e etiquetas de pesquisa para facilitar a descoberta do plugin.

Configurações de Caminhos de Componentes

Se os seus componentes estiverem nas pastas padrão, não há necessidade de preencher estes campos. Use-os apenas para apontar caminhos personalizados:

Diretiva	Tipo	Descrição
skills	array de strings	Pastas de skills adicionais (adicionadas junto com a pasta padrão skills/)
commands / agents / outputStyles	array de strings	Caminhos personalizados de arquivos (que substituem as pastas padrão)
hooks / mcpServers / lspServers	caminhos ou objetos	Arquivos de configuração de hooks ou servidores, ou definições diretas no JSON
dependencies	array de strings	Lista de plugins requeridos por este plugin (analisado na seção 8)

Fique atento a um detalhe importante da documentação sobre o comportamento desses campos: alguns substituem as pastas padrão, enquanto outros adicionam caminhos ao escopo.

• Substituição de Padrões: commands, agents e outputStyles. Ao declarar o campo commands no JSON, a pasta padrão commands/ deixa de ser lida. Para ler tanto a pasta padrão quanto caminhos extras, declare ambos no array: "commands": ["./commands/", "./extras/"].
• Adição ao Escopo: skills. A pasta padrão skills/ sempre será lida, e os diretórios apontados no manifesto serão processados em conjunto.

Esse comportamento pode gerar dúvidas ao iniciar: configurar "agents": ["./extra-agents/reviewer.md"] esperando adicionar um agente secundário removerá os agentes da pasta padrão agents/, pois o campo atua como substituição. Para evitar o problema, liste todos os arquivos desejados no manifesto.

Modelo de manifesto configurado com metadados:

{
  "name": "deployment-tools",
  "displayName": "Deployment Tools",
  "version": "1.2.0",
  "description": "Deployment automation tools",
  "author": { "name": "Dev Team", "email": "dev@company.com" },
  "license": "MIT",
  "keywords": ["deployment", "ci-cd"]
}

💡 Resumo em uma frase: O arquivo plugin.json gerencia o plugin; o único campo obrigatório é o name (que estabelece o namespace); atente-se para quais campos substituem pastas padrão (commands, agents) e quais complementam (skills).

---

03 Categorias de Componentes Suportados em Plugins

Esta seção lista os componentes que podem ser empacotados em um plugin. Cada categoria possui caminhos definidos e regras de execução específicas.

Analogia: As divisórias da caixa de peças. Rodas, eixos e conectores devem ser guardados em suas respectivas divisórias para montagem correta. Da mesma forma, os recursos do plugin devem seguir seus caminhos correspondentes:

Componente	Diretório	Utilidade	Modo de Acionamento
Skills	skills/<nome>/SKILL.md	Lógicas de prompt especializadas (Capítulo 26)	Chamada direta via /plugin:skill ou acionamento autônomo pelo Claude
Commands	commands/*.md	Versão simplificada de Skills em markdown (legado, prefira skills)	Igual às Skills
Agents	agents/*.md	Subagentes dedicados a tarefas específicas (Capítulo 23)	Menu /agents na CLI, ou acionamento direto
Hooks	hooks/hooks.json	Ações automatizadas amarradas a eventos (Capítulo 33)	Disparo automático em eventos de ciclo de vida da sessão
MCP servers	.mcp.json	Conexão com serviços de rede e APIs externas (Capítulo 22)	Ativados com a sessão, expondo ferramentas ao Claude
LSP servers	.lsp.json	Servidores de linguagem para inteligência de código (definições, referências)	Execução automática durante a navegação em código
Monitors	monitors/monitors.json	Monitoramento em segundo plano de logs e eventos do sistema	Executados de forma contínua em sessões interativas (experimental)

Algumas observações importantes baseadas nas diretrizes da documentação oficial:

Restrições para Agentes em Plugins. Por motivos de segurança, subagentes empacotados em plugins não possuem suporte a diretivas de hooks, mcpServers e permissionMode em seus arquivos de frontmatter. Isso impede que um plugin configure subagentes que alterem permissões de execução do sistema ou iniciem servidores MCP autônomos sem validação direta do usuário. Os parâmetros permitidos incluem name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background e isolation (onde o único valor suportado para isolation é "worktree").

Gatilhos de Eventos para Hooks. Hooks integrados a plugins escutam os mesmos eventos de ciclo de vida analisados no Capítulo 33 — cobrindo desde SessionStart (início da sessão), PreToolUse (antes da execução de ferramentas, permitindo interrupções) e PostToolUse (após a execução) até Stop (conclusão de resposta) e SessionEnd (término da sessão). Há dezenas de gatilhos disponíveis para automação.

Variedade de Tipos de Hooks. Além do tipo command (que executa chamadas shell no sistema), o ecossistema aceita http (envio de webhook para uma URL), mcp_tool (chamada de ferramentas MCP), prompt (avaliação de prompt com LLM) e agent (validações usando subagentes).

Monitores em Estágio Experimental. Permitem monitorar arquivos de log ou eventos do sistema em segundo plano para alimentar dados na sessão de forma automática. Este recurso está em estágio experimental, requer a versão v2.1.105 ou superior do Claude Code e é executado apenas em sessões ativas interativas.

Outros recursos de suporte: binários e scripts salvos sob a pasta bin/ são injetados automaticamente no PATH do ambiente durante a execução de ferramentas Bash do Claude, permitindo que a IA execute chamadas diretas a esses executáveis. O arquivo settings.json na raiz gerencia diretivas padrão, suportando no momento as chaves agent (para definir o agente padrão da sessão ao iniciar o plugin) e subagentStatusLine.

💡 Resumo em uma frase: Plugins suportam sete tipos de componentes (skills, comandos, agentes, hooks, servidores MCP, LSP e monitores) com caminhos específicos; agentes de plugins possuem restrições de segurança (sem hooks, MCP ou configurações de permissão em frontmatter).

---

04 Trabalhando com Caminhos Relativos e Variáveis de Ambiente

Esta seção detalha o uso de variáveis de caminhos, que são essenciais para garantir o funcionamento do plugin em sistemas diferentes.

Cenário comum de erro: ao criar um hook ou configurar um servidor MCP que execute scripts/format.sh ou node server.js, apontar caminhos absolutos locais como /Users/desenvolvedor/my-plugin/scripts/format.sh impedirá a execução do plugin em computadores de outros colaboradores, além de falhar após atualizações do plugin, pois o diretório da pasta de cache é alterado.

Para solucionar o problema, o Claude Code fornece três variáveis de caminhos que são resolvidas dinamicamente no carregamento de hooks, MCP, LSP, skills e agentes:

Variável	Resolução de Caminho	Utilidade
${CLAUDE_PLUGIN_ROOT}	Caminho absoluto para a pasta de instalação do plugin	Para referenciar scripts, binários e arquivos salvos dentro da estrutura do plugin
${CLAUDE_PLUGIN_DATA}	Diretório de persistência de dados do plugin (mantido após atualizações)	Para salvar banco de dados local, dependências npm (node_modules) ou cache de execução
${CLAUDE_PROJECT_DIR}	Diretório raiz do projeto ativo na sessão do usuário	Para acessar arquivos, scripts ou configurações locais do repositório de trabalho

Analogia: Referenciar por termos genéricos em vez de nomes próprios. Em uma apostila de instruções corporativas, usar termos como "visite a seção de Recursos no rodapé da página" garante que a instrução continue válida mesmo que a página mude de endereço ou número. Escrever ${CLAUDE_PLUGIN_ROOT} é usar essa indicação genérica — o sistema resolve o endereço exato do diretório atual da versão instalada de forma transparente.

Exemplo de configuração de hook referenciando arquivos do plugin usando variáveis (com aspas duplas de segurança para caminhos com espaços):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Aqui está a diretriz de ciclo de vida da pasta de instalação descrita na documentação:

A pasta apontada por ${CLAUDE_PLUGIN_ROOT} é atualizada a cada nova versão instalada. O diretório antigo é mantido em disco por cerca de 7 dias para processos de limpeza e depois é deletado. Não salve dados ou arquivos de estado dentro desse diretório.

Isso significa que: a pasta do plugin é recriada a cada atualização, descartando dados locais salvos nela. Arquivos temporários ou persistentes (como dependências locais) devem ser gravados em ${CLAUDE_PLUGIN_DATA}, que permanece intocado entre atualizações de versão. Guarde scripts e binários fixos in ROOT, e dados de execução em DATA para evitar perda de dados.

Adicionalmente, lembre-se de que plugins instalados não conseguem referenciar arquivos fora de sua estrutura de diretórios. Caminhos relativos de saída como ../shared-utils que apontem para fora do plugin falharão ao serem instalados, pois a CLI clona apenas a pasta do plugin para o diretório de cache (~/.claude/plugins/cache).

💡 Resumo em uma frase: Utilize a variável ${CLAUDE_PLUGIN_ROOT} para referenciar caminhos internos do plugin sem fixar endereços absolutos; salve dados e dependências persistentes em ${CLAUDE_PLUGIN_DATA} e evite referências a caminhos externos à pasta do plugin.

---

05 Prática: Criando e Testando um Plugin Local

Vamos colocar a teoria em prática criando um plugin simples com manifesto contendo uma skill de boas-vindas com passagem de parâmetros. Faremos o teste local sem precisar de configurações complexas.

Passo 1: Criar a estrutura básica usando a CLI

Use o comando plugin init para gerar a estrutura padrão do plugin:

claude plugin init my-greeter --with skills

A flag --with skills orienta a criação das pastas de skills correspondentes. O comando criará a pasta my-greeter contendo a estrutura de manifesto e recursos no diretório ~/.claude/skills/.

Nota de usabilidade da CLI: diretórios de plugins contendo o arquivo plugin.json salvos sob ~/.claude/skills/ são carregados de forma automática na inicialização como my-greeter@skills-dir, sem demandar registros em marketplaces ou instalações. É o caminho ideal para testar ferramentas de uso pessoal.

Passo 2: Inspecionar os arquivos gerados

Listar os arquivos gerados no diretório do plugin:

ls -R ~/.claude/skills/my-greeter

Resultado esperado: O terminal exibe a pasta .claude-plugin/plugin.json e a pasta skills/ externa. A separação física dos arquivos demonstra a regra de diretórios vista no Passo 1.

Passo 3: Criar um arquivo de Skill

Abra ou crie o arquivo no caminho ~/.claude/skills/my-greeter/skills/hello/SKILL.md e adicione o seguinte conteúdo:

---
description: Cumprimenta o usuário em português com uma mensagem amigável.
---

# Hello Skill

Cumprimente o usuário "$ARGUMENTS" com entusiasmo em português, perguntando como posso auxiliá-lo no desenvolvimento do projeto hoje. Seja amigável e use um tom colaborativo.

O parâmetro $ARGUMENTS capturará os argumentos digitados no prompt do console após o nome do comando (reutilizando a lógica de parâmetros vista no Capítulo 26).

Passo 4: Carregar o plugin local no console

Inicie a CLI do Claude Code passando o diretório del plugin local com a flag --plugin-dir (ideal para depuração em tempo real):

claude --plugin-dir ~/.claude/skills/my-greeter

Resultado esperado: O Claude Code inicia a sessão de forma normal. Digite /help no prompt para listar os comandos. O comando /my-greeter:hello deve aparecer listado no escopo do namespace do seu plugin.

Passo 5: Acionar a Skill do plugin

Execute a chamada da skill enviando um argumento de texto:

/my-greeter:hello Walter

Resultado esperado: O Claude responde em português com uma mensagem de boas-vindas entusiasta citando o nome "Walter", conforme as diretrizes do prompt da skill. A resposta confirma o carregamento e execução do plugin local.

Passo 6: Alterar a Skill e atualizar a sessão

Faça uma edição rápida no texto de SKILL.md (adicionando emoji ou mudando a frase) e execute o comando de recarregamento no console (sem precisar sair da sessão):

/reload-plugins

Resultado esperado: A execução de /my-greeter:hello Walter exibe a mensagem atualizada. O recarregamento permite testar alterações de forma rápida.

Lembre-se: alterações de arquivos de skills (SKILL.md) são processadas em tempo real, enquanto mudanças em hooks, MCP (.mcp.json) e configurações de agentes exigem rodar o comando /reload-plugins ou reiniciar a sessão para serem aplicadas.

💡 Resumo em uma frase: Use claude plugin init para criar a estrutura, inicie com claude --plugin-dir <caminho> para depurar localmente e execute /reload-plugins no prompt para atualizar lógicas de hooks e configurações sem reiniciar a sessão.

---

06 Criando e Distribuindo um Marketplace de Plugins

Para distribuir plugins para outros usuários ou para a equipe, é necessário criar e hospedar um Marketplace. O Capítulo 24 apresentou a instalação; aqui veremos como disponibilizar novos pacotes.

Diferença de termos:

• Marketplace Source (Origem do Marketplace): o endereço Git ou pasta que disponibiliza o arquivo de catálogo contendo as definições dos plugins (marketplace.json). Adicionado na CLI via comando /plugin marketplace add.
• Plugin Source (Origem do Plugin): a localização onde os arquivos de código de cada plugin estão hospedados (indicado no catálogo).

Analogia: Catálogo de loja vs. Estoque de fornecedor. O marketplace funciona como o catálogo impresso da loja que lista as mercadorias disponíveis para compra, enquanto as fontes dos plugins indicam onde a transportadora deve buscar cada caixa de produto. O catálogo pode estar hospedado em um repositório central, enquanto os códigos dos plugins podem estar distribuídos em servidores variados.

O arquivo central do marketplace é o .claude-plugin/marketplace.json, salvo na raiz da pasta do repositório do catálogo. Exemplo de estrutura mínima:

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-greeter",
      "source": "./plugins/my-greeter",
      "description": "A friendly greeting plugin"
    }
  ]
}

O campo source indica de onde obter os arquivos do plugin. Os formatos de origem aceitos no catálogo incluem:

Formato de Origem	Estrutura	Cenário de Uso
Caminho Relativo	"./plugins/my-greeter"	Quando os arquivos do plugin estão salvos dentro do mesmo repositório do catálogo (comum para monorepos)
Repositório GitHub	{ "source": "github", "repo": "organizacao/repositorio" }	Para buscar o plugin em um repositório independente do GitHub
Diretório Git	Mapeamento com url e path	Para buscar o plugin em uma subpasta específica de um repositório Git externo
Pacote NPM	{ "source": "npm", "package": "@escopo/nome-do-pacote" }	Para obter pacotes publicados no registro do NPM

Exercício: Adicionar o plugin a um marketplace local para teste. Crie um diretório de teste my-marketplace estruturado com a pasta .claude-plugin/marketplace.json e a subpasta plugins/my-greeter/ contendo os arquivos do plugin criados anteriormente. No console do Claude Code, execute:

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

Resultado esperado: O console exibe a inclusão da nova origem de marketplace e conclui a instalação do plugin my-greeter. O comando /my-greeter:hello passa a funcionar a partir da instalação no marketplace local.

Antes de compartilhar a pasta ou o repositório, execute a validação de integridade na CLI:

claude plugin validate ./my-marketplace

Resultado esperado: A CLI valida o schema do arquivo marketplace.json (checando duplicidade de nomes, loops de dependências, uso de caminhos relativos e inconsistências). Para validar os arquivos internos (como frontmatter de skills do plugin), aponte para a pasta específica do plugin.

Para disponibilizar o marketplace para a equipe, envie a pasta para um repositório Git. Os outros colaboradores poderão adicioná-lo rodando o comando /plugin marketplace add <github-org>/<github-repo>.

💡 Resumo em uma frase: Estruture o arquivo .claude-plugin/marketplace.json listando os plugins e seus caminhos de origem (source), valide o catálogo rodando claude plugin validate <caminho> e compartilhe via repositório Git.

---

07 Estratégias de Carregamento de Plugins

Ao estruturar e testar plugins, escolha o fluxo de carregamento adequado para a etapa do desenvolvimento.

Abordagem	Funcionamento	Comando de Execução	Propriedade Principal
Skills Dir (Carregamento Implícito)	Salvar a pasta em ~/.claude/skills/<nome>	Carregamento automático na inicialização da CLI	Ideal para plugins de uso pessoal em depuração local (免 instalação)
CLI Flag (Carregamento Temporário)	Apontar a pasta com --plugin-dir	claude --plugin-dir ./my-plugin	Ativo apenas durante a execução daquela sessão, limpando logs após fechar
Marketplace (Instalação Padrão)	Adicionar o catálogo e instalar	/plugin install plugin@marketplace	Permite controle de versões, dependências e compartilhamento

Dicas de uso:

• O comando --plugin-dir não salva configurações no sistema. Ao encerrar o console, o plugin é descarregado da CLI, não deixando resíduos nas configurações globais do usuário. É ideal para testar modificações rápidas em andamento.
• Sobrescrita Temporária: a flag --plugin-dir com o mesmo nome de um plugin já instalado via marketplace sobrescreve a versão oficial temporariamente naquela sessão, permitindo depurar alterações locais sem ter que desinstalar o pacote do marketplace.
• Escopos do Skills Dir: plugins salvos na pasta de usuário ~/.claude/skills/ são compartilhados em todos os repositórios. No entanto, se salvos na pasta do projeto .claude/skills/, a documentação oficial orienta: o carregamento é restrito a sessões iniciadas no diretório raiz do projeto. Se você abrir o Claude Code dentro de uma subpasta, o sistema não lerá os plugins da raiz do projeto de forma automática. Execute /reload-plugins na sessão ou inicie a ferramenta sempre a partir do diretório raiz.

Evite publicar no marketplace logo no início. É mais ágil estruturar o plugin usando as abordagens locais de desenvolvimento e, apenas após obter estabilidade, exportar as definições para o catálogo de distribuição do marketplace.

💡 Resumo em uma frase: Utilize a pasta de usuário ~/.claude/skills/ para ferramentas de uso pessoal permanente, a flag --plugin-dir para depurar alterações rápidas locais e use marketplaces apenas na etapa de distribuição final.

---

08 Resolvendo Desafios Comuns em Distribuição: Cache de Versões e Dependências

A distribuição de plugins para equipes envolve gerenciar o controle de atualizações (cache do cliente) e as dependências entre pacotes.

Desafio 1: Atualização de Versões Bloqueada por Cache

Ao disponibilizar atualizações de plugins, como o Claude Code decide se deve obter os novos arquivos? O sistema verifica a versão na seguinte precedência:

1. A chave version no manifesto plugin.json do plugin.
2. A chave version declarada no catálogo marketplace.json.
3. O hash de commit (SHA) do repositório Git do plugin (se as chaves anteriores forem omitidas).

A documentação destaca a seguinte limitação de cache:

Configurar o campo version fixa os arquivos do plugin. Se o manifesto mantiver a versão "1.0.0", enviar novos commits ao repositório Git do plugin não atualizará a cópia local dos clientes, pois o Claude Code entenderá que a versão permanece inalterada e lerá os dados a partir do cache local.

Para resolver o problema, escolha uma das duas abordagens:

Abordagem	Configuração no Manifesto	Comportamento de Atualização	Cenário de Uso
Versionamento Manual (SemVer)	Declare "version": "x.y.z" e atualize a numeração a cada modificação.	Os usuários recebem atualizações apenas ao rodar o comando de update após incremento da versão.	Recomendado para plugins maduros com ciclos de release estruturados.
Versionamento por Commit (SHA)	Remova o campo version do manifesto plugin.json.	Toda alteração enviada ao repositório Git é identificada como nova versão, atualizando o cliente automaticamente.	Recomendado para plugins em desenvolvimento ativo ou de uso interno da equipe.

Evite declarar chaves de versão simultaneamente no manifesto do plugin e no catálogo do marketplace. A chave no plugin.json sobrescreve a declaração do marketplace.json silenciosamente, o que pode causar falhas se as numerações não estiverem sincronizadas.

Desafio 2: Declarar Dependências entre Plugins

Se o seu plugin requer funcionalidades expostas por outro pacote, configure o mapeamento no campo dependencies no JSON:

{
  "name": "my-plugin",
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Ao instalar o plugin principal, o Claude Code lerá a lista e instalará as dependências de forma automática. O controle de versão suporta filtros SemVer (como ~2.1.0) para evitar que atualizações de pacotes secundários quebrem a lógica do seu plugin.

Ao desinstalar plugins, rodar claude plugin uninstall --prune removerá dependências que tenham sido instaladas automaticamente e que não sejam mais requeridas por nenhum outro plugin ativo. Plugins instalados de forma direta pelo usuário não são afetados pelo comando de limpeza.

💡 Resumo em uma frase: Remova o campo version em plugins de desenvolvimento contínuo para que as atualizações Git forcem a atualização do cache dos clientes, e utilize o campo dependencies no manifesto para declarar bibliotecas ou plugins auxiliares requeridos.

---

09 Resumo

Neste capítulo, detalhamos o ecossistema de criação e publicação de plugins do Claude Code, capacitando você a estruturar, testar e compartilhar suas ferramentas de automação.

Principais conceitos abordados:

Tópico	Funcionamento Técnico	Recomendação Prática
Estrutura de Pastas	Pasta .claude-plugin/ contém apenas o manifesto plugin.json	Mantenha as pastas de componentes (skills/agents) na raiz do plugin
Definição de Namespace	O nome do plugin define o escopo dos comandos	Evita colisões de nomes entre componentes de plugins diferentes
Variáveis de Caminho	${CLAUDE_PLUGIN_ROOT} resolve o local de instalação	Nunca utilize caminhos absolutos locais; salve banco e cache em ${CLAUDE_PLUGIN_DATA}
Fluxo de Testes	Use plugin init e inicie a CLI com a flag --plugin-dir	Teste alterações na sessão atual executando o comando /reload-plugins
Distribuição	Catálogo configurado em .claude-plugin/marketplace.json	Valide a sintaxe do catálogo executando claude plugin validate <caminho>
Cache de Versões	O cache local bloqueia atualizações se a versão não for incrementada	Remova o campo version em ferramentas internas para atualizar a partir de commits Git

Agora você é capaz de: estruturar a árvore de diretórios de seus plugins conforme as regras de indexação, configurar manifestos especificando namespaces, utilizar variáveis de caminhos para garantir portabilidade de scripts em outros computadores, depurar lógicas locais com recarregamento dinâmico de plugins, criar marketplaces de distribuição e gerenciar o cache de atualizações para sua equipe. Isso permite modularizar e distribuir suas ferramentas de produtividade.

Compreendendo o ciclo de criação e distribuição de plugins, completamos a trilha de extensão das funcionalidades da CLI.

---

O próximo capítulo, 39 "Prática de Introdução", iniciará a trilha prática do ecossistema. Reuniremos os conceitos explicados até aqui (lógicas de prompts, uso de arquivos CLAUDE.md, controle de subagentes, checkpoints e execução de plugins) para resolver um caso real de desenvolvimento de software de ponta a ponta. Nos vemos no próximo capítulo!

---

Leituras Recomendadas

• Estrutura do Projeto: Diretórios Gerados na Sessão
• Agent SDK: Integrando o Claude Code em Aplicações Externas
• Gerenciamento de Contexto: Otimizando o Consumo de Tokens