プラグインマニフェストリファレンス

plugin.json の完全なリファレンス：すべてのフィールドとその型、デフォルト値、受け入れられるパス形式、userConfig と環境変数スキーマ。

プラグインマニフェストは、プラグインの .claude-plugin/ ディレクトリにある plugin.json ファイルです。プラグインのメタデータと、Claude Code がユーザーに入力を促す userConfig 値を含みます。また、インラインで定義するか、デフォルトの場所の外に保持するコンポーネントを宣言します。

このリファレンスはプラグイン作成者向けであり、プラグインのコンポーネントフィールドをマーケットプレイスエントリに配置するマーケットプレイスオーナー向けです。

検索内容に一致するセクションから始めてください：

• フィールド：フィールドテーブルは各フィールドの型、必須かどうか、デフォルト値、受け入れられるものを示します。パスルールはすべてのコンポーネントパスの ./ プレフィックスと包含をカバーします
• userConfig オプションまたは channels エントリ：ユーザー設定とチャネルスキーマ
• ${CLAUDE_PLUGIN_ROOT} またはプラグインが参照できる別の変数：環境変数
• 各コンポーネントのファイルの場所：標準レイアウト
• claude plugin validate からのメッセージ：トラブルシューティングページは各メッセージとその修正、およびこのページの関連セクションへのリンクを一覧表示します

マニフェストファイル

マニフェストはオプションです。マニフェストがない場合、Claude Code は標準レイアウトで見つかるコンポーネントを読み込みます。その場合、プラグイン名はマーケットプレイスエントリから、または --plugin-dir でプラグインを読み込むときはディレクトリ名から取得されます。

メタデータ、デフォルトディレクトリの外のコンポーネント、userConfig、またはインラインコンポーネント定義が必要な場合は、マニフェストを作成してください。

マニフェストをプラグインルートの .claude-plugin/plugin.json に保存してください。他のすべてのプラグインファイルをプラグインルートに配置し、.claude-plugin/ の内部には配置しないでください。これには skills/、commands/、hooks/ が含まれます。

次の例はフィールドテーブルのほとんどのキーを設定します。参照されるすべてのパスを含むプラグインディレクトリで検証に合格します。

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

認識されないフィールド

認識されないトップレベルキーは削除され、userConfig オプション、channels エントリ、lspServers 設定、または monitors エントリ内の認識されないキーは拒否されます：

• トップレベルフィールド：フィールドは削除され、プラグインは読み込まれます。claude plugin validate は認識されないトップレベルフィールドを警告として報告します
• 厳密なオブジェクト：userConfig オプション、channels エントリ、lspServers 設定、monitors エントリは厳密です。その中の未知のキーはエラーであり、プラグインは読み込まれません

マニフェストを検証する

claude plugin validate はマニフェストの権威的なチェックです。シェルからプラグインディレクトリに対して実行してください：

claude plugin validate ./my-plugin

コマンドは次のいずれかの結果を報告します：

• Validation passed：マニフェストが読み込まれます
• Validation passed with warnings：マニフェストは読み込まれますが、バリデータが修正すべき点を見つけました。例えば、Claude Code が削除する未知のトップレベルフィールド、kebab-case でない name、または欠落している version、description、author などです。CI で警告をエラーに変えるには --strict を渡してください
• Validation failed：マニフェストに型の不一致、欠落しているか、プラグインルートを超えるパス、または userConfig オプション、channels エントリ、lspServers 設定、monitors エントリ内の未知のキーがあります。Claude Code はプラグインを読み込むときに同じ問題を報告します

フィールド

テーブルは plugin.json のトップレベルキーを一覧表示します。name は唯一の必須キーです。フィールド名がリンクの場合、リンク先のセクションに完全なルールがあります。

commands や hooks などのコンポーネントキーについては、コンポーネントパス形式は受け入れられる各形式を例とともに示し、すべてのパスは ./ プレフィックス、拡張子、包含のパスルールに従います。

型列では、パスはプラグインルートに相対する文字列です（例："./custom/commands"）。

`name`

