プラグインにコンポーネントを追加する

スキル、フック、MCP サーバー、その他すべてのコンポーネントタイプを Claude Code プラグインに追加し、各コンポーネントの検証例を含めます。

Claude Code プラグインはスキル、エージェント、フック、MCP サーバーなどのコンポーネントから構築されます。各コンポーネントはプラグイン内にデフォルトフォルダを持ち、.claude-plugin/plugin.json 内のオプションのマニフェストキーがそのフォルダを置き換えるか追加し、ユーザーが見る名前があります。各キーの完全なフィールドテーブルについては、マニフェストリファレンスを参照してください。

このページを使用して、既に読み込まれているプラグインにコンポーネントを追加します。

コンポーネントを追加した後、実行中のセッションで /reload-plugins を実行するか、新しいセッションを開始して Claude Code がそれを読み込むようにします。コンポーネントのファイルを読み込む前に確認するには、プラグインディレクトリからシェルで claude plugin validate . を実行します。

[!NOTE]

これらのケースは他のページで説明されています：

最初のプラグインを構築する：プラグインを作成するから始めます

他のユーザーのプラグインをインストールする：プラグインをインストールするを参照してください

プラグインのユーザーが claude.ai または Cowork にいる：異なるセットのコンポーネントがそこに読み込まれます。プラグイン構造とテストとコンポーネントサポートテーブルを参照してください

プラグインディレクトリを探索する

エクスプローラーは、デフォルトの場所にあらゆる種類のコンポーネントを 1 つずつ持つ例のプラグイン my-plugin を示しています：

レビュースキルと about コマンド
セキュリティレビューサブエージェント
Claude がファイルを編集した後にファイルをフォーマットするフック、およびそれが呼び出す scripts/ フォルダ
ログモニター
出力スタイルとカラーテーマ
ルート監査ワークフロー
hello-plugin 実行可能ファイル
デフォルト設定
ローカル MCP サーバーと Go 言語サーバー

各ファイルはその形式の最小限の有効な例であり、有用であるためではなく形状を示すためにあります：実際のスキルまたはエージェントは完全な指示を持ち、多くの場合サポートファイルを含み、実際のフックまたはモニターは実際の作業を行います。エクスプローラーの後のセクションはエクスプローラーと同じファイルを例として使用し、より完全なものへのリンクを提供します。ファイルまたはフォルダを選択して、それが何のためにあるのか、何が含まれるのか、それをカバーするセクションを見つけます。

What goes in a plugin

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.

Plugin directory

my-plugin/

Selected piece

マニフェストはプラグインの .claude-plugin/ ディレクトリ内の plugin.json ファイルです。プラグインのメタデータと、Claude Code がユーザーに求める userConfig 値が含まれます。Claude Code はマニフェストがなくてもプラグインを読み込みます。ファイル内では、name のみが必須です。このマニフェストでは、description はユーザーが /plugin でプラグインに対して見るテキストであり、version はユーザーをそのバージョンに保ちます。変更するまで：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}

スキルは SKILL.md ファイルです。各スキルを skills/ の下の独自のディレクトリに保存します。Claude はすべてのスキルの description を読み、ユーザーが求めるものがそれと一致する場合（ここでプルリクエストをレビューするよう Claude に求めるなど）、Claude はスキルの指示を読み込んでそれに従います。ユーザーは /my-plugin:review として直接実行することもできます：

---
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.

コマンドは、ユーザーが名前で実行する単一の Markdown ファイルです。コマンドは古い形式です：スキルは同じ方法で名前で実行でき、独自のディレクトリにサポートファイルを含めることもできるため、新しいものはスキルとして記述し、既に持っているファイルについては commands/ を保持します。このファイルは /my-plugin:about になり、スキルと同じフロントマターを取ります：

---
description: Summarize the repository
---

Summarize what this repository does in three sentences.

サブエージェントは、独自の指示と独自のコンテキストウィンドウを持つ別のアシスタントであり、Claude がタスクを委譲して結果を取得できます。agents/ の下の各 Markdown ファイルは 1 つを定義します：フロントマターはそれに名前を付け、いつ使用するかを言い、本文はそのシステムプロンプトです。このファイルは my-plugin:security-reviewer という名前で、ユーザーは @agent-my-plugin:security-reviewer で呼び出すことができます：

