Referência de manifesto de plugin

Referência completa para plugin.json: cada campo com seu tipo e padrão, formas de caminho aceitas e os esquemas de userConfig e variáveis de ambiente.

Um manifesto de plugin é o arquivo plugin.json no diretório .claude-plugin/ de um plugin. Ele contém os metadados do plugin e os valores de userConfig que Claude Code solicita ao usuário. Também declara qualquer componente que você define inline ou mantém fora de seu local padrão.

Esta referência é para criadores de plugins e para proprietários de marketplace que colocam campos de componentes em uma entrada de marketplace.

Comece na seção que corresponde ao que você está procurando:

• Um campo: a tabela Campos fornece o tipo de cada campo, se é obrigatório, seu padrão e o que aceita. Regras de caminho cobre o prefixo ./ e contenção para cada caminho de componente
• Uma opção userConfig ou uma entrada channels: os esquemas Configuração do usuário e Canais
• ${CLAUDE_PLUGIN_ROOT} ou outra variável que um plugin pode referenciar: Variáveis de ambiente
• Onde os arquivos de cada componente vão: Layout padrão
• Uma mensagem de claude plugin validate: a página de solução de problemas lista cada mensagem com sua correção e links para as seções relevantes nesta página

Arquivo de manifesto

O manifesto é opcional. Sem ele, Claude Code carrega os componentes que encontra no layout padrão. O nome do plugin vem da entrada do marketplace ou do nome do diretório quando você carrega o plugin com --plugin-dir.

Escreva um manifesto quando quiser metadados, um componente fora de seu diretório padrão, userConfig ou uma definição de componente inline.

Salve o manifesto em .claude-plugin/plugin.json sob a raiz do plugin. Coloque todos os outros arquivos do plugin na raiz do plugin, não dentro de .claude-plugin/. Isso inclui skills/, commands/ e hooks/.

O exemplo a seguir define a maioria das chaves na tabela Campos. Ele passa na validação em um diretório de plugin que contém cada caminho referenciado.

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

Campos não reconhecidos

Uma chave de nível superior não reconhecida é removida, e uma chave não reconhecida dentro de uma opção userConfig, entrada channels, configuração lspServers ou entrada monitors é rejeitada:

• Campos de nível superior: o campo é removido e o plugin carrega. claude plugin validate relata cada campo de nível superior não reconhecido como um aviso
• Objetos estritos: opções userConfig, entradas channels, configurações lspServers e entradas monitors são estritas. Uma chave desconhecida dentro de uma é um erro, e o plugin não carrega

Validar o manifesto

claude plugin validate é a verificação autoritária para um manifesto. Execute-o do seu shell contra o diretório do plugin:

claude plugin validate ./my-plugin

O comando relata um destes resultados:

• Validation passed: o manifesto carrega
• Validation passed with warnings: o manifesto carrega, mas o validador encontrou algo para corrigir, como um campo de nível superior desconhecido que Claude Code remove, um name que não está em kebab-case, ou um version, description ou author ausente. Passe --strict para transformar avisos em falhas em CI
• Validation failed: o manifesto tem uma incompatibilidade de tipo, um caminho que está faltando ou escapa da raiz do plugin, ou uma chave desconhecida dentro de uma opção userConfig, entrada channels, configuração lspServers ou entrada monitors. Claude Code relata o mesmo problema quando carrega o plugin

Campos

A tabela lista as chaves de nível superior em plugin.json. name é a única chave obrigatória. Quando um nome de campo é um link, a seção vinculada tem suas regras completas.

Para chaves de componentes como commands e hooks, Formas de caminho de componente mostra cada forma aceita com um exemplo, e cada caminho segue as regras de caminho para o prefixo ./, extensões e contenção.

Na coluna Tipo, um caminho é uma string relativa à raiz do plugin, como "./custom/commands".

`name`

O identificador do plugin. Deve ser não vazio, sem espaços, @, :, separadores de caminho, caracteres de controle ou caracteres de formatação bidirecional; use kebab-case.

Claude Code namespaces cada componente sob ele, então um agente reviewer no plugin deploy-tools aparece como deploy-tools:reviewer.

`displayName`

O nome mostrado na UI no lugar de name. Pode conter espaços e qualquer capitalização, e não é usado para namespacing ou lookup.

Para um plugin instalado do marketplace, um displayName na entrada do marketplace tem precedência sobre este valor.

`version`

Uma string de versão, não verificada contra semver. Configurá-la fixa o plugin nessa versão até você alterá-la; veja Versões e atualizações. Um plugin com uma command source, um plugin de um marketplace hospedado em claude.ai e um plugin carregado no local de um marketplace adicionado como um diretório local não são fixados por este campo.