プラグイン識別子。空でなく、スペース、@、:、パス区切り文字、制御文字、双方向フォーマット文字を含まない必要があります。kebab-case を使用してください。

Claude Code はすべてのコンポーネントをその下に名前空間化するため、プラグイン deploy-tools のエージェント reviewer は deploy-tools:reviewer として表示されます。

`displayName`

name の代わりに UI に表示される名前。スペースと任意の大文字小文字を含むことができ、名前空間化またはルックアップには使用されません。

マーケットプレイスにインストールされたプラグインの場合、マーケットプレイスエントリの displayName がこの値より優先されます。

`version`

semver に対してチェックされないバージョン文字列。設定すると、変更するまでプラグインはそのバージョンに固定されます。バージョンと更新を参照してください。command ソースを持つプラグイン、claude.ai でホストされているマーケットプレイスからのプラグイン、およびローカルディレクトリとして追加されたマーケットプレイスからその場で読み込まれたプラグインはこのフィールドで固定されません。

`metadata`

カタログまたは権利フィールドなど、独自のデータ用の自由形式オブジェクト。Claude Code は読み込みません。Claude Code v2.1.222 以降が必要です。

`defaultEnabled`

ユーザーが enabledPlugins で設定していない場合、プラグインが有効な状態で開始するかどうか。デフォルトは true。有効なプラグインが依存するプラグインは、関係なく有効な状態で開始されます。マーケットプレイスエントリの同じフィールドがこれをオーバーライドします。

ユーザーの enabledPlugins エントリが書き込まれると、プラグイン更新全体で保持されるため、後のリリースで defaultEnabled を変更しても、既存ユーザーの設定は変わりません。

`dependencies`

このプラグインが機能するために有効にする必要があるプラグイン。各エントリは "name"、"name@marketplace"、または { "name": "...", "marketplace": "...", "version": "..." } です。ベア名はこのプラグイン独自のマーケットプレイスに対して解決されます。依存関係の制約を参照してください。

`settings`

プラグインが有効な間に Claude Code が適用する設定。agent と subagentStatusLine のみが有効です。他のキーは読み込み時に削除されます。プラグインルートの settings.json がこのキーより優先されます。デフォルト設定を参照してください。

コンポーネントパス形式

すべてのコンポーネントキーはプラグインルートに相対するパスを受け入れます。hooks、mcpServers、lspServers、experimental.monitors はインライン設定も受け入れ、commands はオブジェクトマップも受け入れ、mcpServers は MCP バンドルパスと URL も受け入れます。以下の例は受け入れられる各形式を 1 回示します。各コンポーネントが実行時に何をするかについては、プラグインコンポーネントを参照してください。

パスのみのフィールド

agents、skills、outputStyles、workflows、experimental.themes は 1 つのパスまたはパスの配列を受け入れます。agents エントリは .md ファイルである必要があり、skills エントリはディレクトリである必要があります。他の 3 つはディレクトリまたはファイルを受け入れます。

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

`commands`

commands はパス、パスの配列、またはオブジェクトマップを受け入れます。パスはフラットな .md コマンドファイルまたはディレクトリを指定します。オブジェクトマップでは、各キーはプラグインプレフィックスの後のコマンド名になります。例えば、プラグイン deploy-tools の "about" は /deploy-tools:about として実行されます。

各値は source または content のいずれか 1 つを設定し、両方を設定するか、どちらも設定しないエントリは検証に失敗します。このテーブルの他のフィールドはオプションです：

このマップはファイルからの 1 つのコマンドとインラインコンテンツからの 1 つを宣言します：

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

`hooks`

hooks は .json ファイルパス、settings.json の hooksと同じ形状のインラインフックオブジェクト、またはその両方を混ぜた配列を受け入れます。フックイベントとハンドラーフィールドについては、フックリファレンスを参照してください。

Claude Code は、そのファイルが存在する場合、hooks/hooks.json で宣言したものをマージします。

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

`mcpServers`

mcpServers は .json ファイルパス、MCP バンドルパスまたは URL、インラインマップ、またはそれらを混ぜた配列を受け入れます。サーバー設定フィールドについては、プラグイン提供の MCP サーバーを参照してください。

