著者 Claude Codeプラグインとは？仕組みと料金
Claude Codeプラグインの正体、保存場所、インストール方法を解説します。仕組み自体は無料ですが、読み込むスキルやMCP serverなどの利用ではトークンを消費します。
Claude Code プラグインとは
Claude Code プラグインは、Claude Code が単一の単位として読み込み、管理するコンポーネント一式を含む 1 つのディレクトリです。コンポーネントには、スキル、エージェント、フック、MCP サーバー、LSP サーバー、バックグラウンドモニターがあります。プラグインをインストールすると、すべての構成要素が 1 つの名前の下にまとめて追加され、無効化すると同じ方法ですべて削除されます。
プラグインによって、エージェントが本来持っていなかった能力を追加できるわけではありません。プラグイン内の各構成要素は、.claude/ ディレクトリに手動で作成できるものです。プラグインはパッケージング層です。構成要素にバージョンを付け、15 人に渡し、全員にファイルのコピーを依頼せずに後から更新するための仕組みです。これがプラグインの基本的な考え方です。プラグインに関する混乱の多くは、プラグインを新しい種類の機能だと考えることから生じます。
.claude-plugin/plugin.json にあるオプションのマニフェストでプラグイン名を指定します。この名前が名前空間になります。commit-commands というプラグイン内のスキルは /commit-commands:commit として呼び出します。そのため、2 つのプラグインがそれぞれ commit というスキルを提供しても、一方が他方を隠すことはありません。プラグインのエージェントも @ メンションの一覧で同じ方法によりスコープが設定され、plugin-name:agent-name となります。
プラグイン、skill、MCP server、rules file
この4つの言葉は、互いに競合するものとして使われがちです。しかし実際には競合せず、その境界をここで一度整理しておく価値があります。
- skill は、タスクに応じて Claude が読み込む1単位の指示です。Agent Skill の実体を参照してください。
- MCP server は、プロトコル経由で agent にツールを公開する別プロセスです。多くの場合、自分で運用するネットワークサービスです。
CLAUDE.mdのような rules file は、セッション開始時に読み込まれ、すべてに適用されるプロジェクトコンテキストです。- plugin は、skill、agent、hook、MCP server の定義をまとめて格納できるコンテナです。バージョン番号と配布チャネルも持ちます。
つまり、plugin が答える問いは「agent に何ができるか」ではありません。「これをチームにどう配布し、来月どう更新するか」です。最初の3つから選ぶ場合は、skill、MCP server、rules file の比較で判断方法を詳しく説明しています。MCP に関心がある場合は、VPS で独自の MCP server を運用する方法でホスティングについて説明しています。
プラグインの配置場所と内部構成
マーケットプレイスからインストールしたプラグインは、クローンした場所から実行されるのではなく、~/.claude/plugins/cache のローカルキャッシュにコピーされます。インストールした各バージョンには専用のディレクトリが割り当てられます。更新またはアンインストールを行うと、古いバージョンのディレクトリは孤立状態としてマークされ、約 2 週間後に削除されます。そのため、すでに古いバージョンを読み込んでいるセッションは、タスクの途中で失敗せずに処理を継続できます。
更新のたびにパスが変わるため、プラグインで自身の場所をハードコードしてはいけません。プラグイン内のフックと MCP 設定では ${CLAUDE_PLUGIN_ROOT} を使用します。これは現在のインストールディレクトリに解決されます。更新後も保持する必要がある状態は ${CLAUDE_PLUGIN_DATA} に保存します。これは ~/.claude/plugins/data/ 配下の安定したディレクトリに解決されます。
キャッシュにコピーされるのはプラグイン自身のディレクトリだけです。この点が、後から問題になることがあります。../shared-utils のようにプラグインのルート外を指すパスは、ローカルパスを使って開発している間は機能します。しかし、インストール後はそれらのファイルがコピーされていないため失敗します。
構成は次のようになります。
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── code-review/
│ └── SKILL.md
├── agents/
├── hooks/
│ └── hooks.json
├── .mcp.json
└── bin/plugin.json だけが .claude-plugin/ の中に入ります。それ以外はすべてプラグインのルートに置きます。skills/ または hooks/ を .claude-plugin/ の中に置くと、プラグインのインストールは正常に完了するのに、その後まったく動作しないことがあります。最も一般的な原因はこれです。Claude Code はこれらのディレクトリをルートで探しますが見つけられないため、コンポーネントのないプラグインを読み込みます。
マニフェスト自体は小規模です。
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0"
}Claude Code plugin のインストール方法
インストールは 2 段階で行います。最初の手順では何もインストールされません。まず、plugin のカタログである marketplace を追加し、そこから個々の plugin をインストールします。Anthropic の公式 marketplace である claude-plugins-official は、Claude Code を初めて対話形式で起動したときに登録されます。その他の marketplace は自分で追加します。
/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-pluginsrepository は anthropics/claude-code ですが、marketplace の名前は claude-code-plugins です。この名前は repository のパスではなく、repository 内のカタログファイルに由来します。そのため、install command を入力する前に、/plugin の Marketplaces タブで marketplace 名を確認してください。
インストール後は、概要行を確認します。Plugin is now active. は、このセッションでコンポーネントが読み込まれたことを示します。Run /reload-plugins to activate. は読み込まれていないことを示すため、その command を実行する必要があります。/reload-plugins が会話を再読み込みすると警告する場合は、/reload-plugins --force として再実行してください。続いて、plugin が実際に存在することを確認します。/plugin では Installed タブに plugin が表示され、/help では Custom commands の skill が一覧表示されます。読み込みに失敗した項目は、理由とともに Errors タブに表示されます。
インストール時には scope を指定します。scope によって plugin を使用できる範囲が決まります。User scope は自分だけが、すべての project で使用する設定です。Project scope では、repository の .claude/settings.json 内にある enabledPlugins に plugin が記録されます。そのため、repository を clone した全員にインストールが提示されます。Local scope は、自分だけがこの repository で使用する設定です。
script、Dockerfile、または対話形式のパネルを利用できないセッションでは、代わりに shell 形式を使用します。--scope を指定しない場合、user scope にインストールされます。
claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin listclaude plugin install はセッション外で実行されます。そのため、すでに開いているセッションでは、/reload-plugins を実行するか新しいセッションを開始するまで、新しい plugin は認識されません。
インストール済みの項目を管理する方法は、どちらの場所でも同じです。/plugin list はインストール済みの項目を表示し、--enabled または --disabled を受け付けます。/plugin disable name@marketplace は plugin を削除せずに無効化し、/plugin enable は再度有効化します。/plugin uninstall は plugin を削除します。slash-command 形式では plugin パネルを開いて変更を適用します。そのため、script では claude plugin ... の shell 形式を使用します。
marketplace をチーム全体に共有するには、project の .claude/settings.json に記載します。メンバーは repository フォルダーを信頼すると、1 回だけインストールを促されます。
{
"extraKnownMarketplaces": {
"my-team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}自分の plugin を開発中は、marketplace を使用しないでください。claude --plugin-dir ./my-plugin はそのセッションでディレクトリを読み込み、/reload-plugins は再起動せずに編集内容を反映します。claude plugin validate ./my-plugin は manifest、skill と agent の frontmatter、および hooks/hooks.json を、他のユーザーが使用する前に検証します。
Claude Code プラグインの費用はいくらですか？
仕組み自体は無料です。2026 年 8 月時点では、マーケットプレイスの追加、プラグインのインストール、有効化した状態の維持に料金はかかりません。公式およびコミュニティのマーケットプレイスは公開 git リポジトリであり、プラグインはテキストファイルのディレクトリです。
プラグインが消費するのはトークンです。トークンは、実際にはサブスクリプションの使用量または API 請求額として計測されます。どちらに影響するかは、最初にツールをどの方法で契約したかによって異なります。各プランでの Claude Code の料金では、サブスクリプションの料金体系と、トークン単位の API 料金を並べて説明しています。このコストは 3 通りの形で発生し、それぞれ挙動が異なります。
常駐コンテキストのコスト。 プラグインが提供する内容はコンテキストに組み込まれ、セッションの各ターンで再び読み込まれます。インストール前に、/plugin の詳細ビューで、Context cost にトークン数の見積もりが表示されます。また、追加されるコマンド、スキル、エージェント、フック、MCP サーバー、LSP サーバーを Will install セクションで確認できます。両方を確認してください。ローカルまたはカスタムのマーケットプレイスにあるプラグインでは、この情報が提供されない場合があります。その場合は手作業で見積もる必要があります。MCP サーバーを同梱するプラグインは、通常、最も負荷が大きくなります。ツール定義が大きいためです。ただし、MCP tool search に対応するモデルでは、ツールが必要になるまでこれらの定義は読み込まれません。
呼び出しのコスト。 プラグインのスキルを実行すると、その指示が会話に追加されます。そのため、スキル本体の料金が発生するのは使用時だけです。ただし、スキル本体はコストの小さい部分です。スキルがエージェントに指示する処理には、それ以上のコストがかかる場合があります。unlazy skill の Depth Tree 方式では、ほとんどのトークンが、エージェントによるタスク完了の宣言を許可する前に追加で実行させる処理に使われます。インストールしたファイル自体に使われるわけではありません。エージェントは異なります。サブエージェントは、独自のシステムプロンプトとキャッシュを持つ独立した会話を実行し、キャッシュヒットがない状態から開始します。そのため、ワークフローがエージェントを起動するプラグインは、コンテキストの見積もりから想定されるよりも大幅に高コストになります。
キャッシュのコスト。 セッションの途中でプラグインを有効化または無効化すると、次のリクエストで会話全体の再処理が必要になることがあります。スキル、コマンド、エージェント、フック、LSP サーバー、モニター、テーマでは、この処理は発生しません。これらが追加する内容は既存の履歴の後ろに追加されるため、次のリクエストでは新しい内容の料金だけが発生し、それ以前の内容は引き続きキャッシュから読み込まれます。例外は、MCP サーバーを提供するプラグインです。ツールが tool search によって遅延読み込みされる場合、キャッシュは維持されます。ツールがプロンプトのプレフィックスに読み込まれる場合、次のリクエストでは会話全体がキャッシュされていない入力として再読み込みされます。そのため、この場合は --force を渡すまで /reload-plugins が警告を表示して処理を拒否します。
推測せずに、実際の使用量を確認できます。すべての API レスポンスには cache_read_input_tokens と cache_creation_input_tokens が含まれます。また、トークン使用量をリアルタイム表示するカスタムステータスラインを設定すると、両方を常に確認できます。健全なセッションでは、生成するトークンよりもはるかに多くのトークンを読み込みます。ターンごとに生成量が高いままなら、プレフィックス内の何かが毎ターン変化しています。コンテキストウィンドウに何が追加されているかを詳しく確認するには、Claude Code のコンテキストウィンドウを管理する方法とそれらのトークン数が実際に意味することを参照してください。
定期的な整理も効果があります。Installed タブでは、少なくとも 2 週間使用していないプラグインが Not used recently ヘッダーの下にまとめられ、詳細ビューには Last used 行が表示されます。これらのプラグインは、すべてのセッションで起動時間とコンテキストを消費します。無効化するか、アンインストールしてください。
プラグインはユーザー権限で実行されます
Anthropic の公式ドキュメントでも、プラグインとマーケットプレイスは高度に信頼されたコンポーネントであり、マシン上でユーザー権限のまま任意のコードを実行できると明記されています。これは仮定の話ではありません。プラグインのフックは、ツール呼び出しの前後を含むセッションイベントでシェルコマンドを実行します。プラグインが有効な間は、その bin/ ディレクトリが Bash ツールの PATH に追加されます。プラグインの MCP サーバーは、プラグインが起動するプロセスです。これらはユーザーアカウントから分離されたサンドボックス内で実行されるわけではありません。
ノート PC では、このリスクはデスクトップユーザーがアクセスできる範囲に限定されます。しかし、サーバーでは通常そうなりません。エージェントを実行するアカウントには、SSH キー、デプロイトークン、クラウド CLI のセッション、Docker ソケットへのアクセス権が付与されていることが多いため、「ユーザー権限で任意のコードを実行できる」ということは、実質的にマシン全体を操作できることを意味します。Claude Code を VPS で実行する場合は、何かをインストールする前に VPS で Claude Code を安全に実行する方法 を確認してください。また、外部サービスと通信するプラグインをインストールする前に、認証情報をエージェントから隔離する方法 を確認してください。同じ借用サーバー上で動作する他のハーネスでも、同じ問題が発生します。そのため、インストールする価値のある DeepSeek Harness プラグイン の多くは、新しい機能ではなく、支出上限、ツール権限ルール、インジェクションスキャンを主な機能としています。
いくつかのガードレールは存在するため、どのように機能するかを把握しておくと役立ちます。プロジェクトスコープのプラグインは、ユーザー自身ではなくリポジトリから取得されるため、ワークスペースを信頼した後にのみ読み込まれます。MCP サーバーにはサーバーごとの承認が必要で、LSP サーバーもその信頼が確立されるまで待機します。一方、バックグラウンドモニターはまったく読み込まれません。プラグインに含まれるエージェントでは、フック、MCP サーバー、権限モードを宣言できません。マーケットプレイスの外部を指すシンボリックリンクはスキップされるため、マーケットプレイスのプラグインがホスト上の任意のファイルを取り込むこともできません。
ただし、これらの対策がインストール内容の確認に取って代わるわけではありません。Will install の一覧を確認し、ソースコードを開いて読めるプラグインを優先してください。チームのプラグインは、自分たちが管理するマーケットプレイスリポジトリに置き、独自に作成したものには claude plugin validate を実行してください。
FAQ
Claude Code のプラグインには追加料金がかかりますか？
いいえ。プラグインシステム、マーケットプレイスの追加、プラグインのインストールに料金はかかりません。費用が発生するのはトークン使用量で、他のコンテキストと同様に、プランまたは API の利用額として請求されます。プラグインは毎ターン固定のコンテキストを追加し、そのスキルまたはエージェントを呼び出すとさらにコンテキストを追加します。また、MCP server を提供し、そのツールがプロンプトプレフィックスに読み込まれる場合は、キャッシュされない高コストのターンが 1 回発生することがあります。インストール前に、/plugin の詳細ビューで Context cost の見積もりを確認できます。
プラグインとスキルの違いは何ですか？
スキルは、1 つの指示単位です。プラグインは、スキル、エージェント、hooks、MCP servers、LSP servers、monitors を含めることができるパッケージです。名前、バージョン、インストール元のマーケットプレイスも持ちます。自分とこのプロジェクトだけで使う場合は、.claude/ にスタンドアロンのスキルを記述します。動作する最小限の変更へエージェントを誘導する Ponytail のような単一目的のスキルが、その最も分かりやすい例です。1 つのルールを持つ 1 つのファイルとして始まり、チームでも必要になった時点でプラグインに変換します。他の人にも必要で、時間とともに更新する必要がある場合は、プラグインにします。プラグインのスキルには名前空間が付くため、プラグイン内のスキルは /plugin-name:skill-name ではなく /skill-name として呼び出します。
プラグインはインストールされましたが、スキルが表示されません。何が問題ですか？
まずインストール概要を確認します。Run /reload-plugins to activate. と表示された場合、コンポーネントはまだ読み込まれていません。再読み込み時に会話を再読み込みすると警告された場合は、/reload-plugins --force として再実行します。読み込み済みなのに何も表示されない場合は /plugin を開き、Errors タブを確認します。最も多い構成上の誤りは、skills/、agents/、または hooks/ を .claude-plugin/ の中に配置することです。Claude Code はその場所を参照しません。プラグインのスキルには名前空間が付くため、/help の Custom commands タブで /plugin-name:skill-name を探します。最後の手段として rm -rf ~/.claude/plugins/cache を実行し、再起動してから再インストールします。
インタラクティブパネルを使わずにプラグインをインストールできますか？
はい。シェルコマンド claude plugin install name@marketplace を使用します。--scope project または --scope local を指定しない限り、ユーザースコープにインストールされます。/plugin パネルを利用できないスクリプト、イメージ、非対話型環境でも動作します。セッション外で実行されるため、すでに開いているセッションでプラグインを有効にするには、/reload-plugins が必要です。
GitHub で見つけたマーケットプレイスのプラグインをインストールしても安全ですか？
そのリポジトリのインストールスクリプトを自分のユーザー権限で実行する場合と同じように扱ってください。実際、その状態に近い動作をするためです。プラグインは hooks を通じてシェルコマンドを実行でき、Bash tool の PATH に実行ファイルを追加できるほか、MCP servers を起動できます。いずれもユーザーの権限で実行されます。Anthropic はサードパーティ製プラグインの内容を管理または検証していません。内容を確認できるソースからインストールし、確認前に Will install の一覧を確認してください。サーバーではノート PC よりも厳格に判断します。サーバー上のアカウントには通常、盗難の価値がある key や token が保存されているためです。