---
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.

フックは Claude Code のライフサイクルの特定の時点（すべてのファイル編集後など）で自動的に何かを実行します：シェルコマンド、HTTP リクエスト、MCP ツール呼び出し、モデルへのプロンプト、またはサブエージェント。プラグインのフックをプラグインルートの hooks/hooks.json に保存します。このフックは Claude がファイルを書き込むか編集した後、プラグインの scripts/format.sh を実行します：

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

モニターは、Claude Code がセッションの開始時にバックグラウンドで開始し、セッションが終了するまで実行し続けるシェルコマンドです。それが出力するものは Claude に通知として到達します。when フィールドは、代わりに名前付きスキルが初めて実行されるときに開始できます。このモニターはエラーログをテールします：

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

プラグインは出力スタイルを含めることができます。これは Claude が返信をフォーマットおよび表現する方法を変更します。各出力スタイルを output-styles/<name>.md として保存します。このスタイルは /output-style に my-plugin:terse として表示されます：

---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---

Keep every reply short. Skip preambles and summaries.

プラグインは Claude Code インターフェースのカラーテーマを含めることができます。各テーマを themes/<slug>.json として保存します。このテーマは /theme に Dracula として表示され、my-plugin からのものとしてマークされます：

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

workflows/ フォルダはワークフロー .js ファイルを保持します：meta ブロック、その後、複数のサブエージェントを調整するスクリプト本文。このファイルは /my-plugin:audit-routes として実行されます：

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/ はプラグインがコマンドラインツールを配布する方法です。プラグインが有効な間、Claude Code はこのフォルダをシェルの PATH に配置するため、Claude またはスキルの指示は、ユーザーが何もインストールすることなく、ツールを名前で実行できます。この実行可能ファイルが配置されている場合、hello-plugin は Claude が実行できるコマンドです：

#!/bin/bash
echo "hello from my-plugin"

hooks/hooks.json のフックはスクリプトを実行し、このフォルダは例がそれを保持する場所です。scripts/ という名前は慣例であり、Claude Code が探すものではありません：フックはファイルをそのパス ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh で指します。フォーマッタスクリプトは次のようになります：

#!/bin/bash
npx prettier --write .

プラグインルートの settings.json は、プラグインが有効な間に適用される設定を保持するため、プラグインはセッションの動作を変更でき、コンポーネントを追加するだけではありません。プラグインから効果を発揮するのは 2 つのキーのみです。agent と subagentStatusLine；他のすべてのキーは削除されます。デフォルト設定を参照してください。

このファイルは agent を設定し、セッションのメインスレッドをプラグイン独自の security-reviewer エージェントとして実行するため、そのエージェントのシステムプロンプト、ツール制限、およびモデルがセッション全体に適用されます：

{
  "agent": "security-reviewer"
}

MCP サーバーは Claude に外部システムからのツールを提供します。プラグインルートの .mcp.json で宣言します。このサーバーはプラグイン内のスクリプトからローカルサーバーを開始し、/mcp に plugin:my-plugin:db として表示されます：

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

LSP サーバーは Claude に言語の診断とコードナビゲーションを提供します。プラグインルートの .lsp.json でサーバーを宣言します。このサーバーは .go ファイルの Go 言語サーバーを接続します：

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

各種類のコンポーネントを追加する

以下の各セクションでは、コンポーネントの種類ごとに、プラグイン内でのファイルの配置場所、検証に通る例、プラグインの読み込み後にユーザーに表示される内容、およびデフォルトの場所を変更するマニフェストキーを説明します。プラグインに必要なものを追加してください。必須のものはありません。

スキル

スキルは、説明がタスクに一致したときに Claude が読み込める SKILL.md ファイルです。ユーザーはコマンドとして実行することもできます。各スキルは skills/ 配下の個別のディレクトリに保存します。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

Claude がいつ使用すべきかを判断できるよう、SKILL.md に description を指定します。

---
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.

プラグインを読み込むと、/my-plugin:review でスキルが実行されます。コマンド名と呼び出せる主体は次のルールに従います。

