Claude Code Plugin実践ガイド — 発見・導入・自作・チーム共有の全手順

Claude Codeの真価はプラグインで引き出す。Skills・Hooks・MCPサーバー・AGENT.mdといった個別機能は使いこなせても、それらを「プラグイン」としてパッケージ化し、ワンコマンドで導入・チーム共有できることを知っている開発者はまだ少ない。本記事では、プラグインの発見から自作・組織標準化までを、実際のコマンドと設定ファイル付きで一気通貫に解説する。

Claude Code Pluginとは何か — Skills・Hooks・MCPをバンドルする仕組み

プラグインが解決する問題：設定の属人化とコピペ地獄

チームでClaude Codeを使っていると、「あの人のCLAUDE.mdを共有して」「MCPサーバーの設定どうやるんだっけ」というやり取りが頻発する。settings.jsonやCLAUDE.mdを手動コピーして回る運用は、バージョン管理もできず属人化の温床になる。

プラグインはこの問題を根本から解決する仕組みだ。Skills・Hooks・MCPサーバー設定・Agents・LSPサーバーといった機能群を1つのパッケージにまとめ、claude plugin install でワンコマンド導入できるようにする。

プラグインの構成要素

プラグインは .claude-plugin/ ディレクトリに格納され、以下の要素をバンドルできる。

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # マニフェスト（nameのみ必須）
├── skills/                  # スラッシュコマンド（SKILL.md）
│   └── review/
│       └── SKILL.md
├── agents/                  # サブエージェント定義
├── hooks/
│   └── hooks.json           # ライフサイクルフック
├── .mcp.json                # MCPサーバー設定
├── .lsp.json                # LSPサーバー設定
└── settings.json            # デフォルト設定

plugin.json は省略可能で、省略した場合はClaude Codeがディレクトリ構造から各コンポーネントを自動検出する。正直、この自動検出がよくできていて、最小構成なら plugin.json なしでも動く。

プラグインの発見とインストール — マーケットプレイスの使い方

公式マーケットプレイスからの導入

Claude Codeには公式マーケットプレイス（anthropics/claude-plugins-official）がデフォルトで登録されている。LSP連携やコードレビュー、各種SaaS統合など数十個のプラグインが用意されており、追加設定なしで利用できる。

プラグインの発見にはCLI内で /plugin コマンドを使う。Discoverタブで一覧を確認し、そのままインストールできる。

# プラグインのインストール（/plugin スラッシュコマンド形式）
/plugin install typescript-lsp@claude-plugins-official

# マーケットプレイスを指定してインストール
/plugin install code-review@claude-plugins-official

# スコープ指定（user / project / local）
/plugin install supabase@claude-plugins-official --scope project

# インストール済みプラグインの確認
claude plugin list

# プラグインの無効化（アンインストールせず一時停止）
claude plugin disable code-review

# マーケットプレイス単位での更新
/plugin marketplace update claude-plugins-official

スコープは3種類あり、用途に応じて使い分ける。user（デフォルト）は ~/.claude/settings.json に、project は .claude/settings.json に、local は .claude/settings.local.json に記録される。チームで共有したい場合は --scope project を選ぶとよい。

コミュニティマーケットプレイスの追加と注意点

公式以外にもコミュニティが運営するマーケットプレイスが存在する。GitHubリポジトリ、GitURL、ローカルパスなどを指定して追加できる。

# GitHubリポジトリをマーケットプレイスとして追加
claude plugin marketplace add owner/repo-name

# 登録済みマーケットプレイスの一覧
claude plugin marketplace list

# マーケットプレイスのリスティングを更新
claude plugin marketplace update

セキュリティ上の注意: コミュニティプラグインのHooksは任意のシェルコマンドを実行できる。インストール前に必ずリポジトリのソースコードを確認すること。マーケットプレイスからインストールされたプラグインは ~/.claude/plugins/cache/ にコピーされるため、インストール後にリモートが改ざんされても既存環境には影響しない。

プラグインを自作する — 最小構成から始める実装手順

plugin.jsonの書き方とメタデータ

自作プラグインの plugin.json は name フィールドのみ必須だ。以下が主要フィールドの全体像になる。

{
  "name": "my-team-plugin",
  "version": "1.0.0",
  "description": "チーム標準の開発支援プラグイン",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/yourname"
  },
  "license": "MIT",
  "keywords": ["review", "testing"],
  "skills": "./skills/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

skills・hooks・mcpServers などのパスはすべて ./ から始まる相対パスで指定する。カスタムパスはデフォルトディレクトリを置き換えるのではなく、補完する形で動作する。

Skillsの定義（スラッシュコマンド）