`metadata`

Um objeto de forma livre para seus próprios dados, como campos de catálogo ou direito. Claude Code não o lê. Requer Claude Code v2.1.222 ou posterior.

`defaultEnabled`

Se o plugin inicia habilitado quando o usuário não o configurou em enabledPlugins. Padrão é true. Um plugin que um plugin habilitado depende inicia habilitado independentemente. O mesmo campo na entrada do marketplace substitui este.

Uma vez que a entrada enabledPlugins de um usuário é escrita, ela persiste entre atualizações de plugin, então alterar defaultEnabled em uma versão posterior não altera a configuração para um usuário existente.

`dependencies`

Plugins que devem estar habilitados para este funcionar. Cada entrada é "name", "name@marketplace" ou { "name": "...", "marketplace": "...", "version": "..." }. Nomes simples resolvem contra o próprio marketplace deste plugin. Veja restrições de dependência.

`settings`

Configurações que Claude Code aplica enquanto o plugin está habilitado. Apenas agent e subagentStatusLine têm efeito; outras chaves são removidas no carregamento. Um settings.json na raiz do plugin tem precedência sobre esta chave. Veja Configurações padrão.

Formas de caminho de componente

Cada chave de componente aceita um caminho relativo à raiz do plugin. hooks, mcpServers, lspServers e experimental.monitors também aceitam configuração inline, commands também aceita um mapa de objeto, e mcpServers também aceita caminhos de bundle MCP e URLs. Os exemplos a seguir mostram cada forma aceita uma vez. Para o que cada componente faz em tempo de execução, veja Componentes de plugin.

Campos apenas de caminho

agents, skills, outputStyles, workflows e experimental.themes recebem um caminho ou um array de caminhos. Entradas agents devem ser arquivos .md, e entradas skills devem ser diretórios. Os outros três aceitam um diretório ou um arquivo.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

`commands`

commands recebe um caminho, um array de caminhos, ou um mapa de objeto. Um caminho nomeia um arquivo de comando .md plano ou um diretório. No mapa de objeto, cada chave se torna o nome do comando após o prefixo do plugin. Por exemplo, "about" no plugin deploy-tools executa como /deploy-tools:about.

Cada valor define exatamente um de source ou content, e uma entrada que define ambos ou nenhum falha na validação. Os outros campos nesta tabela são opcionais:

Este mapa declara um comando de um arquivo e um de conteúdo inline:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

`hooks`

hooks recebe um caminho de arquivo .json, um objeto de hooks inline na mesma forma que hooks em settings.json, ou um array misturando ambos. Para eventos de hook e campos de handler, veja a referência de hooks.

Claude Code mescla o que você declara com hooks/hooks.json quando esse arquivo existe.

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

`mcpServers`

mcpServers recebe um caminho de arquivo .json, um caminho de bundle MCP ou URL, um mapa inline, ou um array misturando-os. Para campos de configuração de servidor, veja servidores MCP fornecidos por plugin.

Claude Code carrega .mcp.json na raiz do plugin primeiro, depois cada forma declarada em ordem. Um nome de servidor declarado depois substitui um anterior.

Um valor mcpServers recebe uma destas formas:

Um caminho de bundle ou URL deve terminar em .mcpb ou .dxt. Qualquer outra extensão falha na validação.

`lspServers`

lspServers recebe um caminho de arquivo .json, um mapa inline de nome de servidor para configuração, ou um array de qualquer um.

Claude Code carrega .lsp.json na raiz do plugin primeiro, depois cada configuração declarada em ordem. Um nome de servidor declarado depois substitui um anterior.

Cada configuração de servidor é um objeto estrito com estes campos. Uma chave desconhecida falha na validação.

Esta configuração inline executa gopls para arquivos .go:

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

Para os servidores de linguagem que Anthropic publica como plugins e como os servidores se comportam em tempo de execução, veja Inteligência de código.

`monitors`

experimental.monitors recebe um caminho de arquivo .json ou o array inline. Quando você omite a chave, Claude Code carrega monitors/monitors.json se existir.

Cada entrada é um objeto estrito com estes campos.

Este array inline declara um monitor que inicia a primeira vez que a skill deploy executa:

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Um command de monitor não pode referenciar ${user_config.*}. Veja Campos que executam através de um shell.

Regras de caminho

Cada caminho de componente em um manifesto é relativo à raiz do plugin e deve começar com ./. Um caminho como commands/foo.md falha na validação. skills e mcpServers cada um aceitam uma forma fora dessa regra:

• skills: também aceita ".". Ambos "." e "./" denotam a raiz do plugin. Antes de v2.1.221, "." falhou na validação do manifesto, então use "./" quando o plugin deve carregar em versões anteriores
• mcpServers: também aceita uma URL de bundle https://

Contenção e existência

Cada caminho de componente deve resolver dentro da raiz do plugin e deve existir. claude plugin validate não verifica os caminhos outputStyles, lspServers, monitors ou themes, então um caminho ruim nesses campos falha apenas quando o plugin carrega:

• Contenção: um caminho que resolve fora da raiz do plugin não carrega, e a aba Errors do /plugin mostra <component> path escapes plugin directory: <path>. Um caminho contendo .. é o caso usual, e claude plugin validate o relata como Path contains ".." which could be a path traversal attempt
• Existência: um caminho que não existe não carrega, e a aba Errors do /plugin mostra <component> path not found: <path>. claude plugin validate o relata como Path not found

Como cada chave se combina com seu local padrão

Cada chave de componente substitui seu local padrão, adiciona a ele, ou mescla com ele:

• Substitui o padrão: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. Quando você define commands, o diretório padrão commands/ não é escaneado. Para manter o padrão e adicionar mais, liste-o explicitamente: "commands": ["./commands/", "./extras/"]
• Adiciona ao padrão: skills. O diretório skills/ ainda é escaneado, e os diretórios listados carregam junto com ele
• Mescla: hooks, mcpServers, lspServers. O arquivo padrão carrega primeiro, e o que o manifesto declara mescla nele, conforme descrito em Formas de caminho de componente

Se um plugin tem uma pasta padrão como commands/ e também define a chave de manifesto que a substitui, Claude Code carrega os caminhos do manifesto e não a pasta. claude plugin list e a interface /plugin então mostram o aviso Default <folder>/ folder is ignored because the manifest sets "<key>".

Para evitar o aviso, defina a chave para um caminho dentro dessa pasta: "commands": ["./commands/deploy.md"] nomeia um arquivo na pasta padrão e não produz aviso.

Configuração do usuário

userConfig declara valores que Claude Code solicita ao usuário quando o plugin está habilitado, para que os usuários não editem settings.json eles mesmos.

As chaves são identificadores feitos de letras, dígitos e underscores, e não podem começar com um dígito.

Cada valor é um objeto estrito com estes campos. Uma chave desconhecida falha na validação.

Cada opção de cada plugin habilitado também aparece como uma linha no painel /config, exceto opções sensitive e listas multiple. As linhas /config requerem Claude Code v2.1.269 ou posterior.

Este userConfig declara um endpoint e um token mascarado:

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

Limitar um campo a opções fixas

Defina options em um campo userConfig para fazer os usuários escolherem seu valor de uma lista fixa.

Para limitar um campo tone a três opções, liste-as em options e defina default para uma delas:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

Se você declarar options em qualquer campo, usuários em versões Claude Code antes de v2.1.271 não podem carregar o plugin.

options se aplica a um campo string que não é multiple ou sensitive. Defina default para um dos valores listados, ou defina required: true para que o usuário escolha um. Cada opção é um rótulo simples de 1 a 64 caracteres, e claude plugin validate, que você executa no seu shell, relata qualquer coisa que rejeita. Um plugin cujas options quebram essas regras falha ao carregar.

Onde os valores são armazenados

Valores não sensíveis são salvos em pluginConfigs no settings.json do usuário. Valores sensíveis vão para o armazenamento de credenciais seguro da plataforma. A página de configurações lista quais arquivos de configurações pluginConfigs é lido.

Referenciar um valor salvo

Referencie um valor salvo onde o plugin precisa dele, em uma de duas formas:

• ${user_config.KEY}: substituído em configuração de servidor MCP, configuração de servidor LSP, hook args em forma exec, e conteúdo de skill e agente. Em conteúdo de skill e agente, apenas valores não sensíveis são substituídos, e um valor sensível lá se torna um placeholder
• CLAUDE_PLUGIN_OPTION_<KEY>: exportado para processos de hook para cada opção, com <KEY> em maiúsculas. Um hook em forma shell lê $CLAUDE_PLUGIN_OPTION_API_TOKEN para api_token

Campos que executam através de um shell

Comandos de hook em forma shell, comandos de monitor e MCP headersHelper rejeitam ${user_config.*}. Um componente que o referencia em um desses campos falha com um erro em vez de executar, porque o valor do campo é passado para um shell que re-analisaria o valor substituído.

A tabela mostra como o valor pode chegar a cada um desses campos.

Canais