コマンド名: /<plugin>:<directory> となるため、my-plugin 内の skills/review/SKILL.md は /my-plugin:review になります。フロントマターで name を設定すると、最後のセグメントが置き換えられ、プラグインのプレフィックスはそのまま残ります。スキルのコマンド名の決まり方を参照してください
呼び出せる主体: Claude、ユーザー、またはその両方で、フロントマターで制御します。スキルを呼び出せる主体を制御するを参照してください

スキルはデフォルトの skills/ ディレクトリ以外に配置することもできます。

追加のディレクトリ: skills マニフェストキーに列挙します。commands や agents とは異なり、デフォルトの skills/ のスキャンを置き換えるのではなく、それに追加されます
プラグインルートの単一スキル: skills/ ディレクトリも skills マニフェストキーもない場合、プラグインルートの SKILL.md が 1 つのスキルとして読み込まれます。フロントマターで name を設定してください。設定しないと、マーケットプレイスからのインストール時に、スキル名がプラグイン名ではなくキャッシュディレクトリの名前になります

プラグインに指示を含めるには、スキルとして記述します。Claude Code はプラグインルートの CLAUDE.md を読み込まず、claude plugin validate は CLAUDE.md at the plugin root is not loaded as project context という警告を出します。

保護されたファイルへの編集のブロックのように、常に守られる必要があるルールは、スキルではなくフックとしてプラグインに追加してください。どちらを選ぶべきかについては、類似機能の比較の「Hook vs Skill」タブを参照してください。

フロントマターのフィールドとサポートファイルについては、スキルを参照してください。

コマンド

コマンドは、/my-plugin:about のように、ユーザーが名前で実行する単一の Markdown ファイルです。

[!NOTE]

コマンドは古い形式であり、新規の作業ではスキルがこれに代わります。スキルも同じように名前で実行でき、さらにディレクトリ内にサポートファイルを含めることもできます。commands/ は .claude/commands/ から移行するファイルのために残しておいてください。

コマンドを commands/<file>.md に保存すると、/<plugin>:<file> になります。サブディレクトリはセグメントを追加するため、commands/db/migrate.md は /my-plugin:db:migrate になります。

コマンドファイルはスキルと同じフロントマターを受け付けます。

マニフェストでコマンドを定義する

これが必要なのは、コマンドファイルを commands/ 以外の場所に置きたい場合か、別の Markdown ファイルを用意せずに plugin.json 内で短いコマンドを定義したい場合だけです。commands マニフェストキーを設定すると、Claude Code は commands/ をスキャンする代わりにそれを読み取ります。このキーには、パス、パスの配列、または各コマンド名を source ファイルかインラインの content にマッピングするオブジェクトを指定できます。

このマニフェストは、Markdown ファイルなしで /my-plugin:about をインラインで定義します。

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

プラグインを読み込み、セッションで /my-plugin:about を実行して、読み込まれたことを確認してください。

キーの完全な構文については、commands を参照してください。

エージェント

サブエージェントは、独自の指示とコンテキストウィンドウを持つ別のアシスタントで、Claude はタスクを委任できます。agents/ 配下の各 Markdown ファイルが 1 つのサブエージェントを定義します。

---
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.

このエージェントの名前は my-plugin:security-reviewer で、ユーザーは @agent-my-plugin:security-reviewer で明示的に呼び出すことができます。名前の形式は <plugin>:<name> で、<name> はフロントマターの name フィールドから取られ、このフィールドがない場合はファイル名から取られます。

agents マニフェストキーは agents/ のスキャンを置き換えます。

エージェントをサブフォルダーで整理する

プラグインのエージェントファイルは agents/ のサブフォルダーに置くことができます。Claude Code はそれらを再帰的に読み込み、プラグイン名、各サブフォルダー名、ファイル名をコロンで連結して、エージェントのスコープ付きの名前を作ります。たとえば、my-plugin という名前のプラグイン内の agents/review/security.md は my-plugin:review:security として読み込まれます。この名前を変更する設定が 2 つあります。

フロントマターの name: ファイル名の部分だけを置き換えるため、agents/review/security.md 内の name: audit は my-plugin:review:audit として読み込まれます
マニフェストの agents フィールド: ここに列挙したファイルはサブフォルダー名なしで読み込まれるため、"agents": "./custom/review/security.md" は my-plugin:security として読み込まれます

プラグインエージェントのフロントマターフィールド

プラグインエージェントのフロントマターは次のルールに従います。

