【完全ガイド】Claude Codeプラグインとは？作り方からマーケットプレイスの公開までを解説

「Claude Codeをもっと自分たちのワークフローに合わせたい」
そう感じたことはないでしょうか。その答えのひとつが、プラグインです。

この記事では、PRレビュー自動化プラグインをゼロから作り、ローカルで動作確認し、マーケットプレイスへ公開するまでの全工程を実体験ベースで解説します。
使ったファイル構成・実行コマンド・つまずいたポイントと対処法まで、手順を追えば再現できる形でまとめました。加えて、マーケットプレイスについても解説しています。

「プラグインって難しそう」、「マーケットプレイスとは何？」と感じている方にこそ、読んでいただきたい内容です。

Claude Codeのプラグインは「共有可能な拡張パッケージ」です。
最初は小さく作ってテストしながら成長させていくのがおすすめです。

Claude Codeのプラグインとは？

プラグインはClaude Codeを拡張する自己完結型ディレクトリ構造です。
内部にはskills、agents、hooks、.mcp.json（MCP）、.lsp.json（LSP）など、目的に応じたコンポーネントを自由に組み合わせられます。

個人のローカル設定向けであるスタンドアロン（.claude/）と異なり、プラグインはチーム共有・バージョン管理・マーケットプレイス公開を前提に設計されています。/my-plugin:hello のように名前空間付きで呼び出せるため、同じ機能をチーム内で安全に再利用できるのが大きな強みです。

判断の目安はシンプルです。個人で完結する設定なら .claude/ のスタンドアロンで十分。
チームへの共有や再利用が必要になった時点で、.claude-plugin としてプラグイン化を検討しましょう。

プラグインの主要コンポーネント

プラグインは複数の機能ブロックで構成されます。各コンポーネントの役割を把握しておくと、目的に応じた設計がしやすくなります。

.claude-plugin/plugin.jsonの役割

plugin.json はプラグインのメタ情報（name、version、description、author など）を定義するマニフェストファイルです。
マーケットプレイスやCLIはこのファイルを参照してプラグインを識別するため、最初に正確に作成しておくことが重要です。

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

その他のコンポーネントの役割

• skills/（またはcommands/）：SKILL.mdを置くディレクトリ。スラッシュコマンドの実体となります。
• agents/：特化したサブエージェントの定義。Claudeが状況に応じて自動的に呼び出すことがあります。
• hooks/：イベントハンドラ（hooks.json）。PostToolUse や UserPromptSubmit などのタイミングで外部スクリプトを起動できます。
• MCP servers（.mcp.json）：外部サービスと連携するためのModel Context Protocolサーバー定義。プラグインにバンドルしてツール化できます。
• LSP servers（.lsp.json）：言語サーバー設定。TypeScriptやPythonなどのリアルタイムコードインテリジェンスを提供します。

代表的なディレクトリ構成

典型的な構成は以下のとおりです。
ルートに .claude-plugin を置き、同階層skills/・agents/・hooks/などを並べます。

my-first-plugin/
├─ .claude-plugin/
│  └─ plugin.json
├─ skills/
│  └─ hello/
│     └─ SKILL.md
├─ agents/
├─ hooks/
└─ .mcp.json

なぜプラグイン化するのか（スタンドアロンとの違い）

両者の最大の違いは「配置場所」と「用途の想定」にあります。
スタンドアロン（~/.claude やプロジェクトの .claude/）は手早く試せる個人設定向け、プラグインは配布・共有・バージョン管理を前提とした構造です。

• スタンドアロン：高速に試せるが共有が難しい
• プラグイン：明確な構造でリポジトリ配布が可能

個人実験ならスタンドアロン、チームや公開を視野に入れるならプラグイン――そんなイメージで使い分けると迷わないね。

インストール・スコープ・CLI操作

プラグインはスコープ（user / project / local / managed）ごとに管理されます。
スコープは設定の適用範囲を決めるため、運用ポリシーに合わせて適切に選びます。

代表的なCLIコマンド例

以下は典型的なCLIコマンド例です。

# インストール（例：project スコープ）
claude plugin install formatter@my-marketplace --scope project

# 有効化 / 無効化
claude plugin enable my-first-plugin --scope project
claude plugin disable my-first-plugin --scope project

# 更新 / アンインストール
claude plugin update my-first-plugin --scope project
claude plugin uninstall my-first-plugin --scope project

