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