サポートされるフィールド: name、description、model、effort、maxTurns、autoCompactWindow、tools、disallowedTools、skills、memory、background、omitClaudeMd、isolation、color、および experimental の cacheTtl キーです。isolation の有効な値は "worktree" のみです。各フィールドの役割については、サポートされるフロントマターフィールドを参照してください
無視されるフィールド: permissionMode、hooks、mcpServers、initialPrompt です。エージェントファイル単独ではフックや MCP サーバーを追加できないため、代わりにプラグインのフックと MCP サーバーとして追加してください
256 文字を超える name: Claude Code はこれを無視し、このフィールドがない場合と同様に、エージェントの名前をファイル名にします
解析できないフロントマター: エージェントはすべてのフィールドが無視された状態で読み込まれます。名前はファイル名になり、説明は Agent from my-plugin plugin になります。このようなファイルを見つけるには、シェルで claude plugin validate を実行してください

各フィールドの役割と優先順位のルールについては、サブエージェントを参照してください。

フック

フックは、ファイル編集のたびなど、Claude Code のライフサイクルの特定の時点で何かを自動的に実行します。実行できるのは、シェルコマンド、HTTP リクエスト、MCP ツール呼び出し、モデルへのプロンプト、またはサブエージェントです。プラグインのフックは、プラグインルートの hooks/hooks.json に、トップレベルの "hooks" キーの下に、settings.json 内の hooks オブジェクトと同じ形式で保存します。これにより、既存の設定フックをそのままコピーできます。

このフックは、Write または Edit のたびに同梱のスクリプトを実行します。

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

スクリプトを scripts/format.sh に保存し、実行可能にしてください。

プラグインを読み込み、Claude にファイルの編集を依頼します。終了コード 0 で終了した PostToolUse フックはトランスクリプトに何も表示しないため、実行されたことはデバッグログか、スクリプト自体による変更内容で確認してください。

hooks/hooks.json 内のフックと hooks マニフェストキー内のフックは、どちらも読み込まれます。すべてのイベントとそのペイロードについては、フックイベントを参照してください。

有効な別のプラグインが同じ名前を持つ場合、2 つのうち一方の hooks/hooks.json のフックが登録され、もう一方のフックは除外されます。どちらが登録されるか、およびそれを知らせる /plugin 内の通知については、有効な 2 つのプラグインが同じ名前を持つ場合のフックを参照してください。

Claude Code 内で実行され、そのインターフェースに描画できる JavaScript 関数としてフックを記述するには、同じ hooks/hooks.json の modules キーの下にモジュールファイルを列挙します。これを含むプラグインは mod です。mod を作成するを参照してください。

プラグインのフックが発火するタイミング

プラグインのフックは、そのプラグインのスキルやコマンドが使用されるのを待ちません。Claude Code はセッションがプラグインを読み込んだ時点でフックを登録し、それ以降、フックはそれぞれのイベントで発火します。フックが実行されるタイミングを限定するには、その matcher を絞り込んでください。

フックがまったく発火しない場合は、発火しないフックを参照してください。

環境、クォート、MCP ツールのマッチング

フックの環境、${CLAUDE_PLUGIN_ROOT} のクォート、プラグイン自身の MCP ツールに対する matcher は、次のように動作します。

環境: すべてのフックプロセスは、環境変数として CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA、さらに各ユーザー設定値に対応する CLAUDE_PLUGIN_OPTION_<KEY> を受け取るため、スクリプトはそこからこれらを読み取れます
クォート: command に args がない場合はシェルを介して実行されるため、フックの hooks/hooks.json の例のように ${CLAUDE_PLUGIN_ROOT} のパスを二重引用符で囲み、展開後のパスが 1 つのシェルワードになるようにしてください。代わりに args を渡す場合、各要素はシェルを介さずに 1 つの引数として渡されるため、クォートは不要です。exec 形式と shell 形式を参照してください
プラグイン自身の MCP ツールのマッチング: このプラグインが宣言する MCP サーバーのツールは mcp__plugin_<plugin>_<server>__<tool> という名前になるため、matcher にはこの完全な名前を記述してください。サーバー名だけの matcher は決して発火しません。MCP ツールのマッチングを参照してください

MCP サーバー