スコープが編集する設定ファイル

一般的なスコープと影響先の例

• user → ~/.claude/settings.json
• project → ./.claude/settings.json（プロジェクトルート）
• local → ./.claude/settings.local.json（ローカル・一時）
• managed → 管理者が制御する集中管理領域（企業向け）

運用例：個人設定はuser、チームで共通するプラグインはproject、一時的な検証は localを使うと整理しやすいです。

プラグインを作ってみた

概要

公式ドキュメントを参考に、実用的なプラグインをゼロから作成します。

今回作ったのは、Pull Requestの差分から可読性・パフォーマンス・セキュリティの3観点で簡易レビューコメントを自動生成するプラグインです。

環境とディレクトリ構成

作業前にバージョンとログイン状態を確認しておきます。

claude --version
# 出力例: 2.1.74 (Claude Code)

今回使用するディレクトリ構成は以下のとおりです。

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

plugin.json

実際に使用した plugin.json は以下のとおりです。

{
  "name": "my-first-plugin",
  "description": "Automated PR review suggestions (readability, perf, security)",
  "version": "1.0.0",
  "author": { "name": "kuretom" },
  "homepage": "https://github.com/yourname/my-first-plugin"
}

name は名前空間と連動するため、英数字とハイフンのみを使い小文字で統一します。version はセマンティックバージョニング（MAJOR.MINOR.PATCH）を採用します。

plugin.jsonってどこに置くの？

.claude-plugin/plugin.json のパスに置いてね。
nameやversion は正しい形式で書くことが大事だよ。

skills/とSKILL.mdの書き方

まずは SKILL.md だけで動く最小構成から始めます。
以下が実際に使用した SKILL.md の内容です。

---
name: review
description: Generate concise PR review suggestions from a diff or code snippet
---
受け取った差分またはコードを、可読性・パフォーマンス・セキュリティの3観点で要約し、それぞれ改善提案を出してください。
入力の例:
$ARGUMENTS
- diff: 差分テキスト
- language: 言語指定（省略可）

作成後は以下のコマンドで呼び出せます。

/my-first-plugin:review

ローカルでのテスト

プラグインはインストールしなくても動くって本当？

うん、–plugin-dirを使えばインストールなしでローカルのプラグインを読み込めるよ。

開発中は以下のコマンドでローカルディレクトリを直接読み込み、動作を確認します。
インストールなしで何度でも繰り返し検証できるのが利点です。

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

# 起動後に/plugin listでinstalledにmy-first-pluginが表示されることを確認
/plugin list

# 起動後にターミナルでスキルを実行して確認
/my-first-plugin:review

実行すると、差分の比較結果が以下のように出力されます。

読み込んでるのにスキルが見つからないことがあるんだけど？

プラグインが読み込めない・スキルが呼び出せない場合は、以下の項目を順番に確認してください。

マーケットプレイスとしてpluginを公開する

マーケットプレイスとは？

マーケットプレイスとは、複数のプラグインを一覧化して配布するカタログ基盤です。
マーケットプレイスを追加登録することで、そこに収録された個別プラグインをコマンド一発でインストールできるようになります。

プラグインとマーケットプレイスの違い

• プラグイン：単一の拡張パッケージ。個別に配布・インストール可能。チームで共有するためにプラグイン単位で管理することが多い。
• マーケットプレイス：複数のプラグインを一覧化するカタログ。マーケットプレイスを追加して、そのカタログからプラグインを選んでインストールできる。バージョン追跡、自動更新、複数ソース（Gitリポジトリ、ローカルパス、npmパッケージ 等）をサポートする。

プラグインが「個別の機能」、マーケットプレイスが「複数プラグインをまとめたカタログ」――アプリとアプリストアの関係に近いイメージです。

個人や小規模チームであればプラグイン単体での配布で事足ります。複数のプラグインを一元管理したい場合や、自動更新・権限管理が必要になった段階で、マーケットプレイスを構築する価値が出てきます。

マーケットプレイスに必要なファイルとフォーマット

プロジェクトのルートディレクトリに .claude-plugin/marketplace.json を配置し、plugins/ 配下に各プラグインをまとめます。
marketplace.json にはマーケットプレイス名（name）、所有者情報（owner）、そして plugins 配列を定義します。各プラグインエントリには最低限 name と source（取得元）が必要です。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