Claude Code はプラグインルートの .mcp.json を最初に読み込み、次に宣言された各形状を順に読み込みます。後で宣言されたサーバー名は前のものを置き換えます。

mcpServers 値は次のいずれかの形状を取ります：

バンドルパスまたは URL は .mcpb または .dxt で終わる必要があります。他の拡張子は検証に失敗します。

`lspServers`

lspServers は .json ファイルパス、サーバー名から設定へのインラインマップ、またはその両方の配列を受け入れます。

Claude Code はプラグインルートの .lsp.json を最初に読み込み、次に宣言された各設定を順に読み込みます。後で宣言されたサーバー名は前のものを置き換えます。

各サーバー設定は、これらのフィールドを持つ厳密なオブジェクトです。未知のキーは検証に失敗します。

このインライン設定は .go ファイルに対して gopls を実行します：

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

Anthropic が公開する言語サーバープラグインと、サーバーが実行時にどのように動作するかについては、コード インテリジェンスを参照してください。

`monitors`

experimental.monitors は .json ファイルパスまたはインライン配列を受け入れます。キーを省略すると、Claude Code は存在する場合 monitors/monitors.json を読み込みます。

各エントリは、これらのフィールドを持つ厳密なオブジェクトです。

このインライン配列は、deploy スキルが初めて実行されるときに開始される 1 つのモニターを宣言します：

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

モニター command は ${user_config.*} を参照できません。シェルを通じて実行されるフィールドを参照してください。

パスルール

マニフェスト内のすべてのコンポーネントパスはプラグインルートに相対し、./ で始まる必要があります。commands/foo.md などのパスは検証に失敗します。skills と mcpServers は各々、そのルール外の 1 つの形式を受け入れます：

• skills："." も受け入れます。"." と "./" の両方がプラグインルートを示します。v2.1.221 より前では、"." はマニフェスト検証に失敗したため、プラグインが以前のバージョンで読み込まれる必要がある場合は "./" を使用してください
• mcpServers：https:// バンドル URL も受け入れます

包含と存在

すべてのコンポーネントパスはプラグインルート内で解決され、存在する必要があります。claude plugin validate は outputStyles、lspServers、monitors、themes パスをチェックしないため、これらのフィールドの不正なパスはプラグインが読み込まれるときにのみ失敗します：

• 包含：プラグインルート外で解決されるパスは読み込まれず、/plugin Errors タブに <component> path escapes plugin directory: <path> が表示されます。.. を含むパスが一般的なケースであり、claude plugin validate は Path contains ".." which could be a path traversal attempt として報告します
• 存在：存在しないパスは読み込まれず、/plugin Errors タブに <component> path not found: <path> が表示されます。claude plugin validate は Path not found として報告します

各キーがデフォルトの場所とどのように組み合わされるか

各コンポーネントキーは、デフォルトの場所を置き換えるか、追加するか、またはマージします：

• デフォルトを置き換える：commands、agents、outputStyles、workflows、experimental.themes、experimental.monitors。commands を設定すると、デフォルトの commands/ ディレクトリはスキャンされません。デフォルトを保持して追加するには、明示的にリストします："commands": ["./commands/", "./extras/"]
• デフォルトに追加：skills。skills/ ディレクトリはまだスキャンされ、リストされたディレクトリはそれと一緒に読み込まれます
• マージ：hooks、mcpServers、lspServers。デフォルトファイルが最初に読み込まれ、マニフェストが宣言したものはそれにマージされます。コンポーネントパス形式で説明されているとおりです

プラグインが commands/ などのデフォルトフォルダを持ち、それを置き換えるマニフェストキーも設定している場合、Claude Code はマニフェストパスを読み込み、フォルダは読み込みません。claude plugin list と /plugin インターフェイスは警告 Default <folder>/ folder is ignored because the manifest sets "<key>" を表示します。

警告を避けるには、キーをそのフォルダ内のパスに設定してください："commands": ["./commands/deploy.md"] はデフォルトフォルダ内のファイルを指定し、警告は生成されません。

ユーザー設定