MCP サーバーは、外部システムのツールを Claude に提供します。プラグインルートの .mcp.json に、プロジェクトの .mcp.json と同じ形式で宣言します。この .mcp.json は db という名前のサーバーを 1 つ宣言します。

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

mcpServers のラッパーを省略し、db をファイルのトップレベルに置くこともできます。

プラグインを読み込み、/mcp を実行して、サーバーが plugin:my-plugin:db として表示されることを確認してください。

claude plugin validate は .mcp.json をチェックし、Claude Code が読み込み時に破棄するサーバーエントリをエラーとして報告します。Claude Code v2.1.281 以降が必要です。

不正なエントリが読み込み時にどこに表示されるかについては、起動しない MCP サーバーを参照してください。

mcpServers マニフェストキーには、インラインのサーバーマップ、JSON ファイルへのパス、またはそれらの配列を指定できます。マニフェストのサーバーが .mcp.json 内のサーバーと同じ名前を持つ場合、マニフェストのサーバーがそれを置き換えます。

claude.ai と Cowork のユーザーに届ける

MCP サーバーの db サーバーのようなローカルの stdio サーバーは、Claude Code と、Claude Desktop アプリでユーザーのマシン上で実行される Cowork セッションでは動作しますが、claude.ai では動作しません。claude.ai のユーザーにも届けるには、MCP コネクタをスキルと一緒にバンドルするで示されているように、リモートサーバーを https:// URL で参照してください。claude.ai と Cowork は、これをコネクタとしてユーザーに提供します。

サーバー名、ツール名、再読み込み

サーバーの名前、変数の置換、再読み込みの動作は次のルールに従います。

サーバー名: plugin:<plugin>:<server> となるため、my-plugin 内の db サーバーは /mcp で plugin:my-plugin:db になります。mcp_tool フックでサーバーを指定する場合も同じ形式を使用してください
ツール名: mcp__plugin_<plugin>_<server>__<tool> となるため、その db サーバー上の query ツールは mcp__plugin_my-plugin_db__query になります。これが権限ルールとフックの matcher で使用する名前です
置換: ${CLAUDE_PLUGIN_ROOT} とその他のパス変数は、command、args、env 内で置換されます。args では各要素が 1 つの引数として渡されるため、クォートは不要です
再読み込み: ユーザーが /reload-plugins を実行し、再読み込みが適用されると、設定が変更されていないサーバーは接続を維持します。設定が変更されたサーバーは再接続し、削除したサーバーは切断されます

パッケージ化された MCPB サーバーを含める

mcpServers キーには、パッケージ化されたサーバーを MCPB ファイルとして指定することもできます。拡張子は .mcpb または旧形式の .dxt です。キーには、プラグイン内のパスまたは https:// URL としてファイルを指定します。

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

サーバーの名前は、バンドルのマニフェスト内の name から取られます。

バンドル自体のマニフェストでは、サーバーがユーザーから必要とする設定を user_config ブロックで宣言できます。必須の設定に保存済みの値がないバンドルサーバーは起動しません。/plugin の Errors タブには Bundled MCP server "<name>" was not started: it needs configuration と表示されます。

ユーザーは次の 2 つのいずれかの方法で値を指定します。

/plugin で指定する: Installed タブでプラグインを選択し、Configure を選びます
インストール時にシェルから指定する: claude plugin install に --config <server>.<key>=<value> を渡します。Claude Code v2.1.285 以降が必要で、プラグイン内にパッケージ化されたバンドルに対してのみ機能します。

トランスポートと認証については、MCP を参照してください。

LSP サーバー

LSP サーバーは、言語の診断とコードナビゲーションを Claude に提供します。使用する言語を公式のコードインテリジェンスプラグインがすでにカバーしている場合は、自分で作成する代わりにそれをインストールしてください。そうでない場合は、プラグインルートの .lsp.json でサーバーを宣言します。

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

このファイルは各サーバー名をその設定に直接マッピングし、マップを囲むラッパーオブジェクトはありません。command はバイナリの名前で、その引数は args に指定します。extensionToLanguage には少なくとも 1 つの拡張子が必要で、それぞれ . で始まる必要があります。

claude plugin validate はこのファイルを読み取りません。いずれかのエントリが無効な場合、読み込み時にファイル全体がスキップされ、/plugin の Errors タブに Invalid LSP server config for ".lsp.json" と表示されます。