マーケットプレイスのホスティングと配布方法

ホスティングにはGitHubが最もシンプルで手軽です。
リポジトリを作成して .claude-plugin/marketplace.json を追加すれば、ユーザーは以下のコマンドで追加・インストールできます。他のGitサービスやURL配布も可能ですが、相対パスを使用する場合はGitベースのホスティングが推奨されます。

/plugin marketplace add owner/repo
/plugin install review-plugin@my-plugins

marketplaceを作ってみた

概要

今回は pr-pilot-marketplace という名称でマーケットプレイスを実際に構築します。
.claude-plugin/marketplace.json を作成し、plugins/ フォルダ内にプラグイン（pr-pilot）をまとめることで、誰でも再利用できる形に仕上げます。

収録したプラグイン（pr-pilot）の機能は、「PRに関わるコードレビュー・変更履歴・コミットメッセージ・テスト提案を、引数なしのスラッシュコマンドひとつで自動生成できる」というものです。

プロジェクトのディレクトリ構成は以下のとおりです。

pr-pilot
├── .claude-plugin
│   └── marketplace.json
├── .gitignore
├── LICENSE
├── README.md
└── plugins
    └── pr-pilot
        ├── plugin.json
        └── skills
            ├── changelog
            │   └── SKILL.md
            ├── commit-msg
            │   └── SKILL.md
            ├── review
            │   └── SKILL.md
            └── test-suggest
                └── SKILL.md

.claude-plugin/marketplace.jsonの内容は以下のとおりです。

{
  "name": "pr-pilot-marketplace",
  "owner": {
    "name": "kuretom"
  },
  "metadata": {
    "description": "kuretom's plugin marketplace for Claude Code"
  },
  "plugins": [
    {
      "name": "pr-pilot",
      "source": "./plugins/pr-pilot",
      "description": "PR workflow toolkit — review, changelog generation, commit message drafting, and test suggestion skills for Claude Code",
      "version": "1.0.0",
      "author": {
        "name": "kuretom"
      },
      "repository": "https://github.com/kuretom-blog/pr-pilot-marketplace",
      "license": "MIT",
      "category": "development",
      "tags": ["pr", "review", "changelog", "commit", "test", "workflow"]
    }
  ]
}

marketplaceのインストール

GitHubにpushしたマーケットプレイスとプラグインは、以下のコマンドでいつでもどこからでもインストールできます。

# マーケットプレイスを追加
/plugin marketplace add kuretom-blog/pr-pilot-marketplace

# マーケットプレイスからプラグインをインストール
/plugin install pr-pilot@pr-pilot-marketplace

インストール後は /plugin コマンドで状態を確認できます。

/plugin

「Marketplaces」タブでは、追加済みのマーケットプレイスを確認できます。

「Installed」タブでは、インストール済みのプラグインを確認できます。

使えるスキルの一覧も以下の画面で確認できます。

pr-pilotプラグインは、次のワークフローに沿って活用できます。

（番外編）公式マーケットプレイスに登録申請

公式マーケットプレイスへの登録申請方法を紹介します。
前述の手順どおりGitHubからインストールして使う分には、この申請は必須ではありません。

ただ、「他の開発者にも役立つはず」と感じたプラグインであれば、申請してみる価値は十分あります。以下の手順で提出できます。

GitHubのURLとプラグインの詳細情報（名前・説明・ユースケース）を入力します。

「Supported platforms」でClaude Codeを選択し、Submitで申請完了です。

公式マーケットプレイスに掲載されると、以下のメリットがあります。技術的な貢献の実績としても残るため、興味があれば積極的に挑戦してみてください。

まとめ

この記事では、Claude Codeのプラグインについて、概念の整理から実際の作成・テスト・マーケットプレイス公開まで、一連の流れを実体験ベースで解説しました。

要点を振り返ると、プラグインは.claude-plugin/plugin.jsonとskills/の2つがあれば最小構成として動作します。
開発中は --plugin-dir オプションを使えばインストール不要でローカル検証でき、チームへの共有はGitHubリポジトリ経由で完結します。

「まず小さく作ってみる」
これがプラグイン開発の最大のコツです。
今回紹介したpr-pilotのように、日常業務の繰り返し作業をスラッシュコマンド一つに集約するだけで、開発体験は大きく変わります。
ぜひ自分のワークフローに合ったプラグインを作るところから始めてみてください。