Referência de plugins

Referência técnica completa para o sistema de plugins do Claude Code, incluindo esquemas, comandos CLI e especificações de componentes.

Um plugin é um diretório independente de componentes que estende o Claude Code com funcionalidade personalizada. Os componentes do plugin incluem skills, agents, hooks, servidores MCP, servidores LSP e monitores.

Referência de componentes de plugin

Skills

Os plugins adicionam skills ao Claude Code, criando atalhos /name que você ou Claude podem invocar.

Localização: diretório skills/ ou commands/ na raiz do plugin, ou um único arquivo SKILL.md na raiz do plugin

Formato de arquivo: Skills são diretórios com SKILL.md; commands são arquivos markdown simples

Estrutura de skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opcional)
│   └── scripts/ (opcional)
└── code-reviewer/
    └── SKILL.md

Skills e commands são descobertos automaticamente quando o plugin é instalado.

Se um plugin não tem diretório skills/ e nenhum campo manifest skills, um SKILL.md na raiz do plugin é carregado como um único skill. Defina o campo frontmatter name para controlar o nome de invocação do skill. Sem ele, Claude Code volta para o nome do diretório de instalação, que para plugins instalados do marketplace é uma string de versão que muda a cada atualização. Para plugins que enviam mais de um skill, use o layout de diretório skills/ mostrado acima.

Em skills e commands de plugin, campos frontmatter booleanos como disable-model-invocation aceitam yes, no, on, off, 1 e 0 em qualquer caso de letra, além de true e false. Antes da v2.1.218, Claude Code reconhecia apenas true e false.

Para detalhes completos, consulte Skills.

Agents

Os plugins podem fornecer subagentes especializados para tarefas específicas que Claude pode invocar automaticamente quando apropriado.

Localização: diretório agents/ na raiz do plugin

Formato de arquivo: Arquivos markdown descrevendo capacidades do agent

Estrutura de agent:

---
name: agent-name
description: O que este agent se especializa e quando Claude deve invocá-lo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt de sistema detalhado para o agent descrevendo seu papel, expertise e comportamento.

Plugin agents suportam campos frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background e isolation. O único valor válido de isolation é "worktree". Por razões de segurança, hooks, mcpServers e permissionMode não são suportados para agents fornecidos por plugin.

Claude Code carrega um agent de plugin mesmo quando seu frontmatter não tem name ou não faz parse:

• Sem name: Claude Code nomeia o agent após o arquivo, então agents/reviewer.md em um plugin chamado my-plugin carrega como my-plugin:reviewer
• Frontmatter que não faz parse: Claude Code nomeia o agent após o arquivo, usa Agent from my-plugin plugin como sua descrição e ignora cada campo no arquivo

Em contraste, Claude Code pula um arquivo de project, user ou managed agent cujo frontmatter não tem name ou não faz parse.

Para encontrar arquivos no diretório padrão agents/ de um plugin cujo frontmatter não faz parse, execute claude plugin validate. O caminho que você passa depende se o plugin tem um manifest, e ambos os exemplos usam ./my-plugin como o diretório do plugin:

• Um plugin com manifest: claude plugin validate ./my-plugin
• Um plugin sem manifest: claude plugin validate ./my-plugin/agents. Requer Claude Code v2.1.233 ou posterior.

Agents aparecem na typeahead de @-mention sob seu nome com escopo, como my-plugin:code-reviewer, uma vez que o plugin está habilitado.

Para detalhes completos, consulte Subagents.

Hooks

Os plugins podem fornecer manipuladores de eventos que respondem a eventos de Claude Code automaticamente.

Localização: hooks/hooks.json na raiz do plugin, ou inline em plugin.json

Formato: Configuração JSON com matchers de eventos e ações

Configuração de hook:

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

Plugin hooks respondem aos mesmos eventos de ciclo de vida que hooks definidos pelo usuário:

Tipos de hook:

• command: executar comandos shell ou scripts
• http: enviar o JSON do evento como uma solicitação POST para uma URL
• mcp_tool: chamar uma ferramenta em um servidor MCP configurado
• prompt: avaliar um prompt com um LLM (usa placeholder $ARGUMENTS para contexto)
• agent: executar um verificador agentic com ferramentas para tarefas de verificação complexas

Hooks que visam o servidor MCP agrupado do próprio plugin devem usar seus nomes com escopo. Matchers de ferramenta e campos if usam o nome de ferramenta com escopo mcp__plugin_<plugin-name>_<server-name>__<tool>, e o campo server de um hook mcp_tool usa plugin:<plugin-name>:<server-name>. Um matcher escrito contra a chave do servidor simples nunca dispara. Consulte Match MCP tools e Plugin-provided MCP servers.

MCP servers

Os plugins podem agrupar servidores Model Context Protocol (MCP) para conectar Claude Code com ferramentas e serviços externos.

Localização: .mcp.json na raiz do plugin, ou inline em plugin.json

Formato: Configuração padrão de servidor MCP

Configuração de servidor MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Comportamento de integração:

• Servidores MCP de plugin iniciam automaticamente quando o plugin está habilitado
• Servidores aparecem como ferramentas MCP padrão no toolkit de Claude
• Servidores de plugin podem ser configurados independentemente de servidores MCP do usuário
• Se você executar /reload-plugins no meio da sessão, Claude Code mantém as conexões ativas de servidores cuja configuração não foi alterada

LSP servers

Os plugins podem fornecer servidores Language Server Protocol (LSP) para dar a Claude inteligência de código em tempo real enquanto trabalha em sua base de código.

Localização: .lsp.json na raiz do plugin, ou inline em plugin.json

Formato: Configuração JSON mapeando nomes de servidores de linguagem para suas configurações