プラグインは接続を設定しますが、サーバーのバイナリはインストールしません。また、各ファイル拡張子に割り当てられるサーバーは 1 つです。

バイナリがない場合: Claude Code はユーザーの PATH から名前で command を起動します。バイナリがそこにない場合、サーバーは起動に失敗し、claude --debug は LSP server <name> failed to start をログに記録します
拡張子の競合: 有効な 2 つのサーバーが同じ拡張子を要求する場合、サーバーが 1 つのプラグインからのものか 2 つのプラグインからのものかにかかわらず、最初に登録されたサーバーがそれらのファイルを処理し、もう一方はそれらのファイルには使用されません。/plugin の Errors タブには LSP server "<name>" is not used for <ext> files という警告が表示されます

lspServers マニフェストキーには、同じマップをインラインで、JSON ファイルへのパス、またはそれらの配列を指定でき、そのサーバーは .lsp.json 内のサーバーに追加されます。マニフェストのサーバーが .lsp.json 内のサーバーと同じ名前を持つ場合、マニフェストのサーバーがそれを置き換えます。

transport、タイムアウト、再起動、その他のフィールドについては、lspServers を参照してください。

ログ出力は stdout ではなく stderr に送ってください。Claude Code はサーバーの stdout をプロトコルメッセージとしてのみ読み取り、最大 64 KiB のメッセージヘッダーと最大 32 MiB のメッセージ本文を受け付けます。

いずれかの上限を超えたサーバー、または stdout にプロトコル以外の出力を書き込んだサーバーを、Claude Code は切断し、その切断を restartOnCrash と maxRestarts におけるクラッシュとして数えます。--debug を付けて実行すると、Claude Code は原因を示すエラーをデバッグログに書き込みます。

実行可能ファイル

プラグインルートの bin/ 内のファイルは、プラグインが有効な間、Bash ツールのシェルの PATH に含まれるため、Claude はそれらをコマンド名だけで実行できます。Claude がサンドボックスの外で PowerShell ツールを使って実行するコマンドも、PATH 上でそれらを見つけられますが、サンドボックス化された PowerShell コマンドでは見つけられません。実行可能なスクリプトを追加します。

#!/bin/bash
echo "hello from my-plugin"

chmod +x bin/hello-plugin で実行可能にし、プラグインを読み込みます。Claude に hello-plugin の実行を依頼すると、Bash ツールの結果にスクリプトの出力が表示されます。

プラグインの bin/ ディレクトリはユーザー自身の PATH エントリの後に置かれるため、プラグインが git、ls、その他のシステムコマンドを隠すことはできません。

claude.ai と Cowork は、トップレベルに bin/ ディレクトリを持つプラグインをインストールしません。これには、claude.ai の組織設定を通じて配布するプラグインも含まれます。

デフォルト設定

プラグインが有効な間に適用されるデフォルトを設定するには、プラグインルートに settings.json を追加するか、同じオブジェクトを settings マニフェストキーにインラインで記述します。有効になるキーは agent と subagentStatusLine の 2 つで、それ以外のキーはすべて破棄されます。

プラグイン自身のエージェントの 1 つをメインスレッドとして実行するには、agent を設定します。

{
  "agent": "security-reviewer"
}

プラグインを読み込み、セッションを開始します。すると Claude は、メインの会話で security-reviewer エージェントのシステムプロンプトとモデルを使って応答します。

このキーが制御するすべての内容については、agent 設定を参照してください。

同じキーが複数の場所で設定されている場合、どの値が適用されるかは次のルールで決まります。

マニフェストよりファイルを優先: 両方が存在し、settings.json がサポートされるキーを少なくとも 1 つ設定している場合、settings.json が適用され、マニフェストの settings は無視されます
プラグインのデフォルトよりユーザー設定を優先: 設定ソースの中で、プラグインのデフォルトは最も低いレイヤーであるため、~/.claude/settings.json 内のユーザー自身の agent がプラグインの値を上書きします
2 つのプラグインが同じキーを設定する場合: 最後に読み込まれたプラグインの値が適用され、claude --debug は overrides setting をログに記録します

subagentStatusLine の形式については、サブエージェントのステータスラインを参照してください。

