Claude Code の Plugins(プラグイン)を自作して配布する実装手順 ― marketplace.json と $CLAUDE_PLUGIN_ROOT の3つのハマりどころ【2026】

はじめに / 対象と前提

Claude Code には、スラッシュコマンド・サブエージェント・hooks・MCP サーバー・Skill をひとまとめにして配布できる Plugins という仕組みがある。チームに同じ hooks や lint 設定を配りたい、自作の便利コマンドを他プロジェクトでも使い回したい、というときに個別コピペするより圧倒的に楽になる。

この記事は以下を前提にしている。

• Claude Code CLI を日常的に使っていて、.claude/hooks や .claude/commands を自作した経験がある人
• 「Plugins って聞いたことはあるけど自作したことはない」レベルの人
• 確認環境:Claude Code CLI(2026年8月時点の最新版)、macOS + zsh

自分は自作 hooks(保存時 lint)を毎回プロジェクトにコピペするのに疲れて Plugins 化したところ、地味なところで2回ハマった。その記録。

TL;DR

• Plugin は .claude-plugin/plugin.json が本体、配布は .claude-plugin/marketplace.json を持つリポジトリ(マーケットプレイス)経由
• commands/ agents/ hooks/hooks.json skills/ .mcp.json を1つの plugin ディレクトリにまとめて配布できる
• hooks 内で自分のスクリプトを呼ぶときは相対パスではなく ${CLAUDE_PLUGIN_ROOT} を使わないと、インストール先によって静かに失敗する

手順 / 動かし方

1. plugin 本体を作る

my-lint-plugin/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   └── hooks.json
└── scripts/
    └── lint.sh

plugin.json:

{
  "name": "my-lint-plugin",
  "version": "1.0.0",
  "description": "保存時に自動lintをかけるプラグイン"
}

hooks/hooks.json:

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

2. マーケットプレイスを作る

配布用の別リポジトリ(または同一リポジトリの別ディレクトリ)に .claude-plugin/marketplace.json を置く。

{
  "name": "my-marketplace",
  "owner": { "name": "yourname" },
  "plugins": [
    {
      "name": "my-lint-plugin",
      "source": "./plugins/my-lint-plugin",
      "description": "保存時に自動lintをかけるプラグイン"
    }
  ]
}

3. インストールして動作確認

/plugin marketplace add ./my-marketplace-repo
/plugin install my-lint-plugin@my-marketplace

インストール後、適当なファイルを Edit してみて scripts/lint.sh が実際に走るかを確認する。走らない場合は次の「ハマりどころ」を疑う。

ハマりどころ

1. hooks 内の相対パスが解決できない

最初 command を "./scripts/lint.sh" と相対パスで書いていたところ、手元では動くのにインストール経由だと無反応だった。原因は plugin のインストール先ディレクトリと Claude Code の実行時 cwd が一致しないこと。hooks はどのプロジェクトの cwd からでも呼ばれるので、相対パスは基本的に破綻する。${CLAUDE_PLUGIN_ROOT}(plugin 自身がインストールされているディレクトリを指す環境変数)で絶対パス化するのが正解。

2. marketplace.json の source パスの起点ミス

source は marketplace.json 自身の位置(.claude-plugin/ の親ディレクトリ)からの相対パスになる。plugin ディレクトリを marketplace リポジトリの外に置いていたときに plugin not found 相当のエラーで弾かれた。marketplace リポジトリ配下に plugin をまとめて置くか、source を書き直す必要がある。

3. plugin.json を編集しても反映されない

インストール済みの plugin の plugin.json を直接書き換えても、既存セッションには反映されないことがあった。マーケットプレイスの更新を取り込む操作(/plugin marketplace add の再実行、もしくは plugin の再インストール)をしてから Claude Code を再起動して初めて反映された。「設定を直したのに動きが変わらない」と思ったらまずここを疑うとよい。

背景・補足

hooks 単体・commands 単体なら .claude/ 直下にファイルを置くだけで動くが、それだと「このプロジェクトだけの設定」で終わってしまう。Plugins 化すると、複数プロジェクト・複数マシンに同じ設定を配れるようになるので、個人の定型作業を自動化するレイヤーをそのまま「配布可能な単位」に昇格させられるのが大きい。自分は Claude Code に日次のルーチン作業(状態ファイルの読み込みや定型チェック)を任せる構成をいくつか組んでいるが、そうした自動化レイヤーの部品を plugin 化しておくと使い回しが効いて楽になる。

まとめ

• Plugin の本体は plugin.json、配布は marketplace.json を持つリポジトリ経由
• hooks 内のスクリプト参照は必ず ${CLAUDE_PLUGIN_ROOT} で絶対パス化する(相対パスは cwd 次第で壊れる)
• marketplace.json の source は marketplace 自身からの相対パスであることに注意
• 設定変更が反映されないときはマーケットプレイスの再取り込み+再起動を試す
• 個人用の hooks・commands が増えてきたら、コピペ運用をやめて plugin 化する価値がある