Skillは skills/ ディレクトリ内にサブディレクトリを作り、SKILL.md を配置する。

<!-- skills/quick-review/SKILL.md -->
---
name: quick-review
description: 変更差分をレビューして改善点を指摘する
---

現在のgit diffの内容をレビューしてください。
以下の観点で改善点を指摘してください：

1. バグの可能性がある箇所
2. パフォーマンス上の懸念
3. セキュリティリスク

問題がなければ「LGTM」とだけ回答してください。

インストール後、/quick-review としてスラッシュコマンドから呼び出せる。

Hooksの組み込み

Hooksはライフサイクルイベントに応じて自動実行される処理だ。command（シェル）、http（POST）、prompt（LLM評価）、agent（エージェント検証）の4タイプがある。

// hooks/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "matcher": "Write|Edit",
        "command": "npx prettier --write ${CLAUDE_FILE_PATH}",
        "timeout": 10000
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/on-stop.sh"
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} でプラグインのインストールディレクトリを参照できる。

MCPサーバーのバンドル

MCPサーバーの設定は .mcp.json に記述するか、plugin.json 内にインラインで定義する。

// .mcp.json
{
  "mcpServers": {
    "my-db-server": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

settings.jsonでのインラインプラグイン宣言

マーケットプレイスを使わないローカル運用

正式なマーケットプレイスを構築せず、settings.jsonの extraKnownMarketplaces に外部ソースとしてプラグインを宣言する方法もある。

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@team-tools": true
  }
}

enabledPlugins で "プラグイン名@マーケットプレイス名": true の形式で有効化する。

プロジェクト単位 vs ユーザー単位の使い分け

チームで共有すべき設定は .claude/settings.json に、API鍵などの機密情報を含む設定は .claude/settings.local.json に分離するのが基本だ。

チーム標準化 — プラグインで開発体験を統一する

プライベートマーケットプレイスの構築

GitHubリポジトリをそのままプライベートマーケットプレイスとして運用できる。

acme-corp/claude-plugins/          # プライベートリポジトリ
├── marketplace.json               # マーケットプレイスマニフェスト
├── plugins/
│   ├── acme-review/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       └── review/
│   │           └── SKILL.md
│   └── acme-deploy/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── hooks/
│           └── hooks.json
└── external_plugins/              # 外部プラグインへの参照

チームメンバーは一度 claude plugin marketplace add acme-corp/claude-plugins を実行すれば、以降はすべてのチームプラグインにアクセスできる。.claude/settings.json に extraKnownMarketplaces として記述しておけば、リポジトリをcloneした時点でマーケットプレイスの信頼確認が促される。

CLAUDE.mdとプラグインの役割分担

両者の使い分けは明確だ。CLAUDE.md はプロジェクト固有のルール（コーディング規約、アーキテクチャ方針、ビルド手順）を記述する場所。プラグイン はプロジェクト横断で再利用できる汎用機能（レビューSkill、フォーマットHook、DB接続MCP）をパッケージ化する仕組み。これは地味に重要な区別で、混同するとメンテナンスが破綻する。

よくあるハマりポイントと解決策

Hooksのシェルスクリプトが動かない — 実行権限の付与忘れが最多原因。chmod +x hooks/on-stop.sh を忘れずに。

MCPサーバーのパスが解決できない — npx で起動するMCPサーバーはグローバルのNode.js環境に依存する。${CLAUDE_PLUGIN_ROOT} を使ってプラグインディレクトリからの相対パスで指定するのが確実。

プラグイン間の競合 — 同名のSkillが複数プラグインに存在する場合、後からインストールしたものが優先される。claude plugin list で有効なプラグインを確認し、不要な方を disable する。

settings.jsonの構文エラーでClaude Codeが起動しない — JSONの構文エラーは即座にClaude Code全体に影響する。復旧するには該当のsettings.jsonを直接エディタで修正するか、一時的にリネームして起動後に修正する。

# 緊急復旧：問題のある設定を退避
mv ~/.claude/settings.json ~/.claude/settings.json.bak
# Claude Code起動後に修正して戻す

セッション限定で試したい — インストールせずに一時的にプラグインを読み込む --plugin-dir オプションが便利。自作プラグインの動作確認に使える。

claude --plugin-dir ./my-plugin-dev

Claude Code Pluginは、個別に使っていたSkills・Hooks・MCPを「再利用可能なパッケージ」に昇華させる仕組みだ。マーケットプレイスからの導入で即座に生産性を上げられるだけでなく、自作プラグインをチームで共有することで、開発体験そのものを標準化できる。まずは /plugin でDiscoverタブを開いて、気になるプラグインを1つインストールするところから始めてみてほしい。