userConfig は、プラグインが有効な場合に Claude Code がユーザーに入力を促す値を宣言するため、ユーザーは settings.json を自分で編集する必要がありません。

キーは文字、数字、アンダースコアで構成される識別子であり、数字で始まることはできません。

各値は、これらのフィールドを持つ厳密なオブジェクトです。未知のキーは検証に失敗します。

各有効なプラグインの各オプションは /config パネルの行としても表示されます。ただし、sensitive オプションと multiple リストは除きます。/config 行には Claude Code v2.1.269 以降が必要です。

この userConfig はエンドポイントとマスクされたトークンを宣言します：

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

フィールドを固定オプションに制限する

userConfig フィールドに options を設定して、ユーザーが固定リストからその値を選択するようにします。

tone フィールドを 3 つのオプションに制限するには、options にリストし、default をそのいずれかに設定します：

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

任意のフィールドで options を宣言する場合、Claude Code v2.1.271 より前のバージョンのユーザーはプラグインを読み込むことができません。

options は multiple または sensitive でない string フィールドに適用されます。default をリストされた値の 1 つに設定するか、ユーザーが 1 つを選択する必要があるように required: true を設定してください。各オプションは 1 ～ 64 文字のプレーンラベルであり、シェルで実行する claude plugin validate は他に拒否するものを報告します。options がこれらのルールを破るプラグインは読み込みに失敗します。

値が保存される場所

機密でない値はユーザーの settings.json の pluginConfigs に保存されます。機密値はプラットフォームのセキュアな認証情報ストアに代わりに保存されます。設定ページは pluginConfigs が読み込まれる設定ファイルを一覧表示します。

保存された値を参照する

プラグインが必要とする場所で保存された値を参照します。次の 2 つの形式のいずれかで：

• ${user_config.KEY}：MCP サーバー設定、LSP サーバー設定、exec 形式フック args、スキルおよびエージェントコンテンツで置き換えられます。スキルおよびエージェントコンテンツでは、機密でない値のみが置き換えられ、機密値はプレースホルダーになります
• CLAUDE_PLUGIN_OPTION_<KEY>：すべてのオプションに対してフックプロセスにエクスポートされます。<KEY> は大文字です。シェル形式フックは api_token に対して $CLAUDE_PLUGIN_OPTION_API_TOKEN を読み込みます

シェルを通じて実行されるフィールド

シェル形式フックコマンド、モニターコマンド、MCP headersHelper は ${user_config.*} を拒否します。これらのフィールドの 1 つで参照するコンポーネントは、フィールドの値がシェルに渡され、置き換えられた値を再解析するため、実行する代わりにエラーで失敗します。

テーブルは、値がこれらの各フィールドに到達する方法を示します。

チャネル

channels はプラグインが提供するメッセージチャネル（チャットアプリへのブリッジなど）を宣言します。1 つを宣言すると、Claude Code はプラグインが有効な場合にチャネルの設定を入力するよう促すことができます。サーバーがメッセージを注入する方法については、チャネルリファレンスを参照してください。

各エントリは、プラグインの MCP サーバーの 1 つにバインドされた厳密なオブジェクトであり、これらのフィールドを持ちます：

このマニフェストはチャネルをプラグインの telegram MCP サーバーにバインドし、サーバーの env に置き換わるボットトークンを入力するよう促します：

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

環境変数

Claude Code は 3 つのパス変数をプラグインコンポーネントに提供します。各変数が解決される場所にリストされたフィールドで ${NAME} として参照し、それらを受け取るプロセスで環境変数として読み込みます。

${CLAUDE_PLUGIN_ROOT} はプラグインが更新されるときに変わるため、そこに状態を書き込まないでください。ルートが移動する場合と古いディレクトリがクリーンアップされる場合については、読み込みページを参照してください。

最後にインストールされた場所からプラグインをアンインストールすると、--keep-data を渡さない限り、${CLAUDE_PLUGIN_DATA} ディレクトリは削除されます。

各変数が解決される場所

各プラグインコンポーネントでは、${...} 参照は特定のフィールドでインラインで解決され、一部のコンポーネントはプロセス環境でも変数を受け取ります：