Formato de arquivo .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Inline em plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Campos obrigatórios:

Campos opcionais:

restartOnCrash e shutdownTimeout requerem Claude Code v2.1.205 ou posterior. Antes da v2.1.205, o schema de configuração aceitava ambas as opções mas definir qualquer uma delas fazia Claude Code pular esse servidor LSP inteiramente na inicialização, com o motivo visível apenas na saída claude --debug.

Múltiplos servidores para a mesma extensão: quando mais de um servidor LSP habilitado declara a mesma extensão de arquivo em extensionToLanguage, se os servidores vêm de um plugin ou de plugins diferentes, o primeiro servidor registrado manipula arquivos com essa extensão e os outros nunca iniciam. A interface /plugin mostra um aviso nomeando o plugin cujo servidor está ativo.

Servidores que falham ao inicializar: Claude Code pula um servidor cuja configuração é inválida, por exemplo um que falta command ou extensionToLanguage, e os outros servidores configurados ainda iniciam. Execute claude --debug para ver por que um servidor foi pulado.

Um servidor pulado não reclama suas extensões de arquivo, então outro servidor válido que declara a mesma extensão, do mesmo plugin ou de um plugin diferente, ainda manipula esses arquivos.

Envie saída de log para stderr, não stdout: Claude Code lê stdout de um servidor apenas como mensagens de protocolo, e aceita cabeçalhos de mensagem até 64 KiB e um corpo de mensagem até 32 MiB. Claude Code desconecta um servidor que excede qualquer limite ou escreve saída não-protocolo para stdout, e conta a desconexão como uma falha para restartOnCrash e maxRestarts. Quando você executa com --debug, Claude Code escreve um erro nomeando a causa para o log de debug.

Plugins LSP disponíveis:

Instale o servidor de linguagem primeiro, depois instale o plugin do marketplace.

Monitors

Os plugins podem declarar monitors de background que Claude Code inicia automaticamente quando o plugin está ativo. Cada monitor executa um comando shell pela vida útil da sessão e entrega cada linha de stdout para Claude como uma notificação, para que Claude possa reagir a entradas de log, mudanças de status ou eventos pesquisados sem ser solicitado a iniciar o watch em si.

Plugin monitors usam o mesmo mecanismo que a ferramenta Monitor e compartilham suas restrições de disponibilidade. Eles executam apenas em sessões CLI interativas, executam sem sandbox no mesmo nível de confiança que hooks, e são pulados em hosts onde a ferramenta Monitor não está disponível.

Localização: monitors/monitors.json na raiz do plugin, ou inline em plugin.json

Formato: Array JSON de entradas de monitor

O seguinte monitors/monitors.json observa um endpoint de status de deployment e um log de erro local:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Para declarar monitors inline, defina experimental.monitors em plugin.json para o mesmo array. Para carregar de um caminho não-padrão, defina experimental.monitors para uma string de caminho relativo como "./config/monitors.json". Monitors são um componente experimental.

Campos obrigatórios:

Campos opcionais:

O valor command suporta as substituições de caminho ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} e ${CLAUDE_PROJECT_DIR}, mais qualquer ${ENV_VAR} do ambiente. Prefixe o comando com cd "${CLAUDE_PLUGIN_ROOT}" && se o script precisa executar do próprio diretório do plugin.

Um command de monitor não pode referenciar valores ${user_config.*}. O comando executa através de um shell, então Claude Code rejeita o monitor com um erro em vez de substituir o valor. Processos de monitor não recebem variáveis de ambiente CLAUDE_PLUGIN_OPTION_<KEY>, então faça o script de monitor ler o valor de um arquivo de configuração que ele possui.

Se você desabilitar um plugin no meio da sessão, Claude Code não para monitors que já estão em execução; eles param quando a sessão termina.

Themes

Os plugins podem enviar temas de cor que aparecem em /theme junto com as predefinições integradas e os temas locais do usuário. Um tema é um arquivo JSON em themes/ com uma predefinição base e um mapa esparso overrides de tokens de cor. Themes são um componente experimental.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Quando um usuário seleciona um tema de plugin, Claude Code salva custom:<plugin-name>:<slug> em sua configuração. Temas de plugin são somente leitura: quando um usuário pressiona Ctrl+E em um em /theme, Claude Code o copia para ~/.claude/themes/ para que possam editar a cópia.

Escopos de instalação de plugin

Quando você instala um plugin, você escolhe um escopo que determina onde o plugin está disponível e quem mais pode usá-lo:

Os plugins usam o mesmo sistema de escopo que outras configurações do Claude Code. Para instruções de instalação e sinalizadores de escopo, consulte Install plugins. Para uma explicação completa de escopos, consulte Configuration scopes.

Plugins de diretório de skills

Qualquer pasta sob um diretório de skills que contenha um manifesto .claude-plugin/plugin.json é carregada como um plugin nomeado <name>@skills-dir na próxima sessão, sem marketplace e sem etapa de instalação. Crie um com plugin init. Diferentemente de uma instalação de marketplace copiada, o plugin é descoberto no local em vez de ser copiado para o cache de plugins.

Uma árvore de diretório de skills suporta três coisas distintas:

Escolha de onde o plugin é carregado

Um plugin de escopo de projeto é verificado no repositório e alcança cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de vir de você, ele é carregado apenas após o mesmo portão de confiança que governa as regras de permissão de projeto em .claude/settings.json, portanto confiar em uma pasta pai ou executar com -p não é suficiente, e 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 LSP iniciam apenas depois que você confia no workspace
• Monitores de fundo não são carregados

Plugins de escopo pessoal não têm nenhuma dessas restrições.

Editar, recarregar e desabilitar um plugin de diretório de skills

