Um plugin Claude Code é construído a partir de componentes, como skills, agentes, hooks e servidores MCP. Cada componente tem uma pasta padrão no plugin, uma chave de manifesto opcional em .claude-plugin/plugin.json que substitui ou adiciona àquela pasta, e um nome que o usuário vê. Para cada tabela de campos completa da chave, consulte a referência de manifesto.
Use esta página para adicionar um componente a um plugin que já carrega.
Depois de adicionar um componente, execute /reload-plugins em uma sessão em execução ou inicie uma nova para que Claude Code o carregue. Para verificar o arquivo do componente antes de carregá-lo, execute claude plugin validate . no seu shell a partir do diretório do plugin.
Explorar o diretório do plugin
O explorador mostra um plugin de exemplo, my-plugin, que tem um de cada tipo de componente em sua localização padrão:
Uma skill de revisão e um comando about
Um subagente de revisão de segurança
Um hook que formata arquivos após Claude editá-los, e a pasta scripts/ que ele chama
Um monitor de log
Um estilo de saída e um tema de cor
Um workflow de auditoria de rotas
Um executável hello-plugin
Configurações padrão
Um servidor MCP local e um servidor de linguagem Go
Cada arquivo é o menor exemplo válido de seu formato, lá para mostrar a forma em vez de ser útil: uma skill ou agente real carrega instruções completas e frequentemente arquivos de suporte, e um hook ou monitor real faz trabalho real. As seções após o explorador usam os mesmos arquivos que seus exemplos e vinculam a versões mais completas. Selecione um arquivo ou pasta para ler para que serve, veja o que entra nele e encontre a seção que o cobre.
O [manifesto](/docs/pt/plugins/manifest-reference) é o arquivo `plugin.json` no diretório `.claude-plugin/` de um plugin. Ele contém os metadados do plugin e os valores `userConfig` que Claude Code solicita ao usuário. Apenas `name` é obrigatório. Neste, `description` é o texto que os usuários veem para o plugin em `/plugin`, e `version` mantém os usuários nessa versão até você alterá-la:
```json theme={null}
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Review, formatting, and database tools for this team"
}
```
Uma [skill](/docs/pt/skills) é um arquivo `SKILL.md`. Salve cada skill em seu próprio diretório em `skills/`. Claude lê a `description` de cada skill, e quando o que o usuário pede corresponde a ela, como pedir a Claude para revisar um pull request aqui, Claude carrega as instruções da skill e as segue. O usuário também pode executá-la diretamente como `/my-plugin:review`:
```markdown theme={null}
---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---
Review the changed files. Report style problems first, then missing tests.
```
Um comando é um único arquivo Markdown que o usuário executa por nome. Comandos são o formato mais antigo: uma skill é executada por nome da mesma forma e também pode carregar arquivos de suporte em seu próprio diretório, então escreva novos como skills e mantenha `commands/` para arquivos que você já tem. Este arquivo se torna `/my-plugin:about` e usa o mesmo frontmatter que uma skill:
```markdown theme={null}
---
description: Summarize the repository
---
Summarize what this repository does in three sentences.
```
Um [subagente](/docs/pt/sub-agents) é um assistente separado, com suas próprias instruções e sua própria janela de contexto, que Claude pode delegar uma tarefa e obter um resultado. Cada arquivo Markdown em `agents/` define um: o frontmatter o nomeia e diz quando usá-lo, e o corpo é seu prompt do sistema. Este é nomeado `my-plugin:security-reviewer`, e o usuário pode invocá-lo com `@agent-my-plugin:security-reviewer`:
```markdown theme={null}
---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---
You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
```
Um [hook](/docs/pt/hooks-guide) executa algo automaticamente em um ponto do ciclo de vida do Claude Code, como após cada edição de arquivo: um comando shell, uma solicitação HTTP, uma chamada de ferramenta MCP, um prompt para um modelo ou um subagente. Salve os hooks do plugin em `hooks/hooks.json` na raiz do plugin. Este executa o `scripts/format.sh` do plugin após Claude escrever ou editar um arquivo:
Um monitor é um comando shell que Claude Code inicia em segundo plano quando a sessão inicia e mantém em execução até que termine, usando a [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool). O que ele imprime chega a Claude como notificações. Um campo `when` pode, em vez disso, iniciá-lo na primeira vez que uma skill nomeada é executada. Este monitora um log de erros:
Um plugin pode incluir [estilos de saída](/docs/pt/output-styles), que alteram como Claude formata e expressa suas respostas. Salve cada estilo de saída como `output-styles/.md`. Este aparece em `/output-style` como `my-plugin:terse`:
```markdown theme={null}
---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---
Keep every reply short. Skip preambles and summaries.
```
Um plugin pode incluir [temas de cor](/docs/pt/terminal-config#create-a-custom-theme) para a interface Claude Code. Salve cada tema como `themes/.json`. Este aparece em `/theme` como `Dracula`, marcado como de `my-plugin`:
A pasta `workflows/` contém arquivos `.js` de [workflow](/docs/pt/workflows): um bloco `meta`, depois um corpo de script que orquestra vários subagentes. Este é executado como `/my-plugin:audit-routes`:
`bin/` é como um plugin envia uma ferramenta de linha de comando. Enquanto o plugin está habilitado, Claude Code coloca esta pasta no `PATH` do shell em que executa comandos, para que Claude, ou as instruções de uma skill, possam executar a ferramenta por nome sem o usuário instalar nada. Com este [executável](#executables) em vigor, `hello-plugin` é um comando que Claude pode executar:
```bash theme={null}
#!/bin/bash
echo "hello from my-plugin"
```
O hook em `hooks/hooks.json` executa um script, e esta pasta é onde o exemplo o mantém. O nome `scripts/` é uma convenção, não algo que Claude Code procure: o hook aponta para o arquivo por seu caminho, `${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`. Um script de formatação pode parecer assim:
Um `settings.json` na raiz do plugin contém [configurações](/docs/pt/settings-reference) que se aplicam enquanto o plugin está habilitado, para que um plugin possa alterar como a sessão se comporta e não apenas adicionar componentes. Apenas duas chaves têm efeito de um plugin, [`agent`](/docs/pt/settings-reference#agent) e [`subagentStatusLine`](/docs/pt/settings-reference#subagentstatusline); todas as outras chaves são descartadas. Consulte [Configurações padrão](#default-settings).
Este define `agent`, que executa o thread principal da sessão como o agente `security-reviewer` do plugin, para que o prompt do sistema, restrições de ferramentas e modelo desse agente se apliquem a toda a sessão:
```json theme={null}
{
"agent": "security-reviewer"
}
```
Um [servidor MCP](/docs/pt/mcp) fornece a Claude ferramentas de um sistema externo. Declare-o em `.mcp.json` na raiz do plugin. Este inicia um servidor local a partir de um script dentro do plugin e aparece em `/mcp` como `plugin:my-plugin:db`:
Um servidor LSP fornece a Claude [diagnósticos e navegação de código](/docs/pt/plugins/code-intelligence) para uma linguagem. Declare o servidor em `.lsp.json` na raiz do plugin. Este conecta o servidor de linguagem Go para arquivos `.go`:
Cada seção abaixo cobre um tipo de componente: onde seus arquivos vão no plugin, um exemplo que valida, o que o usuário vê uma vez que o plugin carrega, e a chave de manifesto que altera a localização padrão. Adicione os que seu plugin precisa; nenhum é obrigatório.
Skills
Uma skill é um arquivo SKILL.md que Claude pode carregar quando sua descrição corresponde à tarefa. O usuário também pode executá-la como um comando. Salve cada skill em seu próprio diretório em skills/:
Dê ao SKILL.md uma description para que Claude saiba quando usá-la:
---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---
Review the changed files. Report style problems first, then missing tests.
Depois de carregar o plugin, /my-plugin:review executa a skill. O nome do comando e quem pode invocá-lo seguem estas regras:
Nome do comando: /<plugin>:<directory>, então skills/review/SKILL.md em my-plugin é /my-plugin:review. Se você definir name no frontmatter, ele substitui o último segmento e o prefixo do plugin permanece. Consulte como uma skill obtém seu nome de comando
Você também pode colocar skills fora do diretório padrão skills/:
Diretórios adicionais: liste-os na chave de manifesto skills. Eles adicionam à varredura padrão skills/ em vez de substituí-la, diferentemente de commands e agents
Uma única skill na raiz do plugin: sem diretório skills/ e sem chave de manifesto skills, um SKILL.md na raiz do plugin carrega como uma skill. Defina name em seu frontmatter, porque caso contrário uma instalação de marketplace nomeia a skill após seu diretório de cache em vez de seu plugin
Para incluir instruções em um plugin, escreva-as como uma skill. Claude Code não carrega um CLAUDE.md na raiz do plugin, e claude plugin validate avisa CLAUDE.md at the plugin root is not loaded as project context.
Para campos de frontmatter e arquivos de suporte, consulte Skills.
Comandos
Um comando é um único arquivo Markdown que o usuário executa por nome, como /my-plugin:about.
Salve um comando em commands/<file>.md e ele se torna /<plugin>:<file>. Um subdiretório adiciona um segmento, então commands/db/migrate.md é /my-plugin:db:migrate.
Arquivos de comando usam o mesmo frontmatter que skills.
Definir comandos no manifesto
Você só precisa disso se quiser manter arquivos de comando em algum lugar diferente de commands/, ou para definir um comando curto dentro de plugin.json sem um arquivo Markdown separado. Defina a chave de manifesto commands, e Claude Code a lê em vez de varrer commands/. A chave usa um caminho, uma matriz de caminhos ou um objeto que mapeia cada nome de comando para um arquivo source ou content inline.
Este manifesto define /my-plugin:about inline, sem arquivo Markdown:
{"name": "my-plugin",
"commands": {"about": {"content": "Summarize what this repository does in three sentences.",
"description": "Summarize the repository"}}}
Carregue o plugin e execute /my-plugin:about na sessão para confirmar que carregou.
Para a sintaxe completa da chave, consulte commands.
Agentes
Um subagente é um assistente separado, com suas próprias instruções e janela de contexto, que Claude pode delegar uma tarefa. Cada arquivo Markdown em agents/ define um:
---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---
You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
Este agente é nomeado my-plugin:security-reviewer, e o usuário pode invocá-lo explicitamente com @agent-my-plugin:security-reviewer. A forma do nome é <plugin>:<name>, onde <name> vem do frontmatter, ou do nome do arquivo quando não há.
A chave agents substitui a varredura agents/.
Organizar agentes em subpastas
Você pode colocar arquivos de agente do plugin em subpastas de agents/. Claude Code os carrega recursivamente e une o nome do plugin, cada nome de subpasta e o nome do arquivo com dois-pontos para formar o nome com escopo do agente. Por exemplo, agents/review/security.md em um plugin nomeado my-plugin carrega como my-plugin:review:security. Duas configurações alteram esse nome:
Frontmatter name: ele substitui apenas o nome do arquivo, então name: audit em agents/review/security.md carrega como my-plugin:review:audit
Campo de manifesto agents: um arquivo que você lista lá carrega sem nomes de subpasta, então "agents": "./custom/review/security.md" carrega como my-plugin:security
Campos de frontmatter em agentes de plugin
O frontmatter de um agente de plugin segue estas regras:
Campos suportados: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color e a chave cacheTtl de experimental. O único valor isolation válido é "worktree". Consulte campos de frontmatter suportados para saber o que cada um faz
Campos ignorados: permissionMode, hooks, mcpServers e initialPrompt. Um arquivo de agente não pode adicionar hooks ou servidores MCP por conta própria, então adicione-os como plugin hooks e servidores MCP em vez disso
Frontmatter que não analisa: o agente ainda carrega com cada campo ignorado. É nomeado após o arquivo, e sua descrição lê Agent from my-plugin plugin. Execute claude plugin validate no seu shell para encontrar esses arquivos
Para saber o que cada campo faz e as regras de precedência, consulte Subagentes.
Hooks
Um hook executa algo automaticamente em um ponto do ciclo de vida do Claude Code, como após cada edição de arquivo: um comando shell, uma solicitação HTTP, uma chamada de ferramenta MCP, um prompt para um modelo ou um subagente. Salve os hooks do plugin em hooks/hooks.json na raiz do plugin, sob uma chave "hooks" de nível superior, na mesma forma que o objeto hooks em settings.json. Isso permite copiar um hook de configurações existente sem alterações.
Este hook executa um script agrupado após cada Write ou Edit:
Salve o script em scripts/format.sh e torne-o executável.
Carregue o plugin e peça a Claude para editar um arquivo. Um hook PostToolUse que sai com 0 não mostra nada na transcrição, então confirme que foi executado com log de depuração ou pelo que o script em si altera.
Hooks em hooks/hooks.json e na chave de manifesto hooks ambos carregam. Para cada evento e sua carga útil, consulte Eventos de hook.
Quando os hooks do plugin disparam
Os hooks de um plugin não esperam que uma das skills ou comandos do plugin seja usada. Claude Code os registra quando uma sessão carrega o plugin, e eles disparam em seus eventos a partir de então. Para limitar quando um hook é executado, restrinja seu matcher.
Ambiente, citação e correspondência de ferramentas MCP
O ambiente do hook, a citação de ${CLAUDE_PLUGIN_ROOT} e os matchers para as próprias ferramentas MCP do plugin funcionam da seguinte forma:
Ambiente: cada processo de hook recebe CLAUDE_PLUGIN_ROOT e CLAUDE_PLUGIN_DATA em seu ambiente, mais CLAUDE_PLUGIN_OPTION_<KEY> para cada valor de configuração do usuário, para que seu script possa lê-los de lá
Citação: quando command não tem args, ele é executado através de um shell, então envolva o caminho ${CLAUDE_PLUGIN_ROOT} em aspas duplas, como o exemplo hooks/hooks.json em Hooks faz, para manter o caminho expandido como uma palavra de shell. Quando você passa args em vez disso, cada elemento é passado como um argumento sem shell e não precisa de citação. Consulte forma exec e forma shell
Correspondência das próprias ferramentas MCP do plugin: uma ferramenta de um servidor MCP que este plugin declara é nomeada mcp__plugin_<plugin>_<server>__<tool>, então escreva esse nome completo no matcher. Um matcher apenas no nome do servidor nunca dispara. Consulte Corresponder ferramentas MCP
Servidores MCP
Um servidor MCP fornece a Claude ferramentas de um sistema externo. Declare-o em .mcp.json na raiz do plugin, na mesma forma que um .mcp.json de projeto. Este .mcp.json declara um servidor nomeado db:
Você também pode omitir o wrapper mcpServers e colocar db no nível superior do arquivo.
Carregue o plugin e execute /mcp para confirmar que o servidor aparece como plugin:my-plugin:db.
claude plugin validate verifica .mcp.json e relata uma entrada de servidor que Claude Code descartaria no tempo de carregamento como um erro. Requer Claude Code v2.1.281 ou posterior.
A chave de manifesto mcpServers usa um mapa de servidor inline, um caminho para um arquivo JSON ou uma matriz daqueles. Quando um servidor de manifesto tem o mesmo nome que um em .mcp.json, o servidor de manifesto o substitui.
Alcançar usuários em claude.ai e Cowork
Um servidor stdio local, como o servidor db em Servidores MCP, é executado em Claude Code e em uma sessão Cowork que é executada em sua máquina no aplicativo Claude Desktop, mas não em claude.ai. Para alcançar usuários lá também, referencie um servidor remoto por sua URL https://, que claude.ai e Cowork oferecem ao usuário como um conector.
Nomes de servidor, nomes de ferramentas e recarregamentos
Os nomes do servidor, substituição de variáveis e comportamento de recarga seguem estas regras:
Nome do servidor: plugin:<plugin>:<server>, então o servidor db em my-plugin é plugin:my-plugin:db em /mcp. Use a mesma forma para nomear o servidor em um hook mcp_tool
Nomes de ferramentas: mcp__plugin_<plugin>_<server>__<tool>, então uma ferramenta query naquele servidor db é mcp__plugin_my-plugin_db__query. Esse é o nome a usar em regras de permissão e matchers de hook
Substituição: ${CLAUDE_PLUGIN_ROOT} e as outras variáveis de caminho são substituídas em command, args e env. Nenhuma citação é necessária em args, porque cada elemento é passado como um argumento
Recarga: quando o usuário executa /reload-plugins e o recarga se aplica, um servidor cuja configuração não foi alterada mantém sua conexão. Um servidor cuja configuração mudou se reconecta, e um que você removeu se desconecta
Incluir um servidor MCPB empacotado
A chave mcpServers também aceita um servidor empacotado como um arquivo MCPB, cuja extensão é .mcpb ou a mais antiga .dxt. Aponte a chave para o arquivo, como um caminho dentro do plugin ou uma URL https://:
Um servidor LSP fornece a Claude diagnósticos e navegação de código para uma linguagem. Se um plugin oficial de inteligência de código já cobre sua linguagem, instale esse em vez de escrever um. Caso contrário, declare o servidor em .lsp.json na raiz do plugin:
O arquivo mapeia cada nome de servidor diretamente para sua configuração, sem objeto wrapper ao redor do mapa. command é o nome do binário, com seus argumentos em args. extensionToLanguage precisa de pelo menos uma extensão, cada uma começando com ..
claude plugin validate não lê este arquivo. Quando qualquer entrada é inválida, o arquivo inteiro é ignorado no carregamento e Invalid LSP server config for ".lsp.json" aparece na aba Errors de /plugin.
Seu plugin configura a conexão mas não instala o binário do servidor, e cada extensão de arquivo obtém um servidor:
Binário ausente: Claude Code inicia command por nome do PATH do usuário. Quando o binário não está lá, o servidor falha ao iniciar e claude --debug registra LSP server <name> failed to start
Conflitos de extensão: quando dois servidores habilitados reivindicam a mesma extensão, o primeiro registrado manipula esses arquivos e o outro não é usado para eles, se os servidores vêm de um plugin ou dois. A aba Errors de /plugin mostra o aviso LSP server "<name>" is not used for <ext> files
A chave de manifesto lspServers usa o mesmo mapa inline, um caminho para um arquivo JSON ou uma matriz daqueles, e seus servidores adicionam aos em .lsp.json. Quando um servidor de manifesto tem o mesmo nome que um em .lsp.json, o servidor de manifesto o substitui.
Para transport, timeouts, reinicializações e os outros campos, consulte lspServers.
Envie a 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 depuração.
Executáveis
Arquivos em bin/ na raiz do plugin estão no PATH do shell da ferramenta Bash enquanto o plugin está habilitado, para que Claude possa executá-los como comandos simples. Adicione um script executável:
#!/bin/bashecho"hello from my-plugin"
Torne-o executável com chmod +x bin/hello-plugin e carregue o plugin. Quando você pede a Claude para executar hello-plugin, o resultado da ferramenta Bash mostra a saída do script.
Diretórios bin/ de plugin vêm após as entradas PATH do próprio usuário, então um plugin não pode sombrear git, ls ou outro comando do sistema.
Para definir padrões que se aplicam enquanto o plugin está habilitado, adicione um settings.json na raiz do plugin, ou coloque o mesmo objeto inline na chave de manifesto settings. Duas chaves têm efeito, agent e subagentStatusLine, e todas as outras chaves são descartadas.
Defina agent para executar um dos próprios agentes do plugin como o thread principal:
{"agent": "security-reviewer"}
Carregue o plugin e inicie uma sessão. Claude então responde na conversa principal com o prompt do sistema e modelo do agente security-reviewer.
Quando a mesma chave é definida em mais de um lugar, estas regras decidem qual valor se aplica:
Arquivo sobre manifesto: quando ambos existem e settings.json define pelo menos uma chave suportada, settings.json se aplica e o settings do manifesto é ignorado
Configurações do usuário sobre padrões do plugin: entre fontes de configurações, padrões de plugin são a camada mais baixa, então um agent próprio do usuário em ~/.claude/settings.json substitui o seu
Dois plugins definem a mesma chave: o valor do plugin carregado por último se aplica, e claude --debug registra overrides setting
Um plugin pode incluir temas de cor e estilos de saída. Ambos aparecem nos mesmos seletores que os do usuário. Para qualquer um, definir a chave de manifesto substitui a varredura de pasta.
Um canal permite que um sistema externo, como um aplicativo de chat, envie mensagens para uma sessão. Em um plugin, um canal é um dos servidores MCP mais uma entrada channels que se vincula a ele e pode solicitar sua própria configuração. Este manifesto vincula um canal a um servidor telegram e solicita um token de bot:
server deve corresponder a uma chave em mcpServers. O userConfig por canal usa a mesma forma que a chave userConfig de nível superior.
Para o que o servidor deve implementar e como os usuários habilitam um plugin de canal, consulte Empacotar como um plugin na referência de canais. Para a tabela de campos, consulte channels.
Monitores
Um monitor é um comando shell que é executado em segundo plano para toda a sessão. O que ele imprime chega a Claude como notificações, para que Claude possa reagir a um log ou mudança de status sem ser solicitado a observá-lo. Salve as entradas em monitors/monitors.json:
O comando é executado em um shell, no diretório de trabalho em que a sessão foi iniciada.
O comando de um monitor é limitado em onde inicia e o que pode referenciar:
Apenas sessões interativas: monitores de plugin iniciam em uma sessão interativa e nunca em modo não-interativo com a flag -p. Eles também iniciam apenas onde a ferramenta Monitor está disponível
Sem configuração do usuário: command obtém as variáveis de caminho e ${ENV_VAR} do ambiente, mas nunca ${user_config.*}. Um monitor que referencia um não inicia, e processos de monitor não recebem CLAUDE_PLUGIN_OPTION_<KEY> também
Desabilitação no meio da sessão: se você desabilitar um plugin no meio da sessão, Claude Code não para monitores que já estão em execução. Eles param quando a sessão termina
A chave de manifesto experimental.monitors usa a mesma matriz inline ou um caminho para um arquivo JSON, e é lida em vez de monitors/monitors.json.
Para o gatilho when e os outros campos, consulte monitors.
Solicitar ao usuário valores de configuração
Declare os valores que seu plugin precisa do usuário na chave de manifesto userConfig, para que os usuários não editem settings.json eles mesmos. Cada opção aparece em um diálogo com seu title como o rótulo e sua description abaixo.
Defina "sensitive": true para um token ou senha. O diálogo então mascara a entrada, e o valor é armazenado em armazenamento seguro em vez de settings.json.
Este manifesto solicita um endpoint e um token:
{"name": "my-plugin",
"userConfig": {"api_url": {"type": "string",
"title": "API URL",
"description": "Base URL of your team's API"},
"api_token": {"type": "string",
"title": "API token",
"description": "Token for your team's API",
"sensitive": true
}}}
Quando o diálogo de configuração aparece
O diálogo aparece apenas na interface interativa /plugin. Ele abre para qualquer opção que ainda não está definida quando o usuário faz qualquer um dos seguintes:
Instala o plugin em /plugin
Executa /plugin install <plugin>@<marketplace> dentro de uma sessão
Habilita o plugin da aba Installed em /plugin
Para abrir o mesmo diálogo a qualquer momento, o usuário executa /plugin configure <plugin>@<marketplace>.
O comando shell claude plugin install nunca solicita valores userConfig. Para definir valores do shell, passe cada um como --config KEY=VALUE. Quando opções permanecem indefinidas, o comando imprime uma linha userConfig options not yet set que nomeia ambas as formas de defini-las. O diálogo userConfig nunca aparece cita a linha.
Para os campos de opção, onde cada valor é armazenado, como um componente referencia um valor salvo e quais campos rejeitam ${user_config.*}, consulte Configuração do usuário.
Referenciar caminhos de plugin e armazenar dados
Você não sabe onde seu plugin será instalado, então refira-se a seus arquivos e dados através destas variáveis em vez de caminhos fixos. Elas são substituídas em conteúdo de skill, comando e agente, em comandos de hook e monitor, e em configurações de servidor MCP e LSP. Elas também são exportadas para processos de hook, MCP e LSP:
${CLAUDE_PLUGIN_ROOT}: o diretório de instalação do plugin. Cada versão tem seu próprio diretório de cache, então o caminho muda quando o plugin é atualizado. Não escreva estado lá
${CLAUDE_PLUGIN_DATA}: um diretório que sobrevive a atualizações, para node_modules, ambientes virtuais e caches. Ele se resolve para ~/.claude/plugins/data/<id>/ e é criado quando primeiro referenciado
${CLAUDE_PROJECT_DIR}: a raiz do projeto, o mesmo valor que hooks recebem
No caminho do diretório de dados, <id> é o identificador do plugin com cada caractere diferente de letras, dígitos, _ e - substituído por -, então my-plugin@my-marketplace se torna my-plugin-my-marketplace.
No Windows, os caminhos substituídos usam barras para frente para que um shell não leia barras invertidas como escapes.
Instalar dependências no diretório de dados
Para um plugin instalado no marketplace, Claude Code instala dependências de pacote Node.js elegíveis automaticamente quando armazena em cache o plugin, então você pode não precisar instalá-las você mesmo. Quando você faz, este hook SessionStart instala node_modules em ${CLAUDE_PLUGIN_DATA} na primeira execução e novamente após uma atualização alterar package.json:
Após a primeira sessão, ~/.claude/plugins/data/<id>/node_modules existe. Um servidor MCP pode então definir NODE_PATH para ${CLAUDE_PLUGIN_DATA}/node_modules em seu env. Para quais campos substituem qual variável, consulte Variáveis de ambiente.
953Um plugin pode incluir temas de cor e estilos de saída. Ambos aparecem nos mesmos seletores que os do usuário. Para qualquer um, definir a chave de manifesto substitui a varredura de pasta.953Um plugin pode incluir temas de cor e estilos de saída. Ambos aparecem nos mesmos seletores que os do usuário. Para qualquer um, definir a chave de manifesto substitui a varredura de pasta.
954954
955| Componente | Salvar como | Formato | Aparece em | Chave de manifesto |955| Componente | Salvar como | Formato | Aparece em | Chave de manifesto |
957| Tema | `themes/<slug>.json` | O formato de [arquivo de tema personalizado](/docs/pt/terminal-config#create-a-custom-theme) que os usuários escrevem em `~/.claude/themes/` | `/theme`, sob o `name` do arquivo | `experimental.themes` |957| Tema | `themes/<slug>.json` | O formato de [arquivo de tema personalizado](/docs/pt/terminal-config#create-a-custom-theme) que os usuários escrevem em `~/.claude/themes/` | `/theme`, sob o `name` do arquivo | `experimental.themes` |
958| Estilo de saída | `output-styles/<name>.md` | O formato de [estilo de saída personalizado](/docs/pt/output-styles#create-a-custom-output-style), com frontmatter `name` e `description` | `/output-style`, como `<plugin>:<name>` | `outputStyles` |958| Estilo de saída | `output-styles/<name>.md` | O formato de [estilo de saída personalizado](/docs/pt/output-styles#create-a-custom-output-style), com frontmatter `name` e `description` | `/output-style`, como `<plugin>:<name>` | `outputStyles` |