変数は、Bash ツールを通じて Claude が実行するコマンドの環境、メインセッション、またはサブエージェントに存在しません。スキル、コマンド、エージェントコンテンツでは、Markdown 本体に ${...} 参照を書き込み、Claude Code はコンテンツを読み込むときにパスをインラインで置き換えます。

クォートとパス区切り文字

置き換えられた各パスを 1 つの引数に保ちます：

• フックコマンド：exec 形式を args で使用して、各パスが 1 つの引数でクォートなしになるようにします
• シェル形式フックとモニターコマンド：変数をダブルクォートで囲んで、スペースを含むパスが 1 つの単語のままになるようにします

このシェル形式フックはプラグインにバンドルされたスクリプトを実行します：

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

Windows では、置き換えられたパスはフォワードスラッシュを使用するため、シェルはバックスラッシュをエスケープとして読み込みません。

標準レイアウト

各コンポーネントタイプには、マニフェストが別の場所を指さない場合に使用されるプラグインルート下のデフォルトの場所があります。

すべてのデフォルトの場所を使用し、フックが呼び出す scripts/ フォルダを持つプラグインは、次のようにレイアウトされます：

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

このレイアウトをクリックして、各ファイルが何をするかを読むには、プラグインエクスプローラーを開いてください。

プラグインルートの CLAUDE.md はコンテキストとして読み込まれず、claude plugin validate はそれを見つけると警告します。Claude のコンテキストに読み込まれる指示を含めるには、スキルに入れてください。

マーケットプレイスエントリとマニフェスト

マーケットプレイスエントリは、このページのすべてのフィールドを独自のフィールドと一緒に受け入れます。strict を含みます。

strict フィールドは、エントリが独自の plugin.json を持つプラグインにコンポーネントを追加できるかどうかを決定します。デフォルトは true です。

エントリフィールドが `plugin.json` とどのように組み合わされるか

エントリはマニフェストとして機能するか、コンポーネントを追加するか、またはそれと競合します：

• plugin.json なし：エントリはマニフェストです。strict に関係なく。エントリ hooks はインラインオブジェクト形式でのみ読み込まれます。ファイルパスまたは配列の場合、/plugin Errors タブに not yet supported in a marketplace entry エラーが表示されます
• plugin.json 存在、strict 未設定または true：Claude Code はマニフェストを読み込み、エントリの commands、agents、skills、outputStyles、themes をそれに追加します。hooks の場合、エントリのイベントのマッチャーはマニフェストの同じイベントのマッチャーを置き換え、マニフェストのみが宣言するイベントはそのマッチャーを保持します
• plugin.json 存在、strict: false：commands、agents、skills、hooks、outputStyles、themes のいずれかを宣言するエントリは競合であり、プラグインは Plugin <name> has conflicting manifests で読み込みに失敗します

ソースがマーケットプレイスルートであるマーケットプレイスエントリが特定の skills サブディレクトリをリストする場合、それらのサブディレクトリのみが読み込まれ、プラグインのデフォルト skills/ ディレクトリはスキャンされません。マニフェストの skills キーは代わりにデフォルトに追加されます。

メタデータの優先順位

一部のメタデータフィールドは strict に関係なく固定の優先順位を持ちます：

• defaultEnabled と表示フィールド：エントリの defaultEnabled とその表示フィールド（displayName など）はマニフェストのものをオーバーライドします
• version：マニフェストの version はエントリのものをオーバーライドします
• name：エントリがプラグインをマニフェストとは異なる name でリストする場合、enabledPlugins はエントリ名を使用し、コンポーネントはマニフェスト名の下に名前空間化されます

完全な優先順位テーブルについては、厳密モードを参照してください。

次のステップ

• プラグインにコンポーネントを追加する：各コンポーネントが実行時に何をするか。検証する例付き
• マーケットプレイスリファレンス：マーケットプレイスがプラグインに設定できるエントリフィールド
• プラグインコマンドリファレンス：claude plugin validate フラグと出力
• プラグインのトラブルシューティング：各検証メッセージとその修正