As alterações que você faz no SKILL.md de um skill entram em vigor imediatamente na sessão atual. As alterações em outros componentes do plugin, como hooks/, .mcp.json, agents/ e output-styles/, não entram. Execute /reload-plugins ou reinicie Claude Code para aplicá-las. Veja Detecção de mudança ao vivo.

Para parar de carregar um plugin de diretório de skills, delete sua pasta ou desabilite-o por nome. Não há etapa de uninstall porque nada foi instalado de um marketplace.

claude plugin disable my-tool@skills-dir

Plugins sincronizados do claude.ai

Em Cowork e sessões em nuvem, Claude Code baixa os plugins habilitados para sua conta claude.ai em ~/.claude/plugins/synced/ no próprio ambiente da sessão e carrega cada um como <name>@synced, sem marketplace e sem registro de instalação. Claude Code não os carrega em sessões que você inicia em seu próprio terminal. Dentro desse ambiente Cowork ou em nuvem, claude plugin list mostra as cópias baixadas sob um cabeçalho Synced from claude.ai. Antes da v2.1.239, Claude Code carregava esses plugins como <name>@inline, a identidade que os plugins --plugin-dir usam.

Gerencie um plugin sincronizado pelo ID <name>@synced que claude plugin list imprime:

• Desativar um: na sessão sincronizada, execute claude plugin disable <name>@synced, ou peça a Claude para executá-lo. Claude Code salva a escolha como "<name>@synced": false no enabledPlugins de nível de usuário daquele ambiente. Para ativar o plugin novamente, execute claude plugin enable <name>@synced na mesma sessão. Para manter um plugin fora de todas as sessões sincronizadas, desative-o para sua conta claude.ai. Para mantê-lo fora das sessões sincronizadas de um projeto em todos os ambientes, defina "<name>@synced": false sob enabledPlugins no .claude/settings.json comprometido daquele projeto.
• Gerencie o plugin em si no claude.ai: claude plugin install, update e uninstall não se aplicam a um plugin sincronizado. Para remover um, desative o plugin para sua conta claude.ai; a próxima sessão sincronizada inicia sem ele.

Quando um plugin habilitado de qualquer outra fonte, como uma instalação do marketplace, um plugin do diretório de skills, ou um plugin --plugin-dir, corresponde ao nome de um plugin sincronizado, 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, desative sua própria cópia. Antes da v2.1.239, Claude Code carregava a cópia sincronizada em vez de uma instalação do marketplace com o mesmo nome.

Esquema de manifesto de plugin

O arquivo .claude-plugin/plugin.json define os metadados e a configuração do seu plugin.

O manifesto é opcional. Se omitido, Claude Code descobre automaticamente componentes em locais padrão e deriva o nome do plugin do nome do diretório. Use um manifesto quando precisar fornecer metadados ou caminhos de componentes personalizados.

Esquema completo

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Campos obrigatórios

Se você incluir um manifesto, name é o único campo obrigatório.

Este nome é usado para namespacing de componentes. Por exemplo, na interface do usuário, o agente agent-creator para o plugin com nome plugin-dev aparecerá como plugin-dev:agent-creator.

Campos não reconhecidos

Claude Code ignora campos de nível superior que não reconhece. Você pode manter metadados de outro ecossistema em plugin.json e o plugin ainda carrega. Isso torna prático manter um manifesto que funciona como manifesto de extensão VS Code ou Cursor, um package.json npm, ou um manifesto de bundle MCPB/DXT.

claude plugin validate relata campos não reconhecidos como avisos, não erros. Se um campo está um ou dois caracteres diferente de um reconhecido, o aviso sugere o nome provavelmente pretendido. Um plugin com apenas avisos de campos não reconhecidos ainda passa na validação e carrega em tempo de execução.

Como Claude Code lida com um campo reconhecido cujo valor tem o tipo errado depende do campo:

• Maioria dos campos: o plugin falha ao carregar. Por exemplo, um valor keywords que é uma string em vez de um array é um erro de carregamento, e claude plugin validate o relata como tal.
• experimental e metadata: Claude Code ignora um valor não-objeto, e claude plugin validate relata um aviso.

Passe --strict para tratar avisos como erros. Use-o em CI para detectar um nome de campo digitado incorretamente ou um campo deixado de outra ferramenta de manifesto antes de publicar, mesmo que o plugin carregasse em tempo de execução.

claude plugin validate ./my-plugin --strict

Campos de metadados

Habilitação padrão

Defina defaultEnabled: false em plugin.json para enviar um plugin que instala desabilitado. O usuário o ativa com claude plugin enable <plugin> ou a interface /plugin. Use isso para plugins que adicionam custo ou escopo que um usuário deve optar por usar, como um que se conecta a um serviço externo.

defaultEnabled é o fallback quando nada mais decidiu o estado do plugin. Duas coisas têm precedência sobre ele:

• A configuração do usuário: uma entrada para o plugin em enabledPlugins em qualquer escopo de configurações. Uma vez escrita, persiste entre atualizações e reinstalações de plugin, então alterar defaultEnabled em uma versão posterior não inverte um usuário existente.
• Um requisito de dependência: quando um plugin é exigido por outro que está ativo, Claude Code escreve true para ele em tempo de instalação ou habilitação. Isso lhe dá uma configuração explícita, então seu próprio padrão não se aplica mais. Veja Habilitar ou desabilitar um plugin com dependências.

O mesmo campo pode aparecer na entrada de marketplace de um plugin, onde tem precedência sobre o valor em plugin.json. Veja Campos de plugin opcionais.

Campos de caminho de componente

Componentes experimentais