テーマと出力スタイル

プラグインにはカラーテーマと出力スタイルを含めることができます。どちらも、ユーザー自身のものと同じピッカーに表示されます。どちらの場合も、マニフェストキーを設定するとフォルダーのスキャンが置き換えられます。

コンポーネント	保存先	形式	表示場所	マニフェストキー
テーマ	`themes/<slug>.json`	ユーザーが `~/.claude/themes/` に記述するカスタムテーマファイルの形式	`/theme`、ファイルの `name` で表示	`experimental.themes`
出力スタイル	`output-styles/<name>.md`	`name` と `description` のフロントマターを持つカスタム出力スタイルの形式	`/output-style`、`<plugin>:<name>` として表示	`outputStyles`

プラグインのテーマは読み取り専用であるため、ユーザーが /theme でテーマを編集すると、その編集はユーザー自身のテーマディレクトリにコピーとして保存されます。

このテーマは、dark プリセット上でプロンプトのアクセントカラーとエラーテキストの色を変更します。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

チャネル

チャネルを使うと、チャットアプリなどの外部システムがセッションにメッセージを送信できます。プラグインにおけるチャネルは、MCP サーバーの 1 つと、それにバインドし独自の設定をユーザーに求めることができる channels エントリで構成されます。このマニフェストは、チャネルを telegram サーバーにバインドし、ボットトークンを求めます。

