File Deleted
View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Referência de plugins
6
7> Referência técnica completa para o sistema de plugins do Claude Code, incluindo esquemas, comandos CLI e especificações de componentes.
8
9<Tip>
10 Procurando instalar plugins? Veja [Descobrir e instalar plugins](/docs/pt/discover-plugins). Para criar plugins, veja [Plugins](/docs/pt/plugins). Para distribuir plugins, veja [Marketplaces de plugins](/docs/pt/plugin-marketplaces).
11</Tip>
12
13Um **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.
14
15<h2 id="plugin-components-reference">
16 Referência de componentes de plugin
17</h2>
18
19<h3 id="skills">
20 Skills
21</h3>
22
23Os plugins adicionam skills ao Claude Code, criando atalhos `/name` que você ou Claude podem invocar.
24
25**Localização**: diretório `skills/` ou `commands/` na raiz do plugin, ou um único arquivo `SKILL.md` na raiz do plugin
26
27**Formato de arquivo**: Skills são diretórios com `SKILL.md`; commands são arquivos markdown simples
28
29**Estrutura de skill**:
30
31```text theme={null}
32skills/
33├── pdf-processor/
34│ ├── SKILL.md
35│ ├── reference.md (opcional)
36│ └── scripts/ (opcional)
37└── code-reviewer/
38 └── SKILL.md
39```
40
41Skills e commands são descobertos automaticamente quando o plugin é instalado.
42
43Se 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. Para um plugin [copiado para o cache](#plugin-caching-and-file-resolution), esse nome é 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.
44
45Em 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`.
46
47Para detalhes completos, consulte [Skills](/docs/pt/skills).
48
49<h3 id="agents">
50 Agents
51</h3>
52
53Os plugins podem fornecer subagentes especializados para tarefas específicas que Claude pode invocar automaticamente quando apropriado.
54
55**Localização**: diretório `agents/` na raiz do plugin
56
57**Formato de arquivo**: Arquivos markdown descrevendo capacidades do agent
58
59**Estrutura de agent**:
60
61```markdown theme={null}
62name: agent-name
63description: O que este agent se especializa e quando Claude deve invocá-lo
64model: sonnet
65effort: medium
66maxTurns: 20
67disallowedTools: Write, Edit
68
69Prompt de sistema detalhado para o agent descrevendo seu papel, expertise e comportamento.
70```
71
72<h4 id="plugin-agent-frontmatter">
73 Frontmatter de agent de plugin
74</h4>
75
76Um arquivo de agent de plugin usa os mesmos [campos frontmatter que um arquivo de subagent](/docs/pt/sub-agents#supported-frontmatter-fields), exceto que Claude Code honra apenas alguns deles quando o agent vem de um plugin:
77
78* **Suportados**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color` e `experimental`. O único valor válido de `isolation` é `"worktree"`.
79* **Não suportados, por razões de segurança**: `hooks`, `mcpServers` e `permissionMode`. Claude Code ignora estes quando carrega um agent de um plugin. Para usá-los, copie o arquivo de agent para `.claude/agents/` ou `~/.claude/agents/`.
80* **Não suportados**: `initialPrompt`.
81
82Você pode colocar arquivos de agent de plugin em subpastas de `agents/`. Claude Code [os carrega recursivamente](/docs/pt/sub-agents#choose-the-subagent-scope) 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 agent. Por exemplo, `agents/review/security.md` em um plugin chamado `my-plugin` carrega como `my-plugin:review:security`. Duas configurações mudam esse nome:
83
84* Frontmatter `name`: ele substitui apenas o nome do arquivo, então `name: audit` em `agents/review/security.md` carrega como `my-plugin:review:audit`
85* Campo manifest [`agents`](#component-path-fields): um arquivo que você lista lá carrega sem nomes de subpasta, então `"agents": "./custom/review/security.md"` carrega como `my-plugin:security`
86
87Claude Code carrega um agent de plugin mesmo quando seu frontmatter não tem `name` ou não faz parse:
88
89* 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`
90* 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
91
92Em contraste, Claude Code pula um arquivo de project, user ou managed agent cujo frontmatter não tem `name` ou não faz parse.
93
94Para 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:
95
96* Um plugin com manifest: `claude plugin validate ./my-plugin`
97* Um plugin sem manifest: `claude plugin validate ./my-plugin/agents`. Requer Claude Code v2.1.233 ou posterior.
98
99Agents aparecem na [typeahead de @-mention](/docs/pt/sub-agents#invoke-subagents-explicitly) sob seu nome com escopo, como `my-plugin:code-reviewer`, uma vez que o plugin está habilitado.
100
101Para detalhes completos, consulte [Subagents](/docs/pt/sub-agents).
102
103<h3 id="hooks">
104 Hooks
105</h3>
106
107Os plugins podem fornecer manipuladores de eventos que respondem a eventos de Claude Code automaticamente.
108
109**Localização**: `hooks/hooks.json` na raiz do plugin, ou inline em plugin.json
110
111**Formato**: Configuração JSON com matchers de eventos e ações
112
113`hooks/hooks.json` pode conter uma chave `$schema` de nível superior que nomeia uma URL de JSON Schema para autocompletar e validação do editor. Claude Code ignora a chave no tempo de carregamento.
114
115**Configuração de hook**:
116
117```json theme={null}
118{
119 "hooks": {
120 "PostToolUse": [
121 {
122 "matcher": "Write|Edit",
123 "hooks": [
124 {
125 "type": "command",
126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
127 }
128 ]
129 }
130 ]
131 }
132}
133```
134
135Plugin hooks respondem aos mesmos eventos de ciclo de vida que [hooks definidos pelo usuário](/docs/pt/hooks):
136
137| Evento | Quando dispara |
138| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139| `SessionStart` | Quando uma sessão começa ou é retomada |
140| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |
141| `UserPromptSubmit` | Quando você envia um prompt, antes de Claude processá-lo |
142| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |
143| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |
144| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |
145| `PermissionDenied` | Quando o modo automático nega uma chamada de ferramenta, incluindo negações sem um veredicto do classificador. Use JSON `hookSpecificOutput.retry: true` para informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Claude Code ignora `retry` quando o classificador não produziu veredicto |
146| `PostToolUse` | Depois que uma chamada de ferramenta é bem-sucedida |
147| `PostToolUseFailure` | Depois que uma chamada de ferramenta falha |
148| `PostToolBatch` | Depois que um lote completo de chamadas de ferramenta paralelas é resolvido, antes da próxima chamada do modelo |
149| `Notification` | Quando Claude Code envia uma notificação |
150| `MessageDisplay` | Enquanto o texto da mensagem do assistente está sendo exibido |
151| `SubagentStart` | Quando um subagente é criado |
152| `SubagentStop` | Quando um subagente termina |
153| `TaskCreated` | Quando uma tarefa está sendo criada via `TaskCreate` |
154| `TaskCompleted` | Quando uma tarefa está sendo marcada como concluída |
155| `Stop` | Quando Claude termina de responder |
156| `StopFailure` | Quando a rodada termina devido a um erro de API |
157| `TeammateIdle` | Quando um colega de [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso |
158| `InstructionsLoaded` | Quando um arquivo CLAUDE.md ou `.claude/rules/*.md` é carregado no contexto. Dispara no início da sessão e quando os arquivos são carregados lentamente durante uma sessão |
159| `ConfigChange` | Quando um arquivo de configuração muda durante uma sessão |
160| `CwdChanged` | Quando o diretório de trabalho muda, por exemplo quando Claude executa um comando `cd`. Útil para gerenciamento reativo do ambiente com ferramentas como direnv |
161| `DirectoryAdded` | Quando um diretório de trabalho é adicionado no meio da sessão via `/add-dir` ou a solicitação de controle SDK `register_repo_root` |
162| `FileChanged` | Quando um arquivo observado muda no disco. O campo `matcher` especifica quais nomes de arquivo observar |
163| `WorktreeCreate` | Quando um worktree está sendo criado via `--worktree`, `isolation: "worktree"`, ou para uma sessão em segundo plano. Substitui o comportamento padrão do git |
164| `WorktreeRemove` | Quando um worktree está sendo removido na saída da sessão, quando um subagente termina, ou quando você exclui uma sessão em segundo plano |
165| `PreCompact` | Antes da compactação de contexto |
166| `PostCompact` | Depois que a compactação de contexto é concluída |
167| `PreModelSwitch` | Antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Pode bloquear a mudança |
168| `PostModelSwitch` | Depois que o modelo da sessão muda, incluindo mudanças que Claude Code faz por conta própria, como restaurar o modelo quando você retoma uma sessão |
169| `Elicitation` | Quando um servidor MCP solicita entrada do usuário durante uma chamada de ferramenta |
170| `ElicitationResult` | Depois que um usuário responde a uma elicitação MCP, antes da resposta ser enviada de volta ao servidor |
171| `SessionEnd` | Quando uma sessão é encerrada |
172
173**Tipos de hook**:
174
175* `command`: executar comandos shell ou scripts
176* `http`: enviar o JSON do evento como uma solicitação POST para uma URL
177* `mcp_tool`: chamar uma ferramenta em um [servidor MCP](/docs/pt/mcp) configurado
178* `prompt`: avaliar um prompt com um LLM (usa placeholder `$ARGUMENTS` para contexto)
179* `agent`: executar um verificador agentic com ferramentas para tarefas de verificação complexas
180
181Hooks que visam o [servidor MCP agrupado](#mcp-servers) 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](/docs/pt/hooks#match-mcp-tools) e [Plugin-provided MCP servers](/docs/pt/mcp#plugin-provided-mcp-servers).
182
183<h3 id="mcp-servers">
184 MCP servers
185</h3>
186
187Os plugins podem agrupar servidores Model Context Protocol (MCP) para conectar Claude Code com ferramentas e serviços externos.
188
189**Localização**: `.mcp.json` na raiz do plugin, ou inline em plugin.json
190
191**Formato**: Configuração padrão de servidor MCP
192
193**Configuração de servidor MCP**:
194
195```json theme={null}
196{
197 "mcpServers": {
198 "plugin-database": {
199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
201 "env": {
202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
203 }
204 },
205 "plugin-api-client": {
206 "command": "npx",
207 "args": ["@company/mcp-server", "--plugin-mode"]
208 }
209 }
210}
211```
212
213**Comportamento de integração**:
214
215* Servidores MCP de plugin iniciam automaticamente quando o plugin está habilitado
216* Servidores aparecem como ferramentas MCP padrão no toolkit de Claude
217* Servidores de plugin podem ser configurados independentemente de servidores MCP do usuário
218* Se você executar [`/reload-plugins`](/docs/pt/discover-plugins#apply-plugin-changes-without-restarting) no meio da sessão, Claude Code mantém as conexões ativas de servidores cuja configuração não foi alterada
219
220<h3 id="lsp-servers">
221 LSP servers
222</h3>
223
224<Tip>
225 Procurando usar plugins LSP? Instale-os do marketplace oficial: procure por "lsp" na aba Discover do `/plugin`. Esta seção documenta como criar plugins LSP para linguagens não cobertas pelo marketplace oficial.
226</Tip>
227
228Os plugins podem fornecer servidores [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) para dar a Claude [inteligência de código em tempo real](/docs/pt/discover-plugins#code-intelligence) enquanto trabalha em sua base de código.
229
230**Localização**: `.lsp.json` na raiz do plugin, ou inline em `plugin.json`
231
232**Formato**: Configuração JSON mapeando nomes de servidores de linguagem para suas configurações
233
234**Formato de arquivo `.lsp.json`**:
235
236```json theme={null}
237{
238 "go": {
239 "command": "gopls",
240 "args": ["serve"],
241 "extensionToLanguage": {
242 ".go": "go"
243 }
244 }
245}
246```
247
248**Inline em `plugin.json`**:
249
250```json theme={null}
251{
252 "name": "my-plugin",
253 "lspServers": {
254 "go": {
255 "command": "gopls",
256 "args": ["serve"],
257 "extensionToLanguage": {
258 ".go": "go"
259 }
260 }
261 }
262}
263```
264
265**Campos obrigatórios:**
266
267| Campo | Descrição |
268| :-------------------- | :------------------------------------------------------------ |
269| `command` | O binário LSP a executar (deve estar em PATH) |
270| `extensionToLanguage` | Mapeia extensões de arquivo para identificadores de linguagem |
271
272**Campos opcionais:**
273
274| Campo | Descrição |
275| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
276| `args` | Argumentos de linha de comando para o servidor LSP |
277| `transport` | Transporte de comunicação: `stdio` (padrão) ou `socket`. Claude Code aceita `socket` mas executa cada servidor sobre stdio, então as regras de protocolo stdout se aplicam a todos os servidores |
278| `env` | Variáveis de ambiente a definir ao iniciar o servidor |
279| `initializationOptions` | Opções passadas para o servidor durante a inicialização |
280| `settings` | Configurações passadas via `workspace/didChangeConfiguration` |
281| `workspaceFolder` | Caminho da pasta de workspace para o servidor |
282| `startupTimeout` | Tempo máximo para aguardar a inicialização do servidor (milissegundos) |
283| `shutdownTimeout` | Tempo máximo para aguardar o desligamento gracioso (milissegundos). Quando o timeout decorre, Claude Code encerra o processo do servidor. Quando não definido, nenhum timeout se aplica |
284| `restartOnCrash` | Se deve reiniciar o servidor após ele falhar. Padrão é `true`. Defina como `false` para deixar um servidor que falhou parado em vez de reiniciá-lo |
285| `maxRestarts` | Número máximo de tentativas de reinicialização antes de desistir |
286| `diagnostics` | Se deve enviar diagnósticos para o contexto de Claude após edições (padrão `true`). Defina como `false` para manter a navegação de código mas suprimir a injeção automática de diagnósticos. |
287
288`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`.
289
290**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.
291
292**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.
293
294Um 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.
295
296**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.
297
298<Warning>
299 **Você deve instalar o binário do servidor de linguagem separadamente.** Plugins LSP configuram como Claude Code se conecta a um servidor de linguagem, mas eles não incluem o servidor em si. Se você vê `Executable not found in $PATH` na aba Errors do `/plugin`, instale o binário necessário para sua linguagem.
300</Warning>
301
302**Plugins LSP disponíveis:**
303
304| Plugin | Servidor de linguagem | Comando de instalação |
305| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------- |
306| `pyright-lsp` | Pyright (Python) | `pip install pyright` ou `npm install -g pyright` |
307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
308| `rust-analyzer-lsp` | rust-analyzer | [Veja instalação de rust-analyzer](https://rust-analyzer.github.io/manual.html#installation) |
309
310Instale o servidor de linguagem primeiro, depois instale o plugin do marketplace.
311
312<h3 id="monitors">
313 Monitors
314</h3>
315
316Os 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.
317
318Plugin monitors usam o mesmo mecanismo que a [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool) 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](#hooks), e são pulados em hosts onde a ferramenta Monitor não está disponível.
319
320**Localização**: `monitors/monitors.json` na raiz do plugin, ou inline em `plugin.json`
321
322**Formato**: Array JSON de entradas de monitor
323
324O seguinte `monitors/monitors.json` observa um endpoint de status de deployment e um log de erro local:
325
326```json theme={null}
327[
328 {
329 "name": "deploy-status",
330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
331 "description": "Deployment status changes"
332 },
333 {
334 "name": "error-log",
335 "command": "tail -F ./logs/error.log",
336 "description": "Application error log",
337 "when": "on-skill-invoke:debug"
338 }
339]
340```
341
342Para 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](#experimental-components).
343
344**Campos obrigatórios:**
345
346| Campo | Descrição |
347| :------------ | :---------------------------------------------------------------------------------------------------------------------------- |
348| `name` | Identificador único dentro do plugin. Previne processos duplicados quando o plugin recarrega ou um skill é invocado novamente |
349| `command` | Comando shell executado como um processo de background persistente no diretório de trabalho da sessão |
350| `description` | Resumo curto do que está sendo observado. Mostrado no painel de tarefas e em resumos de notificação |
351
352**Campos opcionais:**
353
354| Campo | Descrição |
355| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
356| `when` | Controla quando o monitor inicia. `"always"` inicia na inicialização da sessão e no recarregamento do plugin, e é o padrão. `"on-skill-invoke:<skill-name>"` inicia na primeira vez que o skill nomeado neste plugin é despachado |
357
358O valor `command` suporta as [substituições de caminho](#environment-variables) `${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.
359
360Um `command` de monitor não pode referenciar valores [`${user_config.*}`](#user-configuration). O comando executa através de um shell, então Claude Code rejeita o monitor com um [erro](/docs/pt/errors#plugin-command-references-user-config) 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.
361
362Se 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.
363
364<h3 id="themes">
365 Themes
366</h3>
367
368Os 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](#experimental-components).
369
370```json theme={null}
371{
372 "name": "Dracula",
373 "base": "dark",
374 "overrides": {
375 "claude": "#bd93f9",
376 "error": "#ff5555",
377 "success": "#50fa7b"
378 }
379}
380```
381
382Quando 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.
383
384***
385
386<h2 id="plugin-installation-scopes">
387 Escopos de instalação de plugin
388</h2>
389
390Quando você instala um plugin, você escolhe um **escopo** que determina onde o plugin está disponível e quem mais pode usá-lo:
391
392| Escopo | Arquivo de configuração | Caso de uso |
393| :-------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------ |
394| `user` | `~/.claude/settings.json` | Plugins pessoais disponíveis em todos os projetos (padrão) |
395| `project` | `.claude/settings.json` | Plugins de equipe compartilhados via controle de versão |
396| `local` | `.claude/settings.local.json` | Plugins específicos do projeto, ignorados pelo git quando Claude Code salva uma configuração nele |
397| `managed` | [Managed settings](/docs/pt/managed-settings) | Plugins gerenciados (somente leitura, apenas atualizar) |
398
399Os 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](/docs/pt/discover-plugins#install-plugins). Para uma explicação completa de escopos, consulte [Configuration scopes](/docs/pt/settings#where-settings-live).
400
401***
402
403<h2 id="skills-directory-plugins">
404 Plugins de diretório de skills
405</h2>
406
407Qualquer 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`](#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.
408
409Uma árvore de diretório de skills suporta três coisas distintas:
410
411| O que você tem | O que é |
412| :-------------------------------------------- | :-------------------------------------------------------------------------------------------- |
413| `<skills-dir>/foo/SKILL.md` sem manifesto | Um [skill](/docs/pt/skills) simples nomeado `foo` |
414| `<skills-dir>/foo/.claude-plugin/plugin.json` | Um plugin `foo@skills-dir`, que pode agrupar seus próprios skills, agents, hooks e muito mais |
415| `<plugin>/skills/bar/SKILL.md` | Um skill `bar` empacotado dentro de um plugin |
416
417<h3 id="choose-where-the-plugin-loads-from">
418 Escolha de onde o plugin é carregado
419</h3>
420
421| Diretório de skills | Escopo | Carrega |
422| :---------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
423| `~/.claude/skills/` | pessoal | Em cada projeto, já que a localização é apenas sua |
424| `<cwd>/.claude/skills/` | projeto | Apenas depois que você aceita o [diálogo de confiança](/docs/pt/permissions#what-runs-before-you-trust-a-folder) do workspace para essa pasta |
425
426Um 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:
427
428* Servidores MCP que ele declara passam pela [mesma aprovação por servidor](/docs/pt/mcp) que um `.mcp.json` de projeto
429* Servidores LSP iniciam apenas depois que você confia no workspace
430* [Monitores de fundo](#monitors) não são carregados
431
432Plugins de escopo pessoal não têm nenhuma dessas restrições.
433
434<Warning>
435 Plugins `@skills-dir` de escopo de projeto são carregados apenas do `.claude/skills/` do [diretório de trabalho primário](/docs/pt/permissions#working-directories) da sessão. Eles não [caminham até a raiz do repositório](/docs/pt/skills#discovery-from-parent-and-nested-directories) da forma que skills e comandos simples fazem, portanto iniciar de um subdiretório perde um plugin que vive na raiz do repositório. Inicie a partir da raiz do repositório, ou [mova a sessão para lá com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior.
436</Warning>
437
438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">
439 Editar, recarregar e desabilitar um plugin de diretório de skills
440</h3>
441
442As 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](/docs/pt/skills#live-change-detection).
443
444Para 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.
445
446```bash theme={null}
447claude plugin disable my-tool@skills-dir
448```
449
450***
451
452<h2 id="synced-plugins">
453 Plugins sincronizados do claude.ai
454</h2>
455
456Claude Code carrega os plugins habilitados para sua conta claude.ai, incluindo plugins que sua organização ativa para seus membros, juntamente com os plugins que você instala a partir de marketplaces. Ele baixa cada um em `~/.claude/plugins/synced/` e o carrega como `<name>@synced`, sem marketplace e sem registro de instalação. Um plugin sincronizado é executado com a mesma confiança que um plugin de marketplace que você instalou: suas skills, agents, hooks, servidores MCP e servidores LSP são todos carregados.
457
458Onde Claude Code sincroniza esses plugins depende da sessão:
459
460* Em [Cowork](https://claude.com/product/cowork) e [sessões em nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup), Claude Code baixa-os no próprio ambiente da sessão quando a sessão inicia. Antes da v2.1.239, Claude Code carregava esses plugins como `<name>@inline`, a identidade que os plugins `--plugin-dir` usam.
461* Em sessões de terminal onde você faz login com sua conta claude.ai, Claude Code verifica sua conta uma vez cada vez que inicia, depois baixa plugins novos e atualizados e remove os que você ou sua organização desativou, tudo em segundo plano. A sincronização em sessões de terminal requer Claude Code v2.1.273 ou posterior.
462
463A verificação de inicialização é executada em segundo plano, portanto pode ser concluída após sua sessão ter iniciado. Quando adiciona, atualiza ou remove um plugin sincronizado em uma sessão interativa, Claude Code mostra `Plugins changed. Run /reload-plugins to activate.` Execute [`/reload-plugins`](/docs/pt/discover-plugins#apply-plugin-changes-without-restarting) para carregar a alteração nessa sessão, ou deixe para a próxima vez que você iniciar Claude Code. Se você habilitar um plugin no claude.ai enquanto uma sessão está em execução, Claude Code o baixa na próxima vez que inicia.
464
465A sincronização de plugins em sessões de terminal é executada sob as mesmas condições de login que [skills sincronizadas do claude.ai](/docs/pt/skills#where-synced-skills-load). Também precisa de um login que conceda a Claude Code acesso aos plugins de sua conta.
466
467Um login de uma versão anterior do Claude Code obtém acesso a plugins na próxima vez que Claude Code renova esse login em segundo plano, dentro de algumas horas, ou imediatamente se você executar `/login` novamente. A sincronização de plugins começa na próxima vez que você inicia Claude Code após isso.
468
469`claude plugin list` mostra plugins sincronizados sob um cabeçalho `Synced from claude.ai`, e a aba **Installed** do `/plugin` os lista com `synced` como sua fonte. Gerencie um plugin sincronizado pelo ID `<name>@synced` que `claude plugin list` imprime:
470
471* **Desativar um**: execute `claude plugin disable <name>@synced`, ou desative-o na aba **Installed** do `/plugin`. Claude Code salva a escolha como `"<name>@synced": false` em seu [`enabledPlugins`](/docs/pt/settings-reference#enabledplugins) de nível de usuário. Para ativar o plugin novamente, execute `claude plugin enable <name>@synced`.
472* **Manter um fora em todos os lugares**: [desative o plugin para sua conta claude.ai](/docs/pt/desktop#extend-claude-code). Para mantê-lo fora de um projeto em todos os ambientes, defina `"<name>@synced": false` sob `enabledPlugins` no `.claude/settings.json` comprometido daquele projeto.
473* **Gerencie o plugin em si no claude.ai**: `claude plugin install`, `update` e `uninstall` não se aplicam a um plugin sincronizado. Claude Code baixa as atualizações de um plugin na próxima sincronização. Para remover um, desative o plugin para sua conta claude.ai, e Claude Code o remove na próxima sincronização.
474* **Pare de sincronizar em uma máquina**: defina [`syncClaudeAiPlugins`](/docs/pt/settings-reference#syncclaudeaiplugins) como `false` em suas configurações de usuário. Claude Code para de baixar, e na próxima vez que inicia, move os plugins que já sincronizou para `~/.claude/plugins/.trash/` e não os carrega mais. Sua organização pode definir a mesma chave em [configurações gerenciadas](/docs/pt/managed-settings), ou desativar Skills no claude.ai, o que também para plugins de sincronizar.
475
476Você não pode desativar um plugin que sua organização marca como obrigatório no claude.ai. Claude Code o carrega mesmo se você o desativou anteriormente, e `claude plugin disable` recusa com `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` Em `claude plugin list`, esses plugins são marcados `required by your org`.
477
478Quando um plugin habilitado de qualquer outra fonte corresponde ao nome de um plugin sincronizado, Claude Code carrega esse plugin e relata a cópia sincronizada como não carregada. Outras fontes incluem instalações de marketplace, [plugins do diretório de skills](#skills-directory-plugins), plugins `--plugin-dir` e plugins integrados ao Claude Code. 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 de marketplace com o mesmo nome.
479
480***
481
482<h2 id="plugin-manifest-schema">
483 Esquema de manifesto de plugin
484</h2>
485
486O arquivo `.claude-plugin/plugin.json` define os metadados e a configuração do seu plugin.
487
488O manifesto é opcional. Se omitido, Claude Code descobre automaticamente componentes em [locais padrão](#file-locations-reference) e deriva o nome do plugin do nome do diretório. Use um manifesto quando precisar fornecer metadados ou caminhos de componentes personalizados.
489
490<h3 id="complete-schema">
491 Esquema completo
492</h3>
493
494```json theme={null}
495{
496 "name": "plugin-name",
497 "displayName": "Plugin Name",
498 "version": "1.2.0",
499 "description": "Brief plugin description",
500 "author": {
501 "name": "Author Name",
502 "email": "author@example.com",
503 "url": "https://github.com/author"
504 },
505 "homepage": "https://docs.example.com/plugin",
506 "repository": "https://github.com/author/plugin",
507 "license": "MIT",
508 "keywords": ["keyword1", "keyword2"],
509 "metadata": { "catalogId": "cat-123", "tier": "pro" },
510 "skills": "./custom/skills/",
511 "commands": ["./custom/commands/special.md"],
512 "agents": ["./custom/agents/reviewer.md"],
513 "hooks": "./config/hooks.json",
514 "mcpServers": "./mcp-config.json",
515 "outputStyles": "./styles/",
516 "lspServers": "./.lsp.json",
517 "experimental": {
518 "themes": "./themes/",
519 "monitors": "./monitors.json",
520 "evals": "quality/evals"
521 },
522 "dependencies": [
523 "helper-lib",
524 { "name": "secrets-vault", "version": "~2.1.0" }
525 ]
526}
527```
528
529<h3 id="required-fields">
530 Campos obrigatórios
531</h3>
532
533Se você incluir um manifesto, `name` é o único campo obrigatório.
534
535| Campo | Tipo | Descrição | Exemplo |
536| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
537| `name` | string | Identificador único em kebab-case, sem espaços, caracteres de controle ou caracteres de formatação bidirecional. Quando uma [entrada de marketplace](/docs/pt/plugin-marketplaces#plugin-entries) lista o plugin com um nome diferente, o nome da entrada de marketplace é o que `enabledPlugins` e `/plugin` usam | `"deployment-tools"` |
538
539Este nome é usado para namespacing de componentes. Por exemplo, na UI, o agente `agent-creator` para o plugin com nome `plugin-dev` aparecerá como `plugin-dev:agent-creator`.
540
541<h3 id="unrecognized-fields">
542 Campos não reconhecidos
543</h3>
544
545Claude 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 um manifesto de extensão VS Code ou Cursor, um `package.json` npm, ou um manifesto de bundle MCPB/DXT.
546
547`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 campo não reconhecido ainda passa na validação e carrega em tempo de execução.
548
549Como Claude Code lida com um campo reconhecido cujo valor tem o tipo errado depende do campo:
550
551* **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.
552* **`experimental` e `metadata`**: Claude Code ignora um valor não-objeto, e `claude plugin validate` relata um aviso.
553
554Passe `--strict` para tratar avisos como erros. Use 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.
555
556```bash theme={null}
557claude plugin validate ./my-plugin --strict
558```
559
560<h3 id="metadata-fields">
561 Campos de metadados
562</h3>
563
564| Campo | Tipo | Descrição | Exemplo |
565| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
566| `$schema` | string | URL do JSON Schema para autocompletar e validação do editor. Claude Code ignora este campo em tempo de carregamento. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
567| `displayName` | string | Nome legível por humanos mostrado no seletor `/plugin` e outras superfícies de UI. Para um plugin instalado do marketplace, um `displayName` na [entrada de marketplace](/docs/pt/plugin-marketplaces#optional-plugin-fields) tem precedência sobre este valor. Quando nenhum nome de exibição é definido em nenhum lugar, os usuários veem `name`. Ao contrário de `name`, pode conter espaços e qualquer capitalização. Não é usado para namespacing ou lookup. | `"Deployment Tools"` |
568| `version` | string | Opcional. Versão semântica. Definir isso fixa o plugin nessa string de versão, então os usuários só recebem atualizações quando você a incrementa, exceto para uma [`command` source](/docs/pt/plugin-marketplaces#command-sources) ou um plugin [carregado no local](#plugin-caching-and-file-resolution); veja [Gerenciamento de versão](#version-management). Se também definido na entrada de marketplace, `plugin.json` vence. Se omitido, a versão vem da próxima fonte em [Gerenciamento de versão](#version-management). | `"2.1.0"` |
569| `description` | string | Breve explicação do propósito do plugin | `"Deployment automation tools"` |
570| `author` | object | Informações do autor | `{"name": "Dev Team", "email": "dev@company.com"}` |
571| `homepage` | string | URL de documentação | `"https://docs.example.com"` |
572| `repository` | string | URL do código-fonte | `"https://github.com/user/plugin"` |
573| `license` | string | Identificador de licença | `"MIT"`, `"Apache-2.0"` |
574| `keywords` | array | Tags de descoberta | `["deployment", "ci-cd"]` |
575| `metadata` | object | Objeto de forma livre para seus próprios dados, como campos de direito ou catálogo. Claude Code não o lê, então os valores nunca afetam o comportamento do plugin. Claude Code ignora um valor não-objeto, e `claude plugin validate` o relata como um aviso. Antes de v2.1.222, Claude Code tratava a chave como um [campo não reconhecido](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
576| `defaultEnabled` | boolean | Se o plugin inicia em um estado habilitado quando o usuário não definiu um. Padrão é `true`. Veja [Habilitação padrão](#default-enablement). | `false` |
577
578<h3 id="default-enablement">
579 Habilitação padrão
580</h3>
581
582Defina `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 participar, como um que se conecta a um serviço externo.
583
584`defaultEnabled` é o fallback quando nada mais decidiu o estado do plugin. A configuração do usuário e um requisito de dependência têm precedência sobre ele:
585
586* **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.
587* **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](/docs/pt/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).
588
589O 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](/docs/pt/plugin-marketplaces#optional-plugin-fields).
590
591<h3 id="component-path-fields">
592 Campos de caminho de componente
593</h3>
594
595| Campo | Tipo | Descrição | Exemplo |
596| :---------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
597| `skills` | string\|array | Diretórios de skill personalizados contendo `<name>/SKILL.md`. Adiciona à varredura padrão `skills/`. Veja [Regras de comportamento de caminho](#path-behavior-rules) para a exceção de raiz de marketplace | `"./custom/skills/"` |
598| `commands` | string\|array | Arquivos de skill `.md` personalizados ou diretórios (substitui padrão `commands/`) | `"./custom/cmd.md"` ou `["./cmd1.md"]` |
599| `agents` | string\|array | Arquivos de agente personalizados (substitui padrão `agents/`) | `"./custom/agents/reviewer.md"` |
600| `workflows` | string\|array | Arquivos de script de [workflow](/docs/pt/workflows) personalizados ou diretórios (substitui padrão `workflows/`) | `"./custom/workflows/"` |
601| `hooks` | string\|array\|object | Caminhos de configuração de hook ou configuração inline | `"./my-extra-hooks.json"` |
602| `mcpServers` | string\|array\|object | Caminhos de configuração MCP ou configuração inline | `"./my-extra-mcp-config.json"` |
603| `outputStyles` | string\|array | Arquivos/diretórios de estilo de saída personalizados (substitui padrão `output-styles/`) | `"./styles/"` |
604| `lspServers` | string\|array\|object | Configurações do [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) para inteligência de código (ir para definição, encontrar referências, etc.) | `"./.lsp.json"` |
605| `experimental.themes` | string\|array | Arquivos/diretórios de tema de cor (substitui padrão `themes/`). Veja [Temas](#themes) | `"./themes/"` |
606| `experimental.monitors` | string\|array | Configurações de [Monitor](/docs/pt/tools-reference#monitor-tool) em segundo plano que iniciam automaticamente quando o plugin está ativo. Veja [Monitores](#monitors) | `"./monitors.json"` |
607| `experimental.evals` | string\|array | Diretório abaixo da raiz do plugin que contém os [casos de eval](/docs/pt/plugin-evals#use-a-different-eval-directory) do plugin, quando não é o padrão `evals/`. `claude plugin eval --eval-dir` o substitui | `"quality/evals"` |
608| `userConfig` | object | Valores configuráveis pelo usuário solicitados no tempo de habilitação. Veja [Configuração do usuário](#user-configuration) | |
609| `channels` | array | Declarações de canal para injeção de mensagem (estilo Telegram, Slack, Discord). Veja [Canais](#channels) | |
610| `dependencies` | array | Outros plugins que este plugin requer, opcionalmente com restrições de versão semver. Veja [Restringir versões de dependência de plugin](/docs/pt/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
611
612<h3 id="experimental-components">
613 Componentes experimentais
614</h3>
615
616Componentes sob a chave `experimental`, `themes` e `monitors`, têm um esquema de manifesto que pode mudar entre versões enquanto se 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.*`.
617
618<h3 id="user-configuration">
619 Configuração do usuário
620</h3>
621
622O 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`.
623
624```json theme={null}
625{
626 "userConfig": {
627 "api_endpoint": {
628 "type": "string",
629 "title": "API endpoint",
630 "description": "Your team's API endpoint"
631 },
632 "api_token": {
633 "type": "string",
634 "title": "API token",
635 "description": "API authentication token",
636 "sensitive": true
637 }
638 }
639}
640```
641
642As chaves devem ser identificadores válidos. Cada opção suporta estes campos:
643
644| Campo | Obrigatório | Descrição |
645| :------------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
646| `type` | Sim | Um de `string`, `number`, `boolean`, `directory`, ou `file` |
647| `title` | Sim | Rótulo mostrado no diálogo de configuração |
648| `description` | Sim | Texto de ajuda mostrado abaixo do campo |
649| `sensitive` | Não | Se `true`, mascara entrada e armazena o valor em armazenamento seguro em vez de `settings.json` |
650| `required` | Não | Se `true`, a validação falha quando o campo está vazio |
651| `default` | Não | Valor usado quando o usuário não fornece nada |
652| `options` | Não | Para tipo `string`, os valores que o campo aceita, mostrados em `/config` como um seletor sobre eles. Veja [Limitar um campo a opções fixas](#limit-a-field-to-fixed-options). Requer Claude Code v2.1.271 ou posterior |
653| `multiple` | Não | Para tipo `string`, permitir um array de strings |
654| `min` / `max` | Não | Limites para tipo `number` |
655
656Exceto campos `sensitive` e listas `multiple`, cada campo de cada plugin habilitado também aparece como uma linha no painel `/config`. As linhas requerem Claude Code v2.1.269 ou posterior.
657
658Cada 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.
659
660Campos 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](/docs/pt/errors#plugin-command-references-user-config) em vez disso. Cada campo rejeitado tem uma forma alternativa de passar o valor:
661
662| Campo rejeitado | Como passar o valor |
663| :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
664| Comandos de hook em forma de shell | Use [forma exec](/docs/pt/hooks#exec-form-and-shell-form) com `args`, ou leia `CLAUDE_PLUGIN_OPTION_<KEY>` do ambiente do hook |
665| Comandos de [Monitor](#monitors) | Leia o valor de um arquivo de configuração no script |
666| MCP [`headersHelper`](/docs/pt/mcp#use-dynamic-headers-for-custom-authentication) | Leia o valor de um arquivo de configuração no script |
667
668Antes de v2.1.207, esses campos substituíam valores `${user_config.KEY}`; atualize plugins que dependiam disso.
669
670Valores não-sensíveis são armazenados sob a chave [`pluginConfigs`](/docs/pt/settings-reference#pluginconfigs) em seu `settings.json` de usuário como `pluginConfigs[<plugin-id>].options`.
671
672No 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 aproximado de 2 KB, então mantenha valores sensíveis pequenos.
673
674Claude Code lê todos os valores `pluginConfigs` de apenas três fontes de configurações:
675
676* **Configurações do usuário**: `~/.claude/settings.json`, o arquivo que o prompt de tempo de habilitação escreve
677* **`--settings`**: o sinalizador CLI ou configurações inline do SDK
678* **Configurações gerenciadas**: [política controlada pela organização](/docs/pt/permissions#managed-settings)
679
680Quando mais de uma fonte define a mesma chave, as 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`](/docs/pt/cli-reference#cli-flags) sem `user` e Claude Code as ignora. Configurações gerenciadas e `--settings` permanecem o que você passar. A opção [`settingSources`](/docs/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) do SDK define a mesma lista.
681
682Entradas 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`](/docs/pt/settings-reference#enabledplugins) ainda honra configurações de projeto e local.
683
684<h4 id="limit-a-field-to-fixed-options">
685 Limitar um campo a opções fixas
686</h4>
687
688Defina `options` em um campo `userConfig` para fazer os usuários escolherem seu valor de uma lista fixa.
689
690Para limitar um campo `tone` a três opções, liste-as em `options` e defina `default` para uma delas:
691
692```json theme={null}
693{
694 "userConfig": {
695 "tone": {
696 "type": "string",
697 "title": "Tone",
698 "description": "Voice for generated replies",
699 "options": ["neutral", "warm", "formal"],
700 "default": "neutral"
701 }
702 }
703}
704```
705
706Se você declarar `options` em qualquer campo, usuários em versões Claude Code anteriores a v2.1.271 não podem carregar o plugin.
707
708Quando você define `options` em um campo, siga estas regras:
709
710* Defina `type` para `string`
711* Não defina `multiple` ou `sensitive` para `true`
712* Defina `default` para uma das opções
713* Se você deixar `default` indefinido, defina `required` para `true`
714* Liste pelo menos uma opção, cada uma com 1 a 64 caracteres de comprimento
715* Não comece ou termine uma opção com um espaço
716* Não use caracteres de controle, caracteres invisíveis, caracteres que mudam a direção do texto, ou espaços diferentes de um espaço regular em uma opção
717* Não liste a mesma opção duas vezes, mesmo em uma capitalização diferente
718
719Se você quebrar qualquer uma dessas regras, o plugin falha ao carregar. Execute `claude plugin validate` para ver qual campo quebra qual regra.
720
721<h3 id="channels">
722 Canais
723</h3>
724
725O 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.
726
727```json theme={null}
728{
729 "channels": [
730 {
731 "server": "telegram",
732 "userConfig": {
733 "bot_token": {
734 "type": "string",
735 "title": "Bot token",
736 "description": "Telegram bot token",
737 "sensitive": true
738 },
739 "owner_id": {
740 "type": "string",
741 "title": "Owner ID",
742 "description": "Your Telegram user ID"
743 }
744 }
745 }
746 ]
747}
748```
749
750O 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.
751
752<h3 id="path-behavior-rules">
753 Regras de comportamento de caminho
754</h3>
755
756Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:
757
758* **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/"]`
759* **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 do marketplace](/docs/pt/plugin-marketplaces#advanced-plugin-entries), declarar subdiretórios específicos substitui a varredura padrão `skills/`
760* **Regras de mesclagem próprias**: [hooks](#hooks), [servidores MCP](#mcp-servers), e [servidores LSP](#lsp-servers). Veja cada seção para como múltiplas fontes se combinam
761
762Quando 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 na 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.
763
764Para todos os campos de caminho:
765
766* Todos os caminhos devem ser relativos à raiz do plugin e começar com `./`, exceto que o campo `skills` também aceita `"."`
767 * Ambos `"."` e `"./"` denotam a raiz do plugin em si
768 * 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
769* Componentes de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing, exceto arquivos de agente. Veja [Agentes](#agents) para como nomes de agente funcionam
770* Múltiplos caminhos podem ser especificados como arrays
771* 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
772 * Claude Code pega o nome de invocação da 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
773 * Se `name` não estiver definido no frontmatter, Claude Code volta para o basename do diretório
774
775Um 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.
776
777**Exemplos de caminho**:
778
779```json theme={null}
780{
781 "commands": [
782 "./specialized/deploy.md",
783 "./utilities/batch-process.md"
784 ],
785 "agents": [
786 "./custom-agents/reviewer.md",
787 "./custom-agents/tester.md"
788 ]
789}
790```
791
792<h3 id="environment-variables">
793 Variáveis de ambiente
794</h3>
795
796Claude Code fornece três variáveis para referenciar caminhos:
797
798| Variável | Resolve para | Use para |
799| :---------------------- | :------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------- |
800| `${CLAUDE_PLUGIN_ROOT}` | Caminho absoluto para o diretório de instalação do plugin | Scripts, binários e arquivos de configuração agrupados com o plugin |
801| `${CLAUDE_PLUGIN_DATA}` | [Diretório persistente](#persistent-data-directory) que sobrevive a atualizações de plugin, criado na primeira referência | Dependências instaladas como `node_modules` ou ambientes virtuais Python, código gerado e caches |
802| `${CLAUDE_PROJECT_DIR}` | A raiz do projeto | Scripts e arquivos de configuração locais do projeto |
803
804Todos os três são exportados como variáveis de ambiente para processos de hook e para subprocessos de servidor MCP e LSP. Eles não estão presentes no ambiente de comandos que Claude executa através da ferramenta Bash, na sessão principal ou em um subagente. Em conteúdo de plugin, escreva o placeholder em vez disso, e Claude Code substitui o caminho inline quando carrega o conteúdo. Quais campos substituem eles inline depende do componente de plugin:
805
806| Componente de plugin | Campos onde placeholders resolvem |
807| :--------------------------------- | :------------------------------------------- |
808| Conteúdo de skill e agente | Em qualquer lugar onde o placeholder aparece |
809| Comandos de hook e monitor | Em qualquer lugar onde o placeholder aparece |
810| Servidores MCP `stdio` | `command`, `args`, `env` |
811| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` |
812| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` |
813
814Em comandos de hook, use [forma exec](/docs/pt/hooks#exec-form-and-shell-form) 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:
815
816```json theme={null}
817{
818 "hooks": {
819 "PostToolUse": [
820 {
821 "hooks": [
822 {
823 "type": "command",
824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
825 }
826 ]
827 }
828 ]
829 }
830}
831```
832
833Para um plugin copiado, `${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á. Para um plugin carregado no local de um marketplace de diretório local, a variável aponta para o diretório de origem estável. Veja [plugin caching](#plugin-caching-and-file-resolution) para quais plugins são copiados e para semântica de limpeza.
834
835Quando um plugin copiado é 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 requerem uma reinicialização de sessão. Em uma sessão sem um terminal interativo, o recarregamento deixa servidores MCP de plugin no caminho antigo até a próxima sessão.
836
837Para um plugin com uma `command` source, Claude Code [pode recarregar o plugin em si](/docs/pt/plugin-marketplaces#when-claude-code-re-runs-the-command).
838
839Servidores 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](/docs/pt/mcp#option-3-add-a-local-stdio-server).
840
841<h4 id="persistent-data-directory">
842 Diretório de dados persistente
843</h4>
844
845O 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/`.
846
847Um 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 do marketplace, você pode não precisar dele: Claude Code instala automaticamente [dependências de pacote Node.js](#node-js-package-dependencies) elegíveis quando armazena em cache o plugin.
848
849Como 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.
850
851Este hook `SessionStart` instala `node_modules` na primeira execução e novamente sempre que uma atualização de plugin inclui um `package.json` alterado:
852
853```json theme={null}
854{
855 "hooks": {
856 "SessionStart": [
857 {
858 "hooks": [
859 {
860 "type": "command",
861 "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\""
862 }
863 ]
864 }
865 ]
866 }
867}
868```
869
870O `diff` sai com código diferente de zero quando a cópia armazenada está faltando ou difere da agrupada, cobrindo tanto a 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.
871
872Scripts agrupados em `${CLAUDE_PLUGIN_ROOT}` podem então executar contra o `node_modules` persistido:
873
874```json theme={null}
875{
876 "mcpServers": {
877 "routines": {
878 "command": "node",
879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
880 "env": {
881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
882 }
883 }
884 }
885}
886```
887
888O 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. O CLI deleta por padrão; passe [`--keep-data`](#plugin-uninstall) para preservá-lo.
889
890***
891
892<h2 id="plugin-caching-and-file-resolution">
893 Caching de plugins e resolução de arquivos
894</h2>
895
896Plugins são especificados de uma das três maneiras:
897
898* Através de `claude --plugin-dir` ou `claude --plugin-url`, pela duração de uma sessão.
899* Através de um marketplace, instalado para futuras sessões.
900* Através de sua conta claude.ai, [sincronizados](#synced-plugins) em `~/.claude/plugins/synced/`.
901
902Para 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`), exceto quando o plugin é carregado no local. Uma [fonte `command` em link mode](/docs/pt/plugin-marketplaces#copy-mode-and-link-mode) é carregada no local através de links na entrada do cache. Uma [fonte de caminho relativo](/docs/pt/plugin-marketplaces#relative-paths) em um marketplace adicionado de um diretório local é carregada no local a partir da pasta do marketplace.
903
904Para um plugin carregado no local a partir de um marketplace de diretório local, suas edições no diretório de origem entram em vigor no próximo início de sessão ou `/reload-plugins`. Você não precisa de um bump de versão. Os processos de hook do plugin e os servidores MCP e LSP recebem um `CLAUDE_PLUGIN_ROOT` que aponta para o diretório de origem. Claude Code não instala as [dependências de pacotes Node.js](#node-js-package-dependencies) do plugin no diretório de origem. Instale-as lá você mesmo, ou a partir de um hook no [diretório de dados persistentes](#persistent-data-directory).
905
906Para 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](#node-js-package-dependencies). Uma dependência resolvida de uma [tag de release](/docs/pt/plugin-dependencies#tag-plugin-releases-for-version-resolution) obtém um nome de diretório com um sufixo de commit-SHA.
907
908Quando 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.
909
910Claude 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.
911
912As 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.
913
914<h3 id="node-js-package-dependencies">
915 Dependências de pacotes Node.js
916</h3>
917
918Quando 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](/docs/pt/plugin-dependencies).
919
920Claude 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:
921
922| Lockfile | Comando |
923| :------------------------------------------- | :----------------------------------------------- |
924| `bun.lock` ou `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
925| `npm-shrinkwrap.json` ou `package-lock.json` | `npm ci --ignore-scripts` |
926
927Se 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`.
928
929Claude Code pula a instalação em dois casos, cada um com sua própria correção:
930
931* Se seu plugin envia apenas um `yarn.lock` ou `pnpm-lock.yaml`, substitua-o por um lockfile npm.
932* Se um `bunfig.toml` fica ao lado do lockfile bun, remova o `bunfig.toml`, ou substitua o lockfile bun por um lockfile npm.
933
934Envie 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.
935
936Claude 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:
937
938* **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.
939* **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.
940* **Timeout de 60 segundos:** Claude Code para uma instalação que é executada por mais tempo e a trata como falha.
941
942Claude Code busca um plugin de fonte npm antes dessa instalação de dependência, e nenhum dos scripts de instalação próprios do pacote é executado durante a busca. Consulte [pacotes npm](/docs/pt/plugin-marketplaces#npm-packages).
943
944Uma instalação falhada ou ignorada nunca bloqueia o plugin. Quando a instalação falha, ou Claude Code pula um lockfile yarn ou pnpm ou um `bunfig.toml`, ele registra o motivo como um aviso na [saída de debug](#debugging-commands). 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.
945
946Você 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](/docs/pt/network-config#network-access-requirements) para os hosts a permitir.
947
948Para 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](#persistent-data-directory).
949
950<h3 id="path-traversal-limitations">
951 Limitações de travessia de caminho
952</h3>
953
954Claude 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](/docs/pt/plugin-marketplaces#plugin-entries). 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](#share-files-within-a-marketplace-with-symlinks).
955
956Em 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`.
957
958Quando Claude Code rejeita um caminho, ele relata um erro [`path escapes plugin directory`](/docs/pt/errors#path-escapes-plugin-directory) e carrega o plugin sem esse componente.
959
960Claude 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.
961
962<h3 id="share-files-within-a-marketplace-with-symlinks">
963 Compartilhar arquivos dentro de um marketplace com symlinks
964</h3>
965
966Se 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:
967
968* **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.
969* **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.
970* **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.
971
972Para plugins instalados com `--plugin-dir`, de um caminho local, ou de uma [fonte `command`](/docs/pt/plugin-marketplaces#copy-mode-and-link-mode) 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.
973
974O 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:
975
976```bash theme={null}
977ln -s ../../shared-plugin/skills/foo ./skills/foo
978```
979
980***
981
982<h2 id="plugin-directory-structure">
983 Estrutura de diretório do plugin
984</h2>
985
986<h3 id="standard-plugin-layout">
987 Layout padrão do plugin
988</h3>
989
990Um plugin completo segue esta estrutura:
991
992```text theme={null}
993enterprise-plugin/
994├── .claude-plugin/ # Diretório de metadados (opcional)
995│ └── plugin.json # manifesto do plugin
996├── skills/ # Skills
997│ ├── code-reviewer/
998│ │ └── SKILL.md
999│ └── pdf-processor/
1000│ ├── SKILL.md
1001│ └── scripts/
1002├── commands/ # Skills como arquivos .md simples
1003│ ├── status.md
1004│ └── logs.md
1005├── agents/ # Definições de subagentes
1006│ ├── security-reviewer.md
1007│ ├── performance-tester.md
1008│ ├── compliance-checker.md
1009│ └── review/ # Agentes aqui carregam como enterprise-plugin:review:<name>
1010│ └── accessibility.md
1011├── workflows/ # Scripts de fluxo de trabalho
1012│ └── release-audit.js
1013├── output-styles/ # Definições de estilo de saída
1014│ └── terse.md
1015├── themes/ # Definições de tema de cor
1016│ └── dracula.json
1017├── monitors/ # Configurações de monitor de fundo
1018│ └── monitors.json
1019├── hooks/ # Configurações de hooks
1020│ ├── hooks.json # Configuração principal de hooks
1021│ └── security-hooks.json # Hooks adicionais
1022├── bin/ # Executáveis do plugin adicionados ao PATH
1023│ └── my-tool # Invocável como comando simples na ferramenta Bash
1024├── settings.json # Configurações padrão para o plugin
1025├── .mcp.json # Definições de servidor MCP
1026├── .lsp.json # Configurações de servidor LSP
1027├── scripts/ # Scripts de hooks e utilitários
1028│ ├── security-scan.sh
1029│ ├── format-code.py
1030│ └── deploy.js
1031├── LICENSE # Arquivo de licença
1032└── CHANGELOG.md # Histórico de versões
1033```
1034
1035<Warning>
1036 O diretório `.claude-plugin/` contém o arquivo `plugin.json`. Todos os outros diretórios (commands/, agents/, skills/, workflows/, output-styles/, themes/, monitors/, hooks/) devem estar na raiz do plugin, não dentro de `.claude-plugin/`.
1037</Warning>
1038
1039Um 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](#skills).
1040
1041<h3 id="file-locations-reference">
1042 Referência de localizações de arquivo
1043</h3>
1044
1045| Componente | Localização Padrão | Propósito |
1046| :------------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1047| **Manifesto** | `.claude-plugin/plugin.json` | Metadados e configuração do plugin (opcional) |
1048| **Skills** | `skills/` | Skills com estrutura `<name>/SKILL.md` |
1049| **Comandos** | `commands/` | Skills como arquivos Markdown simples. Use `skills/` para novos plugins |
1050| **Agentes** | `agents/` | Arquivos Markdown de subagentes. Subpastas fazem parte do [nome do agente](#agents) |
1051| **Workflows** | `workflows/` | Arquivos de script de [Workflow](/docs/pt/workflows) |
1052| **Estilos de saída** | `output-styles/` | Definições de estilo de saída |
1053| **Temas** | `themes/` | Definições de tema de cor |
1054| **Hooks** | `hooks/hooks.json` | Configuração de hooks |
1055| **Servidores MCP** | `.mcp.json` | Definições de servidor MCP |
1056| **Servidores LSP** | `.lsp.json` | Configurações de servidor de linguagem |
1057| **Monitores** | `monitors/monitors.json` | Configurações de monitor de fundo |
1058| **Executáveis** | `bin/` | Executáveis adicionados ao `PATH` da ferramenta Bash e invocáveis como comandos simples enquanto o plugin está ativado. Você não pode incluir este diretório em um plugin que você [distribui através das configurações da organização claude.ai](/docs/pt/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
1059| **Configurações** | `settings.json` | Configuração padrão aplicada quando o plugin é ativado. Apenas as chaves [`agent`](/docs/pt/sub-agents) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) são suportadas |
1060
1061***
1062
1063<h2 id="cli-commands-reference">
1064 Referência de comandos CLI
1065</h2>
1066
1067Claude Code fornece comandos CLI para gerenciamento de plugins não interativo, útil para scripts e automação.
1068
1069<h3 id="plugin-init">
1070 plugin init
1071</h3>
1072
1073Crie 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.
1074
1075Consulte [Skills-directory plugins](#skills-directory-plugins) para requisitos de escopo e confiança.
1076
1077```bash theme={null}
1078claude plugin init <name> [options]
1079```
1080
1081O comando toma estes argumentos:
1082
1083* `<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.
1084
1085O comando aceita estas opções:
1086
1087| Opção | Descrição | Padrão |
1088| :----------------------- | :----------------------------------------------------------------------------------------------------------------------- | :---------------------- |
1089| `--description <text>` | Descrição do manifesto | |
1090| `--author <name>` | Nome do autor | `git config user.name` |
1091| `--author-email <email>` | Email do autor | `git config user.email` |
1092| `--with <components...>` | Também crie pastas de componentes. Valores válidos: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel` | |
1093| `-f, --force` | Sobrescreva um `.claude-plugin/` existente no destino | |
1094| `-h, --help` | Exiba ajuda para o comando | |
1095
1096`claude plugin new` é um alias para este comando.
1097
1098Cada valor `--with` adiciona um arquivo inicial para esse componente, pronto para editar:
1099
1100| Componente | O que ele cria |
1101| :------------- | :-------------------------------------------------------------------------------------------------------------- |
1102| `skills` | Uma skill `<name>:example` adicional com namespace ao lado da padrão |
1103| `agents` | Uma definição de subagent em `agents/` |
1104| `hooks` | Um `hooks/hooks.json` com um manipulador de evento de exemplo |
1105| `mcp` | Um `.mcp.json` com exemplos de servidor HTTP e stdio |
1106| `lsp` | Um exemplo de language-server `.lsp.json` |
1107| `output-style` | Um `output-styles/<name>.md` que se aplica automaticamente enquanto o plugin está ativado |
1108| `channel` | Um [channel](/docs/pt/channels) baseado em MCP: um servidor stdio (`server.ts`), seu `.mcp.json` e um `package.json` |
1109
1110O 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](/docs/pt/plugin-marketplaces#managed-marketplace-restrictions). Quando bloqueado, `plugin init` falha antes de escrever.
1111
1112Estes exemplos mostram invocações comuns:
1113
1114```bash theme={null}
1115# Crie um plugin mínimo
1116claude plugin init my-helper
1117
1118# Crie com pastas de skill e hook
1119claude plugin init my-helper --with skills hooks
1120
1121# Sobrescreva um scaffold existente
1122claude plugin init my-helper --force
1123```
1124
1125<h3 id="plugin-install">
1126 plugin install
1127</h3>
1128
1129Instale um plugin dos marketplaces disponíveis.
1130
1131```bash theme={null}
1132claude plugin install <plugin> [options]
1133```
1134
1135O comando toma estes argumentos:
1136
1137* `<plugin>`: Nome do plugin ou `plugin-name@marketplace-name` para um marketplace específico
1138
1139O comando aceita estas opções:
1140
1141| Opção | Descrição | Padrão |
1142| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1143| `-s, --scope <scope>` | Escopo de instalação: `user`, `project` ou `local` | `user` |
1144| `--config <key=value>` | Defina uma opção [`userConfig`](#user-configuration) declarada no manifesto do plugin. Repita a flag para definir múltiplas opções | |
1145| `-y, --yes` | Aceite um comando que o marketplace do plugin declara, sem o prompt de confirmação: o comando que produz um plugin com uma [`command` source](/docs/pt/plugin-marketplaces#command-sources), ou o [`headersHelper`](/docs/pt/plugin-marketplaces#authenticate-archive-downloads) que autentica um download de arquivo. Aceitar um `headersHelper` requer Claude Code v2.1.238 ou posterior. Claude Code ainda imprime o comando primeiro. Obrigatório quando stdin ou stdout não é um TTY, a menos que você passe `--accept-command`. Não tem efeito dentro de uma sessão do Claude Code, portanto execute o comando do seu próprio terminal | |
1146| `--accept-command <sha256>` | Aceite o comando declarado pelo marketplace cujo `sha256` uma execução anterior com [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. A aceitação conta para exatamente esse comando, plugin e catálogo de marketplace. Se qualquer um deles mudou desde que o comando foi exibido, incluindo através da própria atualização de marketplace da execução, Claude Code não aceita o digest e mostra o comando novamente. Não pode ser combinado com `-y`. Não tem efeito dentro de uma sessão do Claude Code, portanto execute o comando do seu próprio terminal. Requer Claude Code v2.1.271 ou posterior | |
1147| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout em vez da mensagem legível por humanos, para uso em scripts. Consulte [Formato de resultado JSON](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior | |
1148| `-h, --help` | Exiba ajuda para o comando | |
1149
1150O 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.
1151
1152<span id="plugin-json-result" />Com `--json`, a última linha de stdout é um objeto JSON. Analise apenas essa linha, porque Claude Code imprime qualquer comando que o marketplace declara antes dela. Três campos estão sempre presentes:
1153
1154* `command`: o subcomando que foi executado, como `install`
1155* `outcome`: `ok` ou `failed`
1156* `message`: uma descrição legível por humanos do resultado
1157
1158Outros campos, como `pluginId`, `scope` e `failureCode`, aparecem apenas quando se aplicam. A opção `--json` em `plugin uninstall`, `plugin update`, `plugin enable` e `plugin disable` imprime o mesmo objeto com os próprios campos desse subcomando. Um erro de uso, como um `--scope` inválido, não imprime nenhuma linha de resultado e sai com 1 com o motivo em stderr.
1159
1160Quando uma execução exibe um comando declarado pelo marketplace e não o executa, o resultado `failed` também carrega um objeto `shownCommand` cujos campos incluem o comando conforme exibido, o plugin ao qual pertence e o `sha256` do comando. Para aceitar exatamente esse comando, execute novamente com esse `sha256` como `--accept-command`. Requer Claude Code v2.1.271 ou posterior.
1161
1162Se `shownCommand.acceptCommandMatched` for `false`, o digest que você passou não corresponde ao comando agora exibido. Mostre esse comando a uma pessoa antes de passar seu `sha256`.
1163
1164Estes exemplos mostram invocações comuns:
1165
1166```bash theme={null}
1167# Instale no escopo do usuário (padrão)
1168claude plugin install formatter@my-marketplace
1169
1170# Instale no escopo do projeto (compartilhado com a equipe)
1171claude plugin install formatter@my-marketplace --scope project
1172
1173# Instale no escopo local (não compartilhado com a equipe)
1174claude plugin install formatter@my-marketplace --scope local
1175```
1176
1177<h3 id="plugin-uninstall">
1178 plugin uninstall
1179</h3>
1180
1181Remova um plugin instalado.
1182
1183```bash theme={null}
1184claude plugin uninstall <plugin> [options]
1185```
1186
1187O comando toma estes argumentos:
1188
1189* `<plugin>`: Nome do plugin ou `plugin-name@marketplace-name`
1190
1191O comando aceita estas opções:
1192
1193| Opção | Descrição | Padrão |
1194| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1195| `-s, --scope <scope>` | Desinstale do escopo: `user`, `project` ou `local` | `user` |
1196| `--keep-data` | Preserve o diretório de [persistent data](#persistent-data-directory) do plugin | |
1197| `--prune` | Também remova dependências auto-instaladas que nenhum outro plugin requer. Consulte [plugin prune](#plugin-prune) | |
1198| `-y, --yes` | Pule o prompt de confirmação `--prune`. Obrigatório quando stdin ou stdout não é um TTY | |
1199| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout, no [mesmo formato que `plugin install --json`](#plugin-json-result). Não pode ser combinado com `--prune`. Requer Claude Code v2.1.268 ou posterior | |
1200| `-h, --help` | Exiba ajuda para o comando | |
1201
1202`claude plugin remove` e `claude plugin rm` são aliases para este comando.
1203
1204Por 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.
1205
1206<Note>
1207 Quando plugins instalados de diferentes marketplaces compartilham um nome, o formulário `plugin-name@marketplace-name` desinstala apenas o plugin do marketplace nomeado. Antes da v2.1.212, o formulário qualificado poderia corresponder e desinstalar o plugin de mesmo nome de um marketplace diferente.
1208</Note>
1209
1210<h3 id="plugin-prune">
1211 plugin prune
1212</h3>
1213
1214Remova 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`](/docs/pt/plugin-dependencies) de outro plugin são removidas; plugins que você instalou diretamente nunca são tocados.
1215
1216```bash theme={null}
1217claude plugin prune [options]
1218```
1219
1220O comando aceita estas opções:
1221
1222| Opção | Descrição | Padrão |
1223| :-------------------- | :---------------------------------------------------------------------------- | :----- |
1224| `-s, --scope <scope>` | Limpe no escopo: `user`, `project` ou `local` | `user` |
1225| `--dry-run` | Liste o que seria removido sem remover nada | |
1226| `-y, --yes` | Pule o prompt de confirmação. Obrigatório quando stdin ou stdout não é um TTY | |
1227| `-h, --help` | Exiba ajuda para o comando | |
1228
1229`claude plugin autoremove` é um alias para este comando.
1230
1231O 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`.
1232
1233<h3 id="plugin-enable">
1234 plugin enable
1235</h3>
1236
1237Ative um plugin desativado. Quando o destino é instalado de um marketplace e declara [dependencies](/docs/pt/plugin-dependencies), Claude Code os ativa transitivamente no mesmo escopo. O comando falha sob as condições que [Enable or disable a plugin with dependencies](/docs/pt/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) lista.
1238
1239```bash theme={null}
1240claude plugin enable <plugin> [options]
1241```
1242
1243O comando toma estes argumentos:
1244
1245* `<plugin>`: Nome do plugin, `plugin-name@marketplace-name` ou `plugin-name@synced` para um [plugin sincronizado de claude.ai](#synced-plugins)
1246
1247O comando aceita estas opções:
1248
1249| Opção | Descrição | Padrão |
1250| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
1251| `-s, --scope <scope>` | Escopo para ativar: `user`, `project` ou `local`. Quando omitido, Claude Code detecta o escopo onde o plugin está instalado | Auto-detect |
1252| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout, no [mesmo formato que `plugin install --json`](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior | |
1253| `-h, --help` | Exiba ajuda para o comando | |
1254
1255<h3 id="plugin-disable">
1256 plugin disable
1257</h3>
1258
1259Desative um plugin sem desinstalá-lo.
1260
1261Quando o destino é instalado de um marketplace, o comando falha se outro plugin ativado [depende](/docs/pt/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) dele. A mensagem de erro inclui um comando encadeado que desativa cada dependente primeiro.
1262
1263Para um [synced plugin](#synced-plugins) que sua organização requer, o comando falha e não salva nada.
1264
1265```bash theme={null}
1266claude plugin disable [plugin] [options]
1267```
1268
1269O comando toma estes argumentos:
1270
1271* `[plugin]`: Nome do plugin, `plugin-name@marketplace-name` ou `plugin-name@synced` para um [plugin sincronizado de claude.ai](#synced-plugins). Opcional ao usar `--all`
1272
1273O comando aceita estas opções:
1274
1275| Opção | Descrição | Padrão |
1276| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
1277| `-a, --all` | Desative todos os plugins ativados. Não pode ser combinado com `--scope` | |
1278| `-s, --scope <scope>` | Escopo para desativar: `user`, `project` ou `local`. Quando omitido, Claude Code detecta o escopo onde o plugin está instalado | Auto-detect |
1279| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout, no [mesmo formato que `plugin install --json`](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior | |
1280| `-h, --help` | Exiba ajuda para o comando | |
1281
1282<h3 id="plugin-update">
1283 plugin update
1284</h3>
1285
1286Atualize um plugin para a versão mais recente.
1287
1288```bash theme={null}
1289claude plugin update <plugin> [options]
1290```
1291
1292O comando toma estes argumentos:
1293
1294* `<plugin>`: Nome do plugin ou `plugin-name@marketplace-name`
1295
1296O comando aceita estas opções:
1297
1298| Opção | Descrição | Padrão |
1299| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1300| `-s, --scope <scope>` | Escopo para atualizar: `user`, `project`, `local` ou `managed` | `user` |
1301| `-y, --yes` | Aceite um comando que o marketplace do plugin declara, sem o prompt de confirmação: o comando que produz um plugin com uma [`command` source](/docs/pt/plugin-marketplaces#command-sources), ou o [`headersHelper`](/docs/pt/plugin-marketplaces#authenticate-archive-downloads) que autentica um download de arquivo. Aceitar um `headersHelper` requer Claude Code v2.1.238 ou posterior. Claude Code ainda imprime o comando primeiro. Obrigatório quando stdin ou stdout não é um TTY, a menos que você passe `--accept-command`. Não tem efeito dentro de uma sessão do Claude Code, portanto execute o comando do seu próprio terminal | |
1302| `--accept-command <sha256>` | Aceite o comando declarado pelo marketplace cujo `sha256` uma execução anterior com [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. A aceitação conta para exatamente esse comando, plugin e catálogo de marketplace. Se qualquer um deles mudou desde que o comando foi exibido, incluindo através da própria atualização de marketplace da execução, Claude Code não aceita o digest e mostra o comando novamente. Não pode ser combinado com `-y`. Não tem efeito dentro de uma sessão do Claude Code, portanto execute o comando do seu próprio terminal. Requer Claude Code v2.1.271 ou posterior | |
1303| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout, no [mesmo formato que `plugin install --json`](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior | |
1304| `-h, --help` | Exiba ajuda para o comando | |
1305
1306<Note>
1307 Claude Code resolve um nome de plugin simples contra seus plugins instalados. Quando plugins instalados de diferentes marketplaces compartilham o nome, Claude Code recusa a atualização e lista os comandos `plugin-name@marketplace-name` qualificados para executar em vez disso. Antes da v2.1.246, Claude Code aceitava apenas o formulário qualificado e rejeitava um nome simples como não encontrado.
1308</Note>
1309
1310***
1311
1312<h3 id="plugin-list">
1313 plugin list
1314</h3>
1315
1316Liste plugins instalados com sua versão, marketplace de origem e status de ativação.
1317
1318```bash theme={null}
1319claude plugin list [options]
1320```
1321
1322O comando aceita estas opções:
1323
1324| Opção | Descrição | Padrão |
1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1326| `--json` | Saída como JSON. Uma linha de plugin com problemas de carregamento ou avisos de autoria carrega arrays de strings `errors` ou `notes`. No Claude Code v2.1.268 ou posterior, arrays `errorDetails` e `noteDetails` paralelos fornecem a cada entrada seu `type` de diagnóstico e os nomes aos quais se refere, como o plugin, marketplace, servidor ou arquivo | |
1327| `--available` | Inclua plugins disponíveis dos marketplaces. Requer `--json` | |
1328| `-h, --help` | Exiba ajuda para o comando | |
1329
1330Dentro de uma sessão interativa, `/plugin list` imprime uma listagem similar inline, mas cobre apenas plugins instalados do marketplace:
1331
1332* 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`.
1333* [Plugins sincronizados de claude.ai](#synced-plugins) aparecem em `claude plugin list` no Claude Code v2.1.239 ou posterior e na interface `/plugin`, mas não na saída inline `/plugin list`.
1334* 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.
1335
1336O formulário interativo aceita `--enabled` ou `--disabled` para mostrar apenas plugins nesse estado, e `ls` como abreviação para `list`.
1337
1338<h3 id="plugin-details">
1339 plugin details
1340</h3>
1341
1342Mostre 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/`.
1343
1344```bash theme={null}
1345claude plugin details <name>
1346```
1347
1348O comando toma estes argumentos:
1349
1350* `<name>`: Nome do plugin ou `plugin-name@marketplace-name`
1351
1352O comando aceita estas opções:
1353
1354| Opção | Descrição | Padrão |
1355| :----------- | :------------------------- | :----- |
1356| `-h, --help` | Exiba ajuda para o comando | |
1357
1358A saída mostra dois números de custo para cada componente:
1359
1360* **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.
1361* **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.
1362
1363Este exemplo mostra como a saída se parece para um plugin com duas skills:
1364
1365```
1366dependency-guard 1.2.0
1367 Dependency analysis for Claude Code sessions
1368 Source: dependency-guard@example-marketplace
1369
1370Component inventory
1371 Skills (2) scan-dependencies, review-changes
1372 Agents (0)
1373 Hooks (1) SessionStart (harness-only — no model context cost)
1374 MCP servers (0)
1375 LSP servers (0)
1376
1377Projected token cost
1378 Always-on: ~180 tok added to every session
1379
1380Per-component (rounded)
1381 component always-on on-invoke
1382 scan-dependencies ~100 ~2400
1383 review-changes ~80 ~1800
1384
1385 On-invoke cost is paid each time a skill or agent fires.
1386 Token counts are estimates and may differ from actual usage.
1387```
1388
1389O 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.
1390
1391<h3 id="plugin-validate">
1392 plugin validate
1393</h3>
1394
1395Verifique um plugin ou um marketplace para erros de sintaxe e esquema antes de publicar.
1396
1397O 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.
1398
1399```bash theme={null}
1400claude plugin validate <path> [options]
1401```
1402
1403O comando toma estes argumentos:
1404
1405* `<path>`: Caminho para um diretório de plugin ou um diretório de marketplace. Consulte [Validate a plugin or a directory without a manifest](/docs/pt/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) para quais arquivos uma execução de plugin cobre.
1406
1407O comando aceita estas opções:
1408
1409| Opção | Descrição | Padrão |
1410| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1411| `--strict` | Trate avisos como erros e saia com 1 neles. Use em CI para capturar problemas que o runtime tolera, como [unrecognized fields](#unrecognized-fields) | |
1412| `--json` | Saída do relatório de validação como um objeto JSON com os mesmos códigos de saída. Requer Claude Code v2.1.259 ou posterior | |
1413| `-h, --help` | Exiba ajuda para o comando | |
1414
1415Com `--json`, Claude Code escreve o relatório para stdout como um objeto JSON com estes campos de nível superior:
1416
1417* `success`: o mesmo veredicto que o código de saída fornece
1418* `strict`: se a execução tratou avisos como erros
1419* `target`: o caminho resolvido que Claude Code validou
1420* `manifest`: o resultado do próprio manifesto, ou `null` para uma [execução sem manifesto](/docs/pt/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)
1421* `contents`: resultados por arquivo, cada um nomeando seu `file` e carregando arrays `errors`, `warnings` e `notes`
1422
1423Na saída 2, o comando não escreve nada para stdout; a mensagem de erro vai para stderr.
1424
1425Dentro de uma sessão interativa, `/plugin validate <path>` executa as mesmas verificações inline.
1426
1427<h3 id="plugin-eval">
1428 plugin eval
1429</h3>
1430
1431Execute [eval cases](/docs/pt/plugin-evals) de um plugin e relate resultados pontuados. Requer Claude Code v2.1.269 ou posterior. Cada caso é um prompt mais avaliadores; Claude Code o executa várias vezes em uma sessão isolada com apenas o plugin alvo carregado, e por padrão também sem o plugin para que o relatório mostre a diferença. Consulte [Test plugins with evals](/docs/pt/plugin-evals) para o formato do caso, avaliadores, resultados e uso em CI.
1432
1433```bash theme={null}
1434claude plugin eval [target] [options]
1435```
1436
1437O `target` opcional é um diretório de plugin, um único arquivo `prompt.md` ou `case.yaml`, um plugin instalado como `name` ou `name@marketplace`, ou `name@skills-dir`, e padrão é o diretório atual. Coloque-o antes de `--tag`, `--allow-tools` e `--json`.
1438
1439Esta tabela lista as opções que a maioria das execuções usa. Execute `claude plugin eval --help` para o conjunto completo, incluindo `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp` e `--verbose`.
1440
1441| Opção | Descrição | Padrão |
1442| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
1443| `--runs <n>` | Execuções por caso por braço | Cada `runs` do caso, senão 3 |
1444| `-j, --concurrency <n>` | Sessões de agent para executar de uma vez, 1 a 8. Elas compartilham seu limite de taxa | `1` |
1445| `--model <model>` | Modelo para o agent sob teste | Cada `model` do caso, senão `ANTHROPIC_MODEL` se definido, senão padrão do Claude Code |
1446| `--judge-model <model>` | Modelo para avaliadores `llm` e `baseline` | Um modelo pequeno e rápido |
1447| `--ablation <mode>` | `none` ou `with-without`. Consulte [Compare against a no-plugin baseline](/docs/pt/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` quando um plugin resolve, senão `none` |
1448| `--threshold <0..1>` | Saia com 1 se qualquer caso pontuar abaixo disso | `1.0` |
1449| `--max-cost-usd <usd>` | Pare antes da próxima execução uma vez que o gasto atinja isso, saia com 2 e relate resultados parciais | Sem limite |
1450| `--allow-tools <tools...>` | Conceda ferramentas além do conjunto somente leitura, como `Bash`, `Write`, `Edit` ou `"mcp__plugin_<plugin>_<server>__*"`. Consulte [Grant tools](/docs/pt/plugin-evals#grant-tools) | |
1451| `--scaffold` | Execute cada [`scaffold_script`](/docs/pt/plugin-evals#add-setup-or-history-with-case-yaml) do caso | Desligado |
1452| `--trust-plugin` | Pule o prompt de confiança de primeira execução, para CI. Consulte [What a run can access](/docs/pt/plugin-evals#security) | Desligado |
1453| `--mocks <mode>` | `record` ou `off`. Consulte [Mock MCP servers](/docs/pt/plugin-evals#mock-mcp-servers) | `record` |
1454| `--eval-dir <dir>` | Diretório abaixo do plugin que contém os casos | O `experimental.evals` do manifesto, senão `evals` |
1455| `--json [path]` | Imprima o [documento de resultado](/docs/pt/plugin-evals#json-result) para stdout, ou escreva-o em um caminho `.json` | |
1456| `--no-publish` | Mantenha o relatório HTML local | |
1457| `-h, --help` | Exiba ajuda para o comando | |
1458
1459O comando sai com 0 quando cada caso atende ao limite, 1 em um caso falhando, um erro de carregamento ou um diretório de plugin não confiável, 2 em uma execução parcial, 130 quando interrompido e 143 quando terminado. Consulte [Run evals in CI](/docs/pt/plugin-evals#run-evals-in-ci).
1460
1461<h3 id="plugin-eval-init">
1462 plugin eval init
1463</h3>
1464
1465Crie um conjunto de eval para o plugin no diretório atual. Requer Claude Code v2.1.269 ou posterior. Em um terminal, isso inicia uma entrevista de autoria que lê o plugin, propõe casos e avaliadores, os testa e escreve os arquivos. Com `--bare`, ou sem um terminal, escreve um modelo de caso único em branco em vez disso. Execute de dentro de uma sessão interativa do Claude Code, imprime as instruções da entrevista para essa sessão seguir em vez de escrever um modelo. Consulte [Create your first eval suite](/docs/pt/plugin-evals#create-your-first-eval-suite).
1466
1467```bash theme={null}
1468claude plugin eval init [name] [options]
1469```
1470
1471O `name` opcional é um nome de caso: a entrevista não precisa de um, enquanto `--bare` e o caminho do modelo sem terminal o requerem. Aceita estas opções:
1472
1473| Opção | Descrição | Padrão |
1474| :------------------ | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
1475| `--bare` | Escreva um `prompt.md` em branco e `graders/criteria.md` para `<name>` em vez de executar a entrevista | |
1476| `-i, --interactive` | Exija a entrevista. Falha sem um terminal em vez de escrever um modelo | |
1477| `--eval-dir <dir>` | Diretório abaixo do diretório atual para escrever casos em | O `experimental.evals` do manifesto, senão `evals` |
1478| `-h, --help` | Exiba ajuda para o comando | |
1479
1480<h3 id="plugin-tag">
1481 plugin tag
1482</h3>
1483
1484Crie 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](/docs/pt/plugin-dependencies#tag-plugin-releases-for-version-resolution).
1485
1486```bash theme={null}
1487claude plugin tag [path] [options]
1488```
1489
1490O comando toma estes argumentos:
1491
1492* `[path]`: Caminho para o diretório do plugin. Padrão é o diretório atual.
1493
1494O comando aceita estas opções:
1495
1496| Opção | Descrição | Padrão |
1497| :-------------------- | :----------------------------------------------------------------------- | :------- |
1498| `--push` | Envie a tag para o remoto após criá-la | |
1499| `--dry-run` | Imprima o que seria marcado sem criar a tag | |
1500| `-f, --force` | Crie a tag mesmo que a árvore de trabalho esteja suja ou a tag já exista | |
1501| `-m, --message <msg>` | Mensagem de anotação de tag. Use `%s` como placeholder para a versão | |
1502| `--remote <name>` | Remoto para enviar com `--push` | `origin` |
1503| `-h, --help` | Exiba ajuda para o comando | |
1504
1505***
1506
1507<h2 id="debugging-and-development-tools">
1508 Ferramentas de depuração e desenvolvimento
1509</h2>
1510
1511<h3 id="debugging-commands">
1512 Comandos de depuração
1513</h3>
1514
1515Use `claude --debug` para ver detalhes do carregamento de plugins:
1516
1517Isso mostra:
1518
1519* Quais plugins estão sendo carregados
1520* Quaisquer erros nos manifestos de plugins
1521* Registro de skills, agents e hooks
1522* Inicialização do servidor MCP
1523
1524<h3 id="common-issues">
1525 Problemas comuns
1526</h3>
1527
1528| Problema | Causa | Solução |
1529| :---------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1530| Plugin não carregando | `plugin.json` inválido | Execute `claude plugin validate ./my-plugin` ou `/plugin validate ./my-plugin`, onde `./my-plugin` é seu diretório de plugin, para verificar `plugin.json`, `hooks/hooks.json` e o frontmatter das skills, agents e commands nos diretórios padrão do plugin para erros de sintaxe e esquema. Veja [Validate a plugin or a directory without a manifest](/docs/pt/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) para saber o que uma execução cobre |
1531| Skills não aparecendo | Estrutura de diretório incorreta | Certifique-se de que `skills/` ou `commands/` está na raiz do plugin, não dentro de `.claude-plugin/` |
1532| Hooks não disparando | Script não executável | Execute `chmod +x script.sh` |
1533| Servidor MCP falha | `${CLAUDE_PLUGIN_ROOT}` ausente | Use variável para todos os caminhos de plugin |
1534| Erros de caminho | Caminhos absolutos usados | Torne os caminhos relativos, começando com `./`; veja [Path behavior rules](#path-behavior-rules), que cobrem a exceção `"."` do campo `skills` |
1535| LSP `Executable not found in $PATH` | Servidor de linguagem não instalado | Instale o binário (por exemplo, `npm install -g typescript-language-server typescript`) |
1536
1537<h3 id="example-error-messages">
1538 Exemplos de mensagens de erro
1539</h3>
1540
1541**Erros de validação de manifesto**:
1542
1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: verifique se há vírgulas ausentes, vírgulas extras ou strings sem aspas
1544* `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
1545* `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.
1546
1547**Erros de carregamento de plugin**:
1548
1549* `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
1550* `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
1551* `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
1552
1553<h3 id="hook-troubleshooting">
1554 Solução de problemas de hooks
1555</h3>
1556
1557**Script de hook não executando**:
1558
15591. Verifique se o script é executável: `chmod +x ./scripts/your-script.sh`
15602. Verifique a linha shebang: A primeira linha deve ser `#!/bin/bash` ou `#!/usr/bin/env bash`
15613. Verifique se o caminho usa `${CLAUDE_PLUGIN_ROOT}`: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
15624. Teste o script manualmente: `./scripts/your-script.sh`
1563
1564**Hook não disparando em eventos esperados**:
1565
15661. Verifique se o nome do evento está correto (sensível a maiúsculas): `PostToolUse`, não `postToolUse`
15672. Verifique se o padrão do matcher corresponde às suas ferramentas: `"matcher": "Write|Edit"` para operações de arquivo
15683. Confirme se o tipo de hook é válido: `command`, `http`, `mcp_tool`, `prompt` ou `agent`
1569
1570<h3 id="mcp-server-troubleshooting">
1571 Solução de problemas do servidor MCP
1572</h3>
1573
1574**Servidor não iniciando**:
1575
15761. Verifique se o comando existe e é executável
15772. Verifique se todos os caminhos usam a variável `${CLAUDE_PLUGIN_ROOT}`
15783. Verifique os logs do servidor MCP: `claude --debug` mostra erros de inicialização
15794. Teste o servidor manualmente fora do Claude Code
1580
1581**Ferramentas do servidor não aparecendo**:
1582
15831. Certifique-se de que o servidor está configurado corretamente em `.mcp.json` ou `plugin.json`
15842. Verifique se o servidor implementa o protocolo MCP corretamente
15853. Verifique se há timeouts de conexão na saída de depuração
1586
1587<h3 id="directory-structure-mistakes">
1588 Erros de estrutura de diretório
1589</h3>
1590
1591**Sintomas**: Plugin carrega mas componentes (skills, agents, hooks) estão ausentes.
1592
1593**Estrutura correta**: Componentes devem estar na raiz do plugin, não dentro de `.claude-plugin/`. Apenas `plugin.json` pertence a `.claude-plugin/`.
1594
1595**Lista de verificação de depuração**:
1596
15971. Execute `claude --debug` e procure por mensagens "loading plugin"
15982. Verifique se cada diretório de componente está listado na saída de depuração
15993. Verifique se as permissões de arquivo permitem ler os arquivos do plugin
1600
1601***
1602
1603<h2 id="distribution-and-versioning-reference">
1604 Referência de distribuição e versionamento
1605</h2>
1606
1607<h3 id="version-management">
1608 Gerenciamento de versão
1609</h3>
1610
1611Claude 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. Um plugin [carregado no local](#plugin-caching-and-file-resolution) a partir de um marketplace de diretório local carrega seus arquivos de fonte atuais no início de cada sessão, independentemente do que sua string de versão diz.
1612
1613Para cada tipo de fonte, exceto `command`, Claude Code resolve a versão a partir do primeiro destes que está definido:
1614
16151. O campo `version` no `plugin.json` do plugin
16162. O campo `version` na entrada do marketplace do plugin em `marketplace.json`
16173. O SHA do commit git da fonte do plugin, para fontes `github`, `url`, `git-subdir` e relative-path em um marketplace hospedado em git
16184. O resumo SHA-256, para [fontes `archive`](/docs/pt/plugin-marketplaces#zip-archives): 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
16195. `unknown`, para fontes `npm` ou diretórios locais quando nem o diretório do plugin nem seu marketplace é um repositório git. Claude Code não obtém a versão de um repositório que envolve o caminho de instalação, como um `~/.claude` gerenciado por git
1620
1621Para uma [fonte `command`](/docs/pt/plugin-marketplaces#command-sources), 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](/docs/pt/plugin-marketplaces#copy-mode-and-link-mode), o hash cobre o caminho real do diretório impresso e suas entradas de nível superior em vez do conteúdo do arquivo.
1622
1623Para esses tipos de fonte, isso oferece três maneiras de versionar um plugin:
1624
1625| Abordagem | Como | Comportamento de atualização | Melhor para |
1626| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
1627| **Versão explícita** | Defina `"version": "2.1.0"` em `plugin.json` | Os usuários recebem atualizações apenas quando você incrementa este campo. Enviar novos commits sem incrementá-lo não tem efeito, e `/plugin update` relata "já está na versão mais recente". Para um plugin [carregado no local](#plugin-caching-and-file-resolution), o novo conteúdo é carregado de qualquer forma. | Plugins publicados com ciclos de lançamento estáveis |
1628| **Versão Commit-SHA** | Omita `version` tanto de `plugin.json` quanto da entrada do marketplace | Os usuários recebem atualizações sempre que o commit resolvido da fonte muda | Plugins internos ou de equipe em desenvolvimento ativo |
1629| **Versão Digest** | Use uma [fonte `archive`](/docs/pt/plugin-marketplaces#zip-archives) e omita `version` tanto de `plugin.json` quanto da entrada do marketplace | Com um pin `sha256`, os usuários recebem atualizações quando você altera o pin. Sem um, os usuários recebem atualizações sempre que os bytes do arquivo zip hospedado mudam | Plugins publicados como arquivos zip em um servidor estático ou repositório de artefatos |
1630
1631Se você usar versões explícitas, siga [versionamento semântico](https://semver.org) (`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`.
1632
1633***
1634
1635<h2 id="see-also">
1636 Veja também
1637</h2>
1638
1639* [Plugins](/docs/pt/plugins) - Tutoriais e uso prático
1640* [Marketplaces de plugins](/docs/pt/plugin-marketplaces) - Criando e gerenciando marketplaces
1641* [Skills](/docs/pt/skills) - Detalhes de desenvolvimento de skill
1642* [Subagents](/docs/pt/sub-agents) - Configuração e capacidades de agent
1643* [Hooks](/docs/pt/hooks) - Manipulação de eventos e automação
1644* [MCP](/docs/pt/mcp) - Integração de ferramenta externa
1645* [Configurações](/docs/pt/settings) - Opções de configuração para plugins