Componentes sob a chave experimental, themes e monitors, têm um esquema de manifesto que pode mudar entre versões enquanto estabilizam. Onde você os declara é uma migração separada: o nível superior ainda funciona, claude plugin validate avisa, e uma versão futura exigirá experimental.*.

Configuração do usuário

O campo userConfig declara valores que Claude Code solicita ao usuário quando o plugin é habilitado. Use isso em vez de exigir que os usuários editem manualmente settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

As chaves devem ser identificadores válidos. Cada opção suporta estes campos:

Cada valor está disponível para substituição como ${user_config.KEY} em configurações de servidor MCP e LSP e comandos de hook. Valores não-sensíveis também podem ser substituídos em conteúdo de skill e agente. Todos os valores são exportados para processos de hook como variáveis de ambiente CLAUDE_PLUGIN_OPTION_<KEY>, onde <KEY> é a chave de opção em maiúsculas.

Campos que executam em um shell rejeitam ${user_config.*}: substituir um valor configurado em um comando shell deixaria o shell executar o que quer que esse valor contenha, então o componente falha com um erro em vez disso. Cada campo rejeitado tem uma forma alternativa de passar o valor:

Antes de v2.1.207, esses campos substituíam valores ${user_config.KEY}; atualize plugins que dependiam disso.

Valores não-sensíveis são armazenados sob a chave pluginConfigs em seu settings.json de usuário como pluginConfigs[<plugin-id>].options.

No macOS, Claude Code armazena valores sensíveis no Keychain do macOS, voltando para ~/.claude/.credentials.json quando o Keychain rejeita a escrita. Em plataformas sem um keychain suportado, ele os armazena em ~/.claude/.credentials.json. O armazenamento em Keychain é compartilhado com tokens OAuth e tem um limite total de aproximadamente 2 KB, então mantenha valores sensíveis pequenos.

Claude Code lê todos os valores pluginConfigs de apenas três fontes de configurações:

• Configurações do usuário: ~/.claude/settings.json, o arquivo que o prompt em tempo de habilitação escreve
• --settings: a flag CLI ou configurações inline do SDK
• Configurações gerenciadas: política controlada pela organização

Quando mais de uma fonte define a mesma chave, configurações gerenciadas têm precedência, depois --settings, depois configurações do usuário. A única fonte que você pode remover desta lista é configurações do usuário: passe --setting-sources sem user e Claude Code as ignora. Configurações gerenciadas e --settings permanecem o que você passar. A opção settingSources do SDK define a mesma lista.

Entradas em .claude/settings.json ou .claude/settings.local.json de um projeto são ignoradas. Ambos os arquivos vivem no workspace, então um repositório clonado poderia fornecer valores lá, e esses valores fluiriam para comandos de hook de plugin, configurações de servidor MCP, comandos LSP e comandos de monitor. Antes de v2.1.207, essas entradas eram lidas. A restrição é específica para pluginConfigs: enabledPlugins ainda honra configurações de projeto e local.

Canais

O campo channels permite que um plugin declare um ou mais canais de mensagem que injetam conteúdo na conversa. Cada canal se vincula a um servidor MCP que o plugin fornece.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

O campo server é obrigatório e deve corresponder a uma chave em mcpServers do plugin. O userConfig opcional por canal usa o mesmo esquema que o campo de nível superior, permitindo que o plugin solicite tokens de bot ou IDs de proprietário quando o plugin é habilitado.

Regras de comportamento de caminho

Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:

• Substitui o padrão: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Por exemplo, quando o manifesto especifica commands, o diretório padrão commands/ não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: "commands": ["./commands/", "./extras/"]
• Adiciona ao padrão: skills. O diretório padrão skills/ é sempre verificado, e diretórios listados em skills são carregados junto com ele. Exceção: para uma entrada de marketplace cuja source resolve para a raiz de marketplace, declarar subdiretórios específicos substitui a varredura padrão skills/
• Regras de mesclagem próprias: hooks, servidores MCP, e servidores LSP. Veja cada seção para como múltiplas fontes se combinam

Quando um plugin tem tanto uma pasta padrão quanto a chave de manifesto correspondente, Claude Code avisa sobre a pasta ignorada em claude plugin list e a visualização de detalhes /plugin. O plugin ainda carrega usando os caminhos de manifesto. Claude Code não avisa quando a chave de manifesto aponta para dentro da pasta padrão, por exemplo "commands": ["./commands/deploy.md"], porque esse caminho nomeia a pasta explicitamente.

Para todos os campos de caminho:

• Todos os caminhos devem ser relativos à raiz do plugin e começar com ./, exceto que o campo skills também aceita "."
  • Ambos "." e "./" denotam a raiz do plugin em si
  • Antes de v2.1.221, "." falhava na validação de manifesto e o plugin não carregava, então use "./" para suportar versões anteriores
• Componentes de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing
• Múltiplos caminhos podem ser especificados como arrays
• Um caminho de skill pode apontar para um diretório que contém um SKILL.md diretamente, por exemplo "skills": ["."] para a raiz do plugin
  • Claude Code pega o nome de invocação do skill do campo name do frontmatter em SKILL.md, então o nome permanece estável qualquer que seja o nome do diretório de instalação
  • Se name não estiver definido no frontmatter, Claude Code volta para o basename do diretório

Um plugin que tem um SKILL.md em sua raiz, nenhum subdiretório skills/, e nenhum campo de manifesto skills é automaticamente carregado como um plugin de skill único. Você não precisa definir "skills": ["./"] em plugin.json para este layout.

Exemplos de caminho:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variáveis de ambiente

Claude Code fornece três variáveis para referenciar caminhos:

Todos os três são exportados como variáveis de ambiente para processos de hook e para subprocessos de servidor MCP e LSP. Quais campos substituem eles inline depende do componente do plugin:

Em comandos de hook, use forma exec com args para que cada caminho seja passado como um argumento sem aspas. Em hooks de forma shell e comandos de monitor, envolva as variáveis em aspas duplas, como em "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Este hook de forma shell executa um script agrupado com um plugin:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} muda quando o plugin é atualizado. O diretório da versão anterior permanece no disco por um período de carência após uma atualização, mas trate-o como efêmero e não escreva estado lá. Veja plugin caching para semântica de limpeza.

Quando um plugin é atualizado 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 exigem reinicialização de sessão. Em uma sessão sem terminal interativo, o reload deixa servidores MCP de plugin no caminho antigo até a próxima sessão.

Para um plugin com uma command source, Claude Code pode recarregar o plugin em si.

Servidores MCP também podem chamar a solicitação roots/list para ler os diretórios de trabalho da sessão em tempo de execução. Veja o que roots/list retorna e quando Claude Code notifica o servidor de mudanças.

Diretório de dados persistente

O diretório ${CLAUDE_PLUGIN_DATA} resolve para ~/.claude/plugins/data/{id}/, onde {id} é o identificador do plugin com caracteres fora de a-z, A-Z, 0-9, _, e - substituídos por -. Para um plugin instalado como formatter@my-marketplace, o diretório é ~/.claude/plugins/data/formatter-my-marketplace/.

Um uso comum é instalar dependências de linguagem uma vez e reutilizá-las entre sessões e atualizações de plugin. Use para dependências Python, dependências bloqueadas com Yarn ou pnpm, e pacotes cujos scripts de ciclo de vida devem executar. Para um plugin instalado a partir de um marketplace, talvez você nem precise dele: Claude Code instala automaticamente dependências de pacote Node.js elegíveis quando armazena em cache o plugin.

Como o diretório de dados sobrevive a qualquer versão única de plugin, uma verificação de existência de diretório sozinha não pode detectar quando uma atualização muda o manifesto de dependência do plugin. O padrão recomendado compara o manifesto agrupado contra uma cópia no diretório de dados e reinstala quando diferem.

Este hook SessionStart instala node_modules na primeira execução e novamente sempre que uma atualização de plugin inclui um package.json alterado:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

O diff sai com código diferente de zero quando a cópia armazenada está faltando ou difere da agrupada, cobrindo tanto primeira execução quanto atualizações que mudam dependências. Se npm install falhar, o rm final remove o manifesto copiado para que a próxima sessão tente novamente.

Scripts agrupados em ${CLAUDE_PLUGIN_ROOT} podem então executar contra o node_modules persistido:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

O diretório de dados é deletado automaticamente quando você desinstala o plugin do último escopo onde está instalado. A interface /plugin mostra o tamanho do diretório e solicita antes de deletar. A CLI deleta por padrão; passe --keep-data para preservá-lo.

Caching de plugins e resolução de arquivos

Plugins são especificados de duas maneiras:

• Através de claude --plugin-dir ou claude --plugin-url, pela duração de uma sessão.
• Através de um marketplace, instalado para futuras sessões.

Para fins de segurança e verificação, Claude Code copia plugins de marketplace para o cache de plugins local do usuário (~/.claude/plugins/cache) em vez de usá-los no local, exceto para fontes command em link mode, que Claude Code usa no local através de links na entrada do cache.

Para plugins copiados, cada versão instalada é um diretório separado no cache, agrupado por marketplace e plugin e nomeado para a versão resolvida, com sua própria cópia dos arquivos do plugin e dependências de pacotes Node.js. Uma dependência resolvida de uma tag de release obtém um nome de diretório com um sufixo de commit-SHA.

Quando você atualiza ou desinstala um plugin, Claude Code marca o diretório da versão anterior como órfão e o remove em uma varredura de fundo aproximadamente 14 dias depois. O período de carência permite que sessões concorrentes de Claude Code que já carregaram a versão antiga continuem funcionando sem erros. Claude Code executa a varredura apenas enquanto pelo menos um plugin está instalado; depois que você desinstala seu último plugin, diretórios órfãos permanecem no disco até que você instale um plugin novamente.

Claude Code remove uma pasta de plugin ou marketplace do cache apenas quando ela não contém mais nenhum diretório ou symlink. Se você criar um symlink de um checkout de desenvolvimento no cache como uma entrada de versão do plugin, Claude Code nunca marca o link como órfão e nunca o remove ou as pastas que o contêm. Claude Code também nunca escreve seus arquivos de rastreamento de versão dentro do checkout vinculado.

As ferramentas Glob e Grep do Claude pulam diretórios de versão órfãos durante buscas, portanto os resultados de arquivo não incluem código de plugin desatualizado.

Dependências de pacotes Node.js

Quando Claude Code copia um plugin para o cache, ele também instala as dependências de pacotes Node.js do plugin lá, para que os hooks e servidores MCP do plugin possam carregá-los. 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, consulte versões de dependência de plugin.

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, e no início da sessão quando um plugin habilitado ainda não está em cache, como em uma máquina nova. A instalação é executada apenas quando o diretório raiz do plugin contém tanto um package.json quanto um lockfile suportado:

Se um plugin contiver 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 yarn.lock e pnpm-lock.yaml porque Yarn e pnpm suportam hooks de configuração em tempo de resolução que contornam --ignore-scripts.

Envie um lockfile npm para o alcance mais amplo. Claude Code executa o gerenciador de pacotes do lockfile correspondente do PATH do usuário e não volta para o outro lockfile se estiver faltando. Para um plugin distribuído através de uma fonte npm, use npm-shrinkwrap.json; npm exclui package-lock.json de pacotes publicados.

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 impede que scripts preinstall, install e postinstall sejam executados, para que dependências que compilam módulos nativos nesses scripts façam download mas não compilem durante essa instalação.
• Timeout de 60 segundos: Claude Code para uma instalação que é executada por mais tempo e a trata como falha.