{
  "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 は mcpServers 内のキーと一致する必要があります。チャネルごとの userConfig は、トップレベルの userConfig キーと同じ形式です。

サーバーが実装する必要がある内容と、ユーザーがチャネルプラグインを有効にする方法については、チャネルリファレンスのプラグインとしてパッケージ化するを参照してください。フィールドの表については、channels を参照してください。

モニター

モニターは、セッション全体を通じてバックグラウンドで実行されるシェルコマンドです。出力した内容は通知として Claude に届くため、Claude は監視を依頼されなくても、ログやステータスの変化に反応できます。エントリは monitors/monitors.json に保存します。

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

コマンドは、セッションの現在の作業ディレクトリでシェル内で実行されます。ユーザーの完全な権限で、サンドボックスの外で実行されます。

モニターのコマンドには、起動する場所と参照できる内容に制限があります。

対話セッションのみ: プラグインのモニターは、-p フラグを使用した非対話モードでは起動しません
最小バージョン: Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry のいずれかを使用している場合、または DISABLE_TELEMETRY か CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC が設定されている場合、モニターには Claude Code v2.1.310 以降が必要です。この要件は機能フラグの取得がオフの場合に適用されます
ユーザー設定は使用不可: command はパス変数と環境からの ${ENV_VAR} を取得しますが、${user_config.*} は決して取得しません。これを参照するモニターは起動せず、モニタープロセスは CLAUDE_PLUGIN_OPTION_<KEY> も受け取りません
セッション途中での無効化: セッションの途中でプラグインを無効にしても、Claude Code はすでに実行中のモニターを停止しません。モニターはセッションの終了時に停止します

experimental.monitors マニフェストキーには、同じ配列をインラインで、または JSON ファイルへのパスを指定でき、monitors/monitors.json の代わりに読み取られます。

when トリガーとその他のフィールドについては、monitors を参照してください。

ユーザーに設定値を求める

プラグインが必要とする値を userConfig マニフェストキーで宣言すると、ユーザーが settings.json を自分で編集する必要がなくなります。各オプションはダイアログに表示され、その title がラベルとして、その description がその下に表示されます。

トークンまたはパスワードの場合は "sensitive": true を設定してください。ダイアログは入力をマスクし、値は settings.json ではなくセキュアストレージに保存されます。

このマニフェストはエンドポイントとトークンを求めます。

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

設定ダイアログが表示されるとき

ダイアログは対話型の /plugin インターフェースの一部です。ユーザーが以下のいずれかを実行したときに、まだ設定されていないオプションに対して開きます。

/plugin でプラグインをインストールする
セッション内で /plugin install <plugin>@<marketplace> を実行する
/plugin の Installed タブからプラグインを有効にする

ユーザーがいつでも同じダイアログを開くには、/plugin configure <plugin>@<marketplace> を実行します。

VS Code 拡張機能のプラグイン管理ダイアログは、インストール後にフォームとして未設定のオプションを求め、プラグインの行のギアアイコンはすべてのオプションを含むフォームを再度開きます。

claude plugin install シェルコマンドは userConfig 値のプロンプトを表示しません。シェルから値を設定するには、インストール時に各値を --config KEY=VALUE として渡すか、その後 claude plugin configure --values-stdin にJSON オブジェクトをパイプします。

オプションが設定されていない場合、claude plugin install は userConfig options not yet set という行を出力します。その行の正確なテキストについては、userConfig ダイアログが表示されないを参照してください。

オプションフィールド、各値が保存される場所、コンポーネントが保存された値を参照する方法、および ${user_config.*} を拒否するフィールドについては、ユーザー設定を参照してください。

プラグインパスを参照し、データを保存する

プラグインがどこにインストールされるかわからないため、固定パスではなく、これらの変数を通じてそのファイルとデータを参照します。スキル、コマンド、エージェントコンテンツ、フックおよびモニターコマンド、MCP および LSP サーバー構成で置換されます。また、フック、MCP、および LSP プロセスにエクスポートされます：

${CLAUDE_PLUGIN_ROOT}：プラグインのインストールディレクトリ。各バージョンは独自のキャッシュディレクトリを持つため、プラグインが更新されるとパスが変更されます。そこに状態を書き込まないでください
${CLAUDE_PLUGIN_DATA}：更新を生き残るディレクトリ。node_modules、仮想環境、キャッシュ用。~/.claude/plugins/data/<id>/ に解決され、最初に参照されるときに作成されます
${CLAUDE_PROJECT_DIR}：プロジェクトルート。フックが受け取るのと同じ値

データディレクトリパスでは、<id> はプラグイン識別子で、文字、数字、_、- 以外のすべての文字が - に置き換わるため、my-plugin@my-marketplace は my-plugin-my-marketplace になります。

Windows では、置換されたパスのほとんどは C:/Users/you/... のように前方スラッシュを使用します。exec 形式のフックと、PowerShell を通じて実行されるフック（Git Bash がインストールされていない場合の Windows のデフォルトシェル）では、ネイティブのバックスラッシュが維持されます。

データディレクトリに依存関係をインストールする

マーケットプレイスでインストールされたプラグインの場合、Claude Code はプラグインをキャッシュするときに適格なNode.js パッケージ依存関係を自動的にインストールするため、自分でインストールする必要がない場合があります。インストールする場合、この SessionStart フックは最初の実行時に ${CLAUDE_PLUGIN_DATA} に node_modules をインストールし、更新が package.json を変更した後に再度インストールします：

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

最初のセッションの後、~/.claude/plugins/data/<id>/node_modules が存在します。MCP サーバーは、その env で NODE_PATH を ${CLAUDE_PLUGIN_DATA}/node_modules に設定できます。どのフィールドがどの変数を置換するかについては、環境変数を参照してください。

次のステップ

プラグインマニフェストリファレンス：plugin.json フィールド、パスルール、標準レイアウト
evals でプラグインをテストする：追加したコンポーネントが Claude の動作を意図した方法で変更することを確認します
プラグインを公開および配布する：プラグインをバージョン管理し、マーケットプレイスに配置します
プラグインのトラブルシューティング：コンポーネントが読み込まれない場合またはフックが発火しない場合の対処方法

plugins/components.md 2026-11-11 22:59 UTC to 2026-11-12 23:02 UTC

プラグインにコンポーネントを追加する

プラグインディレクトリを探索する

各種類のコンポーネントを追加する

スキル

コマンド

マニフェストでコマンドを定義する

エージェント

エージェントをサブフォルダーで整理する

プラグインエージェントのフロントマターフィールド

フック

プラグインのフックが発火するタイミング

環境、クォート、MCP ツールのマッチング

MCP サーバー

claude.ai と Cowork のユーザーに届ける

サーバー名、ツール名、再読み込み

パッケージ化された MCPB サーバーを含める

LSP サーバー

実行可能ファイル

デフォルト設定

テーマと出力スタイル

チャネル

モニター

ユーザーに設定値を求める

設定ダイアログが表示されるとき

プラグインパスを参照し、データを保存する

データディレクトリに依存関係をインストールする

次のステップ