channels declara os canais de mensagem que um plugin fornece, como uma ponte para um aplicativo de chat. Quando você declara um, Claude Code pode solicitar a configuração do canal quando o plugin está habilitado. Para como o servidor injeta mensagens, veja a referência de canais.

Cada entrada é um objeto estrito vinculado a um dos servidores MCP do plugin, com estes campos:

Este manifesto vincula um canal ao servidor MCP telegram do plugin e solicita um token de bot que substitui no env do servidor:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

Variáveis de ambiente

Claude Code fornece três variáveis de caminho para componentes de plugin. Referencie-as como ${NAME} nos campos listados em Onde cada variável resolve, e leia-as como variáveis de ambiente nos processos que as recebem.

${CLAUDE_PLUGIN_ROOT} muda quando o plugin atualiza, então não escreva estado lá. Para onde a raiz se move e quando o diretório antigo é limpo, veja a página de carregamento.

Quando você desinstala o plugin do último lugar onde está instalado, o diretório ${CLAUDE_PLUGIN_DATA} é deletado a menos que você passe --keep-data.

Onde cada variável resolve

Em cada componente de plugin, referências ${...} resolvem inline em campos específicos, e alguns componentes também recebem as variáveis em seu ambiente de processo:

As variáveis 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 skill, comando e agente, escreva a referência ${...} no corpo Markdown em vez disso, e Claude Code substitui o caminho inline quando carrega o conteúdo.

Citação e separadores de caminho

Mantenha cada caminho substituído um único argumento:

• Comandos de hook: use forma exec com args para que cada caminho seja um argumento sem citação
• Hooks em forma shell e comandos de monitor: envolva a variável em aspas duplas para que um caminho com espaços permaneça uma palavra

Este hook em forma shell executa um script agrupado com o plugin:

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

No Windows, os caminhos substituídos usam barras para frente para que um shell não leia barras invertidas como escapes.

Layout padrão

Cada tipo de componente tem um local padrão sob a raiz do plugin, usado quando o manifesto não aponta para outro lugar.

Um plugin que usa cada local padrão, mais uma pasta scripts/ que seus hooks chamam, é disposto assim:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

Para clicar através deste layout e ler o que cada arquivo faz, abra o explorador de plugin.

Um CLAUDE.md na raiz do plugin não é carregado como contexto, e claude plugin validate avisa quando encontra um. Para incluir instruções que carregam no contexto de Claude, coloque-as em uma skill.

Entradas de marketplace e o manifesto

Uma entrada de marketplace aceita cada campo nesta página junto com seus próprios campos, incluindo strict.

O campo strict decide se a entrada pode adicionar componentes a um plugin que tem seu próprio plugin.json. Padrão é true.

Como campos de entrada se combinam com `plugin.json`

A entrada serve como o manifesto, adiciona componentes a ele, ou entra em conflito com ele:

• Sem plugin.json: a entrada é o manifesto, independentemente de strict. Hooks de entrada carregam apenas na forma de objeto inline. Para um caminho de arquivo ou array lá, a aba Errors do /plugin mostra um erro not yet supported in a marketplace entry
• plugin.json presente, strict não definido ou true: Claude Code carrega o manifesto e anexa commands, agents, skills, outputStyles e themes da entrada a ele. Para hooks, os matchers da entrada para um evento substituem os matchers do manifesto para esse mesmo evento, e eventos que apenas o manifesto declara mantêm os deles
• plugin.json presente, strict: false: uma entrada que declara qualquer um de commands, agents, skills, hooks, outputStyles ou themes é um conflito, e o plugin falha ao carregar com Plugin <name> has conflicting manifests

Quando uma entrada de marketplace cuja source é a raiz do marketplace lista subdiretórios skills específicos, apenas esses subdiretórios carregam, e o diretório padrão skills/ do plugin não é escaneado. Uma chave skills no manifesto em vez disso adiciona ao padrão.

Precedência de metadados

Alguns campos de metadados têm uma precedência fixa independentemente de strict:

• defaultEnabled e campos de exibição: o defaultEnabled da entrada e seus campos de exibição como displayName substituem os do manifesto
• version: o version do manifesto substitui o da entrada
• name: quando a entrada lista o plugin sob um name diferente do manifesto, enabledPlugins usa o nome da entrada, e componentes são namespaced sob o nome do manifesto

Para a tabela de precedência completa, veja Modo estrito.

Próximos passos

• Adicionar componentes a um plugin: o que cada componente faz em tempo de execução, com um exemplo que valida
• Referência de marketplace: os campos de entrada que um marketplace pode definir para seu plugin
• Referência de comandos de plugin: flags e saída de claude plugin validate
• Solucionar problemas de plugins: cada mensagem de validação com sua correção