Buscar um plugin de fonte npm executa npm install com scripts de ciclo de vida habilitados, antes dessa instalação de dependência ser executada.

Uma instalação falhada ou ignorada nunca bloqueia o plugin. Quando a instalação falha, ou Claude Code pula um lockfile yarn ou pnpm, ele registra o motivo como um aviso na saída de debug. Um plugin com um package.json e nenhum lockfile é ignorado sem uma entrada de log. Uma instalação com timeout pode deixar uma árvore node_modules parcial na cópia em cache.

Você não pode desativar a instalação automática; nenhuma configuração ou variável de ambiente a desativa. Em redes restritas, consulte os requisitos de acesso à rede para os hosts a permitir.

Para dependências que a instalação automática não pode fornecer, como pacotes que precisam de seus scripts de ciclo de vida para compilar, dependências Python, ou um plugin bloqueado com Yarn ou pnpm, instale-os a partir de um hook no diretório de dados persistentes.

Limitações de travessia de caminho

Claude Code não permite que um plugin referencie arquivos fora de seu próprio diretório. Ele rejeita um caminho de componente que se resolve fora da raiz do plugin, seja o caminho declarado em plugin.json ou em uma entrada de marketplace. Isso cobre um caminho que aponta para fora do plugin conforme escrito, como ../shared-utils, e um symlink que leva para fora do plugin, exceto links dentro de um marketplace.

Em macOS e Linux, Claude Code também rejeita um caminho de componente que contém uma barra invertida em qualquer lugar, mesmo quando o caminho permanece dentro do plugin. Componentes declarados com caminhos de barra invertida, portanto, carregam apenas no Windows. Escreva caminhos de componentes com barras normais, como ./commands/deploy.md.

Quando Claude Code rejeita um caminho, ele relata um erro path escapes plugin directory e carrega o plugin sem esse componente.

Claude Code também não copia arquivos fora do diretório do plugin para o cache quando instala o plugin, portanto quando um script dentro de um plugin copiado lê um caminho acima da raiz do plugin, ele não encontra esses arquivos também.

Compartilhar arquivos dentro de um marketplace com symlinks

Se seu plugin precisar compartilhar arquivos com outras partes do mesmo marketplace, você pode criar links simbólicos dentro do diretório do seu plugin. Como um symlink é tratado quando o plugin é copiado para o cache depende de onde seu alvo se resolve:

• 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. Isso impede que plugins puxem arquivos arbitrários do host, como caminhos do sistema, para o cache.

Para plugins instalados com --plugin-dir, de um caminho local, ou de uma fonte command em copy mode, apenas symlinks que se resolvem dentro do próprio diretório do plugin são preservados. Todos os outros são ignorados.

O comando a seguir cria um link de dentro de um plugin de marketplace para uma skill compartilhada definida por um plugin irmão. No Windows, use mklink /D de um Prompt de Comando elevado ou ative o Modo de Desenvolvedor:

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

Estrutura de diretório do plugin

Layout padrão do plugin

Um plugin completo segue esta estrutura:

enterprise-plugin/
├── .claude-plugin/           # Diretório de metadados (opcional)
│   └── plugin.json             # manifesto do plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills como arquivos .md simples
│   ├── status.md
│   └── logs.md
├── agents/                   # Definições de subagentes
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Scripts de fluxo de trabalho
│   └── release-audit.js
├── output-styles/            # Definições de estilo de saída
│   └── terse.md
├── themes/                   # Definições de tema de cor
│   └── dracula.json
├── monitors/                 # Configurações de monitor de fundo
│   └── monitors.json
├── hooks/                    # Configurações de hooks
│   ├── hooks.json           # Configuração principal de hooks
│   └── security-hooks.json  # Hooks adicionais
├── bin/                      # Executáveis do plugin adicionados ao PATH
│   └── my-tool               # Invocável como comando simples na ferramenta Bash
├── settings.json            # Configurações padrão para o plugin
├── .mcp.json                # Definições de servidor MCP
├── .lsp.json                # Configurações de servidor LSP
├── scripts/                 # Scripts de hooks e utilitários
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Arquivo de licença
└── CHANGELOG.md             # Histórico de versões

Um arquivo CLAUDE.md na raiz do plugin não é carregado como contexto do projeto. Os plugins contribuem contexto através de skills, agentes e hooks em vez de CLAUDE.md. Para enviar instruções que sejam carregadas no contexto do Claude, coloque-as em uma skill.

Referência de localizações de arquivo

Referência de comandos CLI

Claude Code fornece comandos CLI para gerenciamento de plugins não interativo, útil para scripts e automação.

plugin init

Crie um novo plugin em ~/.claude/skills/<name>/. Na próxima sessão do Claude Code, ele carrega automaticamente como <name>@skills-dir e aparece em /plugin e claude plugin list sem necessidade de etapa de instalação.

Consulte Skills-directory plugins para requisitos de escopo e confiança.

claude plugin init <name> [options]

Argumentos:

• <name>: Nome do plugin. Torna-se o namespace da skill e o nome do diretório em ~/.claude/skills/, portanto não pode conter espaços ou separadores de caminho.

Opções:

Aliases: new

Cada valor --with adiciona um arquivo inicial para esse componente, pronto para editar:

O plugin criado usa a fonte @skills-dir em vez de um marketplace. Administradores podem bloquear essa fonte com strictKnownMarketplaces ou adicionando {"source": "skills-dir"} a blockedMarketplaces em managed settings. Quando bloqueado, plugin init falha antes de escrever.

Exemplos:

# Crie um plugin mínimo
claude plugin init my-helper

# Crie com pastas de skill e hook
claude plugin init my-helper --with skills hooks

# Sobrescreva um scaffold existente
claude plugin init my-helper --force

plugin install

Instale um plugin dos marketplaces disponíveis.

claude plugin install <plugin> [options]

Argumentos:

• <plugin>: Nome do plugin ou plugin-name@marketplace-name para um marketplace específico

Opções:

O escopo determina qual arquivo de configurações o plugin instalado é adicionado. Por exemplo, --scope project escreve em enabledPlugins em .claude/settings.json, tornando o plugin disponível para todos que clonam o repositório do projeto.

Exemplos:

# Instale no escopo do usuário (padrão)
claude plugin install formatter@my-marketplace

# Instale no escopo do projeto (compartilhado com a equipe)
claude plugin install formatter@my-marketplace --scope project

# Instale no escopo local (não compartilhado com a equipe)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Remova um plugin instalado.

claude plugin uninstall <plugin> [options]

Argumentos:

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

Opções:

Aliases: remove, rm

Por padrão, desinstalar do último escopo restante também exclui o diretório ${CLAUDE_PLUGIN_DATA} do plugin. Use --keep-data para preservá-lo, por exemplo ao reinstalar após testar uma nova versão.

plugin prune

Remova dependências de plugin auto-instaladas que não são mais necessárias por nenhum plugin instalado. Dependências que Claude Code puxou para satisfazer o campo dependencies de outro plugin são removidas; plugins que você instalou diretamente nunca são tocados.

claude plugin prune [options]

Opções:

Aliases: autoremove

O comando lista dependências órfãs e pede confirmação antes de removê-las. Para remover um plugin e limpar suas dependências em uma etapa, execute claude plugin uninstall <plugin> --prune.

plugin enable

Ative um plugin desativado. Quando o destino é instalado de um marketplace e declara dependencies, Claude Code os ativa transitivamente no mesmo escopo. O comando falha sob as condições que Enable or disable a plugin with dependencies lista.

claude plugin enable <plugin> [options]

Argumentos:

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

Opções:

plugin disable

Desative um plugin sem desinstalá-lo. Quando o destino é instalado de um marketplace, o comando falha se outro plugin ativado depends on ele. A mensagem de erro inclui um comando encadeado que desativa cada dependente primeiro.

claude plugin disable [plugin] [options]

Argumentos:

• [plugin]: Nome do plugin ou plugin-name@marketplace-name. Opcional ao usar --all

Opções:

plugin update

Atualize um plugin para a versão mais recente.

claude plugin update <plugin> [options]

Argumentos:

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

Opções:

plugin list

Liste plugins instalados com sua versão, marketplace de origem e status de ativação.

claude plugin list [options]

Opções:

Dentro de uma sessão interativa, /plugin list imprime uma listagem similar inline, mas cobre apenas plugins instalados do marketplace:

• Plugins carregados de diretórios de skills aparecem na interface /plugin e em claude plugin list, mas não na saída inline /plugin list.
• No Claude Code v2.1.239 ou posterior, plugins sincronizados de claude.ai aparecem em claude plugin list quando você o executa no ambiente onde uma sessão sincronizada os baixou. Eles não aparecem na saída inline /plugin list.
• Plugins carregados para a sessão com --plugin-dir ou --plugin-url aparecem na interface /plugin e em claude plugin list apenas quando a mesma flag precede o subcomando, como em claude --plugin-dir <dir> plugin list. Apenas o nome da flag nomeia sua localização, portanto um claude plugin list simples não consegue encontrá-los, diferentemente de plugins sincronizados e plugins de diretório de skills, cujos diretórios fixos Claude Code verifica.

O formulário interativo aceita --enabled ou --disabled para mostrar apenas plugins nesse estado, e ls como abreviação para list.

plugin details

Mostre o inventário de componentes de um plugin e o custo de token projetado. A saída lista todos os componentes que o plugin contribui, agrupados como Skills, Agents, Hooks, servidores MCP e servidores LSP, junto com uma estimativa de quantos tokens ele adiciona a cada sessão. O grupo Skills inclui entradas skills/ e commands/.

claude plugin details <name>

Argumentos:

• <name>: Nome do plugin ou plugin-name@marketplace-name

Opções:

A saída mostra dois números de custo para cada componente:

• Always-on: tokens adicionados a cada sessão pelo texto de listagem do plugin, como descrições de skills, descrições de agents e nomes de comandos, independentemente de qualquer componente disparar.
• On-invoke: tokens que um componente custa quando dispara. Mostrado por componente, não como total do plugin, porque uma sessão típica invoca apenas um subconjunto de componentes.

Este exemplo mostra como a saída se parece para um plugin com duas skills:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

O total always-on é calculado via API count_tokens para seu modelo ativo. Números por componente são proporcionalmente dimensionados a partir desse total. Se a API estiver inacessível, o comando volta para uma estimativa baseada em caracteres.

plugin validate

Verifique um plugin ou um marketplace para erros de sintaxe e esquema antes de publicar.

O comando sai com 0 quando a validação passa, 1 quando falha e 2 quando a própria execução de validação falha, como quando o caminho que você passa é ilegível.

claude plugin validate <path> [options]

Argumentos:

• <path>: Caminho para um diretório de plugin ou um diretório de marketplace. Consulte Validate a plugin or a directory without a manifest para quais arquivos uma execução de plugin cobre.

Opções:

Com --json, Claude Code escreve o relatório para stdout como um objeto JSON com estes campos de nível superior:

