.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/ が含まれます。
次の例はフィールドテーブルのほとんどのキーを設定します。参照されるすべてのパスを含むプラグインディレクトリで検証に合格します。
認識されないフィールド
認識されないトップレベルキーは削除され、userConfig オプション、channels エントリ、lspServers 設定、または monitors エントリ内の認識されないキーは拒否されます:
- トップレベルフィールド:フィールドは削除され、プラグインは読み込まれます。
claude plugin validateは認識されないトップレベルフィールドを警告として報告します - 厳密なオブジェクト:
userConfigオプション、channelsエントリ、lspServers設定、monitorsエントリは厳密です。その中の未知のキーはエラーであり、プラグインは読み込まれません
マニフェストを検証する
claude plugin validate はマニフェストの権威的なチェックです。シェルからプラグインディレクトリに対して実行してください:
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 つはディレクトリまたはファイルを受け入れます。
commands
commands はパス、パスの配列、またはオブジェクトマップを受け入れます。パスはフラットな .md コマンドファイルまたはディレクトリを指定します。オブジェクトマップでは、各キーはプラグインプレフィックスの後のコマンド名になります。例えば、プラグイン deploy-tools の "about" は /deploy-tools:about として実行されます。
各値は source または content のいずれか 1 つを設定し、両方を設定するか、どちらも設定しないエントリは検証に失敗します。このテーブルの他のフィールドはオプションです:
このマップはファイルからの 1 つのコマンドとインラインコンテンツからの 1 つを宣言します:
hooks
hooks は .json ファイルパス、settings.json の hooksと同じ形状のインラインフックオブジェクト、またはその両方を混ぜた配列を受け入れます。フックイベントとハンドラーフィールドについては、フックリファレンスを参照してください。
Claude Code は、そのファイルが存在する場合、hooks/hooks.json で宣言したものをマージします。
mcpServers
mcpServers は .json ファイルパス、MCP バンドルパスまたは URL、インラインマップ、またはそれらを混ぜた配列を受け入れます。サーバー設定フィールドについては、プラグイン提供の MCP サーバーを参照してください。
Claude Code はプラグインルートの .mcp.json を最初に読み込み、次に宣言された各形状を順に読み込みます。後で宣言されたサーバー名は前のものを置き換えます。
mcpServers 値は次のいずれかの形状を取ります:
バンドルパスまたは URL は
.mcpb または .dxt で終わる必要があります。他の拡張子は検証に失敗します。
lspServers
lspServers は .json ファイルパス、サーバー名から設定へのインラインマップ、またはその両方の配列を受け入れます。
Claude Code はプラグインルートの .lsp.json を最初に読み込み、次に宣言された各設定を順に読み込みます。後で宣言されたサーバー名は前のものを置き換えます。
各サーバー設定は、これらのフィールドを持つ厳密なオブジェクトです。未知のキーは検証に失敗します。
このインライン設定は
.go ファイルに対して gopls を実行します:
monitors
experimental.monitors は .json ファイルパスまたはインライン配列を受け入れます。キーを省略すると、Claude Code は存在する場合 monitors/monitors.json を読み込みます。
各エントリは、これらのフィールドを持つ厳密なオブジェクトです。
このインライン配列は、
deploy スキルが初めて実行されるときに開始される 1 つのモニターを宣言します:
command は ${user_config.*} を参照できません。シェルを通じて実行されるフィールドを参照してください。
パスルール
マニフェスト内のすべてのコンポーネントパスはプラグインルートに相対し、./ で始まる必要があります。commands/foo.md などのパスは検証に失敗します。skills と mcpServers は各々、そのルール外の 1 つの形式を受け入れます:
skills:"."も受け入れます。"."と"./"の両方がプラグインルートを示します。v2.1.221 より前では、"."はマニフェスト検証に失敗したため、プラグインが以前のバージョンで読み込まれる必要がある場合は"./"を使用してくださいmcpServers:https://バンドル URL も受け入れます
包含と存在
すべてのコンポーネントパスはプラグインルート内で解決され、存在する必要があります。claude plugin validate は outputStyles、lspServers、monitors、themes パスをチェックしないため、これらのフィールドの不正なパスはプラグインが読み込まれるときにのみ失敗します:
- 包含:プラグインルート外で解決されるパスは読み込まれず、
/pluginErrors タブに<component> path escapes plugin directory: <path>が表示されます。..を含むパスが一般的なケースであり、claude plugin validateはPath contains ".." which could be a path traversal attemptとして報告します - 存在:存在しないパスは読み込まれず、
/pluginErrors タブに<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 フィールドに options を設定して、ユーザーが固定リストからその値を選択するようにします。
tone フィールドを 3 つのオプションに制限するには、options にリストし、default をそのいずれかに設定します:
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を読み込みます
シェルを通じて実行されるフィールド
シェル形式フックコマンド、モニターコマンド、MCPheadersHelper は ${user_config.*} を拒否します。これらのフィールドの 1 つで参照するコンポーネントは、フィールドの値がシェルに渡され、置き換えられた値を再解析するため、実行する代わりにエラーで失敗します。
テーブルは、値がこれらの各フィールドに到達する方法を示します。
チャネル
channels はプラグインが提供するメッセージチャネル(チャットアプリへのブリッジなど)を宣言します。1 つを宣言すると、Claude Code はプラグインが有効な場合にチャネルの設定を入力するよう促すことができます。サーバーがメッセージを注入する方法については、チャネルリファレンスを参照してください。
各エントリは、プラグインの MCP サーバーの 1 つにバインドされた厳密なオブジェクトであり、これらのフィールドを持ちます:
このマニフェストはチャネルをプラグインの
telegram MCP サーバーにバインドし、サーバーの env に置き換わるボットトークンを入力するよう促します:
環境変数
Claude Code は 3 つのパス変数をプラグインコンポーネントに提供します。各変数が解決される場所にリストされたフィールドで${NAME} として参照し、それらを受け取るプロセスで環境変数として読み込みます。
${CLAUDE_PLUGIN_ROOT} はプラグインが更新されるときに変わるため、そこに状態を書き込まないでください。ルートが移動する場合と古いディレクトリがクリーンアップされる場合については、読み込みページを参照してください。
最後にインストールされた場所からプラグインをアンインストールすると、--keep-data を渡さない限り、${CLAUDE_PLUGIN_DATA} ディレクトリは削除されます。
各変数が解決される場所
各プラグインコンポーネントでは、${...} 参照は特定のフィールドでインラインで解決され、一部のコンポーネントはプロセス環境でも変数を受け取ります:
変数は、Bash ツールを通じて Claude が実行するコマンドの環境、メインセッション、またはサブエージェントに存在しません。スキル、コマンド、エージェントコンテンツでは、Markdown 本体に
${...} 参照を書き込み、Claude Code はコンテンツを読み込むときにパスをインラインで置き換えます。
クォートとパス区切り文字
置き換えられた各パスを 1 つの引数に保ちます:- フックコマンド:exec 形式を
argsで使用して、各パスが 1 つの引数でクォートなしになるようにします - シェル形式フックとモニターコマンド:変数をダブルクォートで囲んで、スペースを含むパスが 1 つの単語のままになるようにします
標準レイアウト
各コンポーネントタイプには、マニフェストが別の場所を指さない場合に使用されるプラグインルート下のデフォルトの場所があります。
すべてのデフォルトの場所を使用し、フックが呼び出す
scripts/ フォルダを持つプラグインは、次のようにレイアウトされます:
CLAUDE.md はコンテキストとして読み込まれず、claude plugin validate はそれを見つけると警告します。Claude のコンテキストに読み込まれる指示を含めるには、スキルに入れてください。
マーケットプレイスエントリとマニフェスト
マーケットプレイスエントリは、このページのすべてのフィールドを独自のフィールドと一緒に受け入れます。strict を含みます。
strict フィールドは、エントリが独自の plugin.json を持つプラグインにコンポーネントを追加できるかどうかを決定します。デフォルトは true です。
エントリフィールドが plugin.json とどのように組み合わされるか
エントリはマニフェストとして機能するか、コンポーネントを追加するか、またはそれと競合します:
plugin.jsonなし:エントリはマニフェストです。strictに関係なく。エントリhooksはインラインオブジェクト形式でのみ読み込まれます。ファイルパスまたは配列の場合、/pluginErrors タブに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フラグと出力 - プラグインのトラブルシューティング:各検証メッセージとその修正