Referência de manifesto de plugin

• 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

{
  "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

• 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 ./my-plugin

• 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

​

name

​

displayName

​

version

​

metadata

​

defaultEnabled

​

dependencies

​

settings

​

Formas de caminho de componente

​

Campos apenas de caminho

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

​

commands

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

​

hooks

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

​

mcpServers

​

lspServers

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

​

monitors

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

​

Regras de caminho

• 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

• 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

• 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

​

Configuração do usuário

{
  "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

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

​

Onde os valores são armazenados

​

Referenciar um valor salvo

• ${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

​

Canais

{
  "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

​

Onde cada variável resolve

​

Citação e separadores de caminho

• 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

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

​

Layout padrão

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

​

Entradas de marketplace e o manifesto

​

Como campos de entrada se combinam com plugin.json

• 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

​

Precedência de metadados

• 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

​

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