• success: o mesmo veredicto que o código de saída fornece
• strict: se a execução tratou avisos como erros
• target: o caminho resolvido que Claude Code validou
• manifest: o resultado do próprio manifesto, ou null para uma execução sem manifesto
• contents: resultados por arquivo, cada um nomeando seu file e carregando arrays errors, warnings e notes

Na saída 2, o comando não escreve nada para stdout; a mensagem de erro vai para stderr.

Dentro de uma sessão interativa, /plugin validate <path> executa as mesmas verificações inline.

plugin tag

Crie uma tag git de lançamento para um plugin. Por padrão, o comando marca o plugin no diretório atual; passe um caminho para marcar um plugin em outro lugar. Consulte Tag plugin releases.

claude plugin tag [path] [options]

Argumentos:

• [path]: Caminho para o diretório do plugin. Padrão é o diretório atual.

Opções:

Ferramentas de depuração e desenvolvimento

Comandos de depuração

Use claude --debug para ver detalhes do carregamento de plugins:

Isso mostra:

• Quais plugins estão sendo carregados
• Quaisquer erros nos manifestos de plugins
• Registro de skills, agents e hooks
• Inicialização do servidor MCP

Problemas comuns

Exemplos de mensagens de erro

Erros de validação de manifesto:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: verifique se há vírgulas ausentes, vírgulas extras ou strings sem aspas
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: um campo obrigatório está ausente
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: erro de sintaxe JSON. Antes da v2.1.246, Claude Code também produzia esse erro para um plugin.json salvo como UTF-8 com uma marca de ordem de byte (BOM) à frente, mesmo quando o JSON era válido.

Erros de carregamento de plugin:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: o caminho do comando existe mas não contém arquivos de comando válidos
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: o caminho source em marketplace.json aponta para um diretório inexistente
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: remova definições de componentes duplicadas ou remova strict: false na entrada do marketplace

Solução de problemas de hooks

Script de hook não executando:

1. Verifique se o script é executável: chmod +x ./scripts/your-script.sh
2. Verifique a linha shebang: A primeira linha deve ser #!/bin/bash ou #!/usr/bin/env bash
3. Verifique se o caminho usa ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Teste o script manualmente: ./scripts/your-script.sh

Hook não disparando em eventos esperados:

1. Verifique se o nome do evento está correto (sensível a maiúsculas): PostToolUse, não postToolUse
2. Verifique se o padrão do matcher corresponde às suas ferramentas: "matcher": "Write|Edit" para operações de arquivo
3. Confirme se o tipo de hook é válido: command, http, mcp_tool, prompt ou agent

Solução de problemas do servidor MCP

Servidor não iniciando:

1. Verifique se o comando existe e é executável
2. Verifique se todos os caminhos usam a variável ${CLAUDE_PLUGIN_ROOT}
3. Verifique os logs do servidor MCP: claude --debug mostra erros de inicialização
4. Teste o servidor manualmente fora do Claude Code

Ferramentas do servidor não aparecendo:

1. Certifique-se de que o servidor está configurado corretamente em .mcp.json ou plugin.json
2. Verifique se o servidor implementa o protocolo MCP corretamente
3. Verifique se há timeouts de conexão na saída de depuração

Erros de estrutura de diretório

Sintomas: Plugin carrega mas componentes (skills, agents, hooks) estão ausentes.

Estrutura correta: Componentes devem estar na raiz do plugin, não dentro de .claude-plugin/. Apenas plugin.json pertence a .claude-plugin/.

Lista de verificação de depuração:

1. Execute claude --debug e procure por mensagens "loading plugin"
2. Verifique se cada diretório de componente está listado na saída de depuração
3. Verifique se as permissões de arquivo permitem ler os arquivos do plugin

Referência de distribuição e versionamento

Gerenciamento de versão

Claude Code usa a versão do plugin como a chave de cache que determina se uma atualização está disponível. Quando você executa /plugin update ou a atualização automática é acionada, Claude Code calcula a versão atual e ignora a atualização se ela corresponder ao que já está instalado.

Para cada tipo de fonte, exceto command, Claude Code resolve a versão a partir do primeiro destes que está definido:

1. O campo version no plugin.json do plugin
2. O campo version na entrada do marketplace do plugin em marketplace.json
3. O SHA do commit git da fonte do plugin, para fontes github, url, git-subdir e relative-path em um marketplace hospedado em git
4. O resumo SHA-256, para fontes archive: o pin sha256 na entrada do marketplace, ou o resumo do arquivo baixado quando você não define um pin. Claude Code o encurta para os primeiros 12 caracteres
5. unknown, para fontes npm ou diretórios locais não dentro de um repositório git

Para uma fonte command, Claude Code sempre deriva a versão a partir do que o comando produziu: um hash de conteúdo de 12 caracteres por si só, ou anexado à versão plugin.json como <version>-<hash> quando um está definido. Claude Code ignora o campo version da entrada do marketplace para fontes de comando. Um comando cuja saída com hash muda, portanto, produz uma nova versão, mesmo quando a string de versão criada permanece a mesma. No modo link, o hash cobre o caminho real do diretório impresso e suas entradas de nível superior em vez do conteúdo do arquivo.

Para esses tipos de fonte, isso oferece três maneiras de versionar um plugin:

Se você usar versões explícitas, siga versionamento semântico (MAJOR.MINOR.PATCH): incremente MAJOR para mudanças significativas, MINOR para novos recursos, PATCH para correções de bugs. Documente as alterações em um CHANGELOG.md.

Veja também

• Plugins - Tutoriais e uso prático
• Marketplaces de plugins - Criando e gerenciando marketplaces
• Skills - Detalhes de desenvolvimento de skill
• Subagents - Configuração e capacidades de agent
• Hooks - Manipulação de eventos e automação
• MCP - Integração de ferramenta externa
• Configurações - Opções de configuração para plugins