背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. これは一言でいうと何か

プラグインは、スキル・エージェント・フック・MCP サーバーといった拡張をひとまとめにし、プロジェクトやチームをまたいで共有できるようにする仕組みです。実体は自己完結したディレクトリで、スキルやエージェント、フックを含み、任意で .claude-plugin/plugin.json というマニフェストを持ちます。

ここまでの連載で扱ってきた拡張（第6回スキル、第7回フック、第8回 MCP、第9回サブエージェント）を、「自分の環境の設定」から「配布物」に変えるレイヤー、と捉えると位置づけが明確です。

2. どういう場面で役立つか

Claude Code はカスタムのスキル・エージェント・フックを2通りで追加できます。.claude/ に直接置くスタンドアロン設定と、プラグインです。判断軸ははっきりしています。

プラグインを使う場面。

• チームやコミュニティと機能を共有したい：マーケットプレイス経由で /plugin install できる形になります。
• 複数プロジェクトで同じスキル/エージェントが要る：プロジェクトごとにコピーして回る運用から抜けられます。
• バージョン管理と更新が要る：version を設定すれば、バンプしたときだけ利用者に更新が届きます（省略して git 配布する場合はコミット SHA が使われ、全コミットが新バージョン扱いになります）。
• 名前空間の衝突を避けたい：プラグインのスキルは常に /plugin-name:skill-name の形で名前空間が付き、複数プラグイン間で同名スキルが衝突しません。

逆にスタンドアロン設定（.claude/）が向く場面。 単一プロジェクト向けのカスタマイズ、共有不要な個人的設定、パッケージ化する前の実験、そして**/hello や /deploy のような短いスキル名が欲しいとき**です。プラグイン化すると名前は必ず名前空間付きになるので、ここは実質的なトレードオフになります。公式の勧め方も「まず .claude/ で素早く回し、共有する段になって変換する」です。

3. コード・コマンドの実例と解説

前提条件

• Claude Code がインストール済み・認証済みであること。/plugin コマンドが出てこない場合は最新版に更新します。
• ディレクトリ配置の間違いが最頻出の事故です。 .claude-plugin/ に入れてよいのは plugin.json だけで、skills/・agents/・hooks/・commands/ などはプラグインルート直下に置きます。ここでいうプラグインルートとは .claude-plugin/plugin.json を含むディレクトリであって、~/.claude/ ではありません。

マニフェストを作る

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

my-first-plugin/.claude-plugin/plugin.json として保存します。name は一意の識別子であると同時にスキルの名前空間になります（この例なら /my-first-plugin:hello）。description はプラグインマネージャーでの表示に使われます。version と author は任意です。名前空間の接頭辞を変えたいときは name を書き換えます。

スキルを1つ入れる

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

my-first-plugin/skills/hello/SKILL.md に保存します。フォルダ名がスキル名になり、そこにプラグイン名が接頭辞として付きます。第6回で扱ったスキルの書式そのままで、disable-model-invocation: true を付ければユーザーだけが呼べるスキルになります。

ローカルで読み込んでテストする

claude --plugin-dir ./my-first-plugin

インストール手順を踏まずにプラグインを直接読み込めるので、開発中はこれが基本になります。起動後は /my-first-plugin:hello で試し、/help で名前空間の下に並んでいるか確認します。.zip アーカイブも渡せます（v2.1.128 以降）。フラグを複数回書けば複数プラグインを同時に読み込めます。

同名のマーケットプレイスプラグインが既にインストール済みでも、そのセッション中は --plugin-dir のローカルコピーが優先されるため、アンインストールせずに変更を試せます。変更後は /reload-plugins を実行すれば、再起動なしでスキル・エージェント・フック・MCP・LSP が再読み込みされます。

毎回フラグを渡さずに開発する

claude plugin init my-tool

~/.claude/skills/my-tool/ に、マニフェストとスターターの SKILL.md が生成されます。次のセッションから my-tool@skills-dir として自動的に読み込まれるので、マーケットプレイスもインストール手順も不要です。

既存の .claude/ をプラグインに変換する

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

マニフェストを作ったうえで、既存の資産をプラグインルートへコピーします。フックだけは置き場所が変わり、.claude/settings.json の hooks オブジェクトを my-plugin/hooks/hooks.json に移します（形式は同じです）。

移行後の注意が1点あります。元ファイルは削除してください。 プロジェクトやユーザーの .claude/agents/ の定義は同名のプラグインエージェントを上書きするため、消さないとプラグイン版が有効になりません。一方スキルは名前空間が違うので、元の /skill-name とプラグイン版 /plugin-name:skill-name が両方とも生き残ります（上書きではなく共存）。

その他（agents/・.mcp.json・.lsp.json・monitors/・bin/・settings.json といったコンポーネントの詳細、LSP サーバー設定、バックグラウンドモニター、--plugin-url によるリモート zip の読み込み、マーケットプレイスの作成と配布、コミュニティマーケットプレイスへの送信、claude plugin validate）は公式ドキュメントを参照してください。

4. まとめと次回予告

• プラグインは拡張を「配れる形」にするレイヤー。共有・複数プロジェクト・バージョン管理が要るならこちらです。
• 個人利用や短いスキル名が欲しいうちは .claude/ のままでよく、共有する段で変換すれば十分です。
• 開発は --plugin-dir で読み込み、/reload-plugins で反映。この2つで回せます。

つまずくならほぼここです。 commands/・agents/・skills/・hooks/ を .claude-plugin/ の中に入れてしまう配置ミスが、公式ドキュメントでも「よくある間違い」として名指しされています。.claude-plugin/ に入るのは plugin.json だけ、残りはすべてプラグインルート直下です。動かないときは、まず構造を確認し、次に各コンポーネント（スキル・エージェント・フック）を個別に切り分けて検証してください。

なお、スキルがちょうど1つだけのプラグインなら、skills/ を作らずプラグインルートに SKILL.md を直接置くこともできます（この場合はフロントマターの name が呼び出し名になります）。将来スキルが増える見込みがあるなら、最初から skills/ レイアウトにしておくのが無難です。

次回予告：連載の締めくくりとして、実務で効く使い方をまとめた「ベストプラクティス」を取り上げる予定です。

関連ページ（本記事で触れた概念の詳細）：スキルの書き方と引数 →「Skills」、hooks.json の形式と終了コード →「Hooks」、.mcp.json と ${CLAUDE_PLUGIN_ROOT} →「MCP」、agents/ の定義 →「サブエージェント」、完全な技術仕様とデバッグ →「プラグインリファレンス」、配布 →「プラグインマーケットプレイス」、インストール →「プラグインを検出してインストールする」。

---

本記事は執筆時点の公式ドキュメント（プラグインを作成する）に基づきます。最新は公式ドキュメントをご確認ください。