---
title: "Claude Codeプラグインの作り方と社内配布｜marketplace.json・管理設定【2026年9月版】"
url: "https://www.issoh.co.jp/tech/details/17849/"
published: 2026-09-26
updated: 2026-10-31
categories: ["Claude"]
publisher: "株式会社一創"
---

# Claude Codeプラグインの作り方と社内配布｜marketplace.json・管理設定【2026年9月版】

Claude Codeのプラグインは、スキル・サブエージェント・フック・MCPサーバーをひとまとめにして、1コマンドで入れられるようにする仕組みです。個人で公式マーケットプレイスから入れるだけなら数分で終わりますが、チームへ配る段階で詰まる箇所がいくつもあります。この記事では2026年9月時点の公式ドキュメントとv2.1.282系の挙動をもとに、plugin.jsonを書いて自作プラグインを動かす手順、marketplace.jsonで社内マーケットプレイスを立てる手順、managed settingsで入手元を絞る設定までを、コピーして使えるコマンドとJSONで整理しました。

## まとめ：プラグインにする条件と社内配布で最初に決める設定

プラグインにする価値が出るのは、同じスキルやフックを3つ以上のリポジトリ、または複数人で使い回すときです。1人・1案件なら、`.claude/`配下にファイルを置くだけで足ります。プラグインは有効になっている間、使わないセッションでもスキル名と説明文を毎ターン読み込ませるため、作れば得というものではありません。

チームへ配ると決めたら、先に3点を決めてください。マーケットプレイスをどのリポジトリに置くか。projectスコープで配るのか、managed settingsで全端末に強制するのか。自社マーケットプレイスの自動更新を有効にするか（既定は無効）。この3点が曖昧なまま始めると、「設定はコミットしたのに同僚の端末で動かない」「レビューした後にファイルが差し替わった」という事故が起きます。

## Claude Codeプラグインの中身とv2.1.282時点で入る4種類の部品

最初に、プラグインが何を束ねるものなのかを揃えておきます。

### plugin.jsonと4つのディレクトリで決まる最小構成と名前空間

[公式のプラグイン概要](https://code.claude.com/docs/en/plugins)は、プラグインを「Claude Codeが1単位としてインストールし読み込む、スキル・エージェント・フック・MCPサーバーなどのディレクトリ」と定義しています。目印は`.claude-plugin/plugin.json`というマニフェストで、必須は`name`だけです。この`name`がスキルの接頭辞になり、`hello`というスキルは`/my-plugin:hello`として呼び出されます。2つのプラグインが同名のスキルを持っていても衝突しないのは、この名前空間があるためです。

| 置き場所                 | 中身                   |
| -------------------- | -------------------- |
| plugin.json（専用フォルダ内） | マニフェスト               |
| skills/              | SKILL.mdを持つ1スキル1フォルダ |
| agents/              | サブエージェント定義           |
| hooks/hooks.json     | フック設定                |
| .mcp.json            | MCPサーバー定義            |

つまずきやすいのは置き場所です。`.claude-plugin/`の中に入れてよいのはplugin.jsonだけで、skillsフォルダをその中に置くと読み込まれません。`commands/`は旧形式なので、新しく作るなら`skills/`に寄せてください。各部品そのものの書き方は、[Claude Skillsとは？SKILL.mdの書き方](https://www.issoh.co.jp/tech/details/9396/)と[Claude Code Hooksの設定方法｜全33イベント一覧](https://www.issoh.co.jp/tech/details/9864/)で個別に扱っています。`hooks/hooks.json`に`modules`キーを書き、TypeScriptの関数を同梱して動きや画面を変える拡張は[Claude Code Modsとは｜Hooksとの違い・作り方・組織管理の実装](https://www.issoh.co.jp/tech/details/18287/)で解説しました。

### 単体のスキルやフックで足りる場面とプラグイン化へ進む判断基準

スキルもフックもMCPサーバーも、プラグインにしなくても動きます。`~/.claude/skills/`に置いたスキルは、その端末のすべてのプロジェクトで使えます。公式ドキュメントがプラグインを勧めるのは、複数の部品を1単位で配りたいとき、複数プロジェクトへ入れたいとき、版を切って配布したいときの3つです。

見落とされがちなのがコストです。有効なプラグインは、Claudeが自発的に呼べるスキル・エージェント・コマンドの名前と説明を毎ターンのコンテキストに載せます。本文が読み込まれるのは使ったときだけですが、一覧の分は何もしないセッションでも使用量に数えられます。部品が1つしかなく、使う人も自分だけなら、プラグインにする理由はありません。

## 公式マーケットプレイスから入れる手順とスコープ別の書き込み先

自作の前に、入れる側の挙動を押さえておくと配布設計で迷いません。

### セッション内とシェルで異なる導入コマンドの挙動と常駐トークンの測定

公式マーケットプレイス`claude-plugins-official`は、対話型のターミナルセッションを初めて起動したときに自動で登録されます。[インストール手順のドキュメント](https://code.claude.com/docs/en/plugins/install)によると、セッション内の`/plugin install`はすぐには入れず、詳細ペインを開いて中身とスコープを確認させる動きです。シェルからの`claude plugin install`は確認なしで入り、既定はuserスコープです。

```
# 公式マーケットプレイスから入れる（未登録の新しい端末では1行目が要る）
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official

# 入れた後に常駐トークンと部品の内訳を確認する
claude plugin details commit-commands
```

詳細ペインには、公式マーケットプレイスのプラグインに限り「Context cost」として毎ターン分と呼び出し時の2つの推定トークン数が出ます。導入後は`claude plugin details`の`Always-on`行で、そのプラグインが毎セッションに足すトークン数を確認できる仕組みです。`claude -p`などの非対話実行では`/plugin`は使えませんが、導入済みのプラグインは読み込まれます。

### user・project・localの3スコープと同僚の端末に入らない仕様

スコープごとに、`enabledPlugins`を書き込むファイルが変わります。userは`~/.claude/settings.json`、projectはコミットする`.claude/settings.json`、localは`.claude/settings.local.json`です。同じプラグインが複数に書かれていれば、local、project、userの順で勝ちます。

チーム配布で最も多い誤解がprojectスコープです。`.claude/settings.json`をコミットしても、同僚の端末へプラグイン本体はダウンロードされません。公式ドキュメントは、各自が一度`claude plugin install <name>@<marketplace> --scope project`を実行する必要があると明記しています。例外は、マーケットプレイスが相対パスで持っているプラグインで、リポジトリ側の`extraKnownMarketplaces`が適用されればそこから読み込まれます。ただしその適用も、同僚がフォルダのワークスペース信頼を承認した後です。

## 空のディレクトリから自作プラグインを作り手元の1セッションで動かす手順

ここからは作る側です。マーケットプレイスは後回しにし、手元のフォルダで動くところまで進めます。

### plugin.jsonとSKILL.mdの作成と検証コマンドによる動作確認

[プラグイン作成のドキュメント](https://code.claude.com/docs/en/plugins/create)の手順を、そのまま実行できる形にまとめました。`disable-model-invocation: true`は、Claudeが自発的にこのスキルを呼ばず、人が打ったときだけ動かす指定です。

```
mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello

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

# my-first-plugin/skills/hello/SKILL.md
---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.

# 検証して1セッションだけ読み込む
claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin
```

検証が通ると最終行に`✔ Validation passed`が出ます。起動後に`/my-first-plugin:hello`と打てば動作確認は完了です。ファイルを直したら`/reload-plugins`で読み直せます。`--strict`を付けると警告も失敗扱いになるため、CIで回すならこちらを使ってください。v2.1.157以降なら`claude plugin init my-tool`でひな形を作る手もあります。

### 既存の.claude配下をプラグインへ移すときにフックが2回走る落とし穴

すでに`.claude/skills/`や`.claude/agents/`がある場合は、プラグインのルートへコピーするだけで移せます。フックは設定ファイルの`hooks`オブジェクトを`hooks/hooks.json`へ同じ形で移します。

```
# my-plugin/hooks/hooks.json（編集のたびにlintを走らせる例）
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}
```

注意点は、移した後も元のファイルが残っている間の挙動です。スキルとエージェントは接頭辞が付くので`/deploy`と`/my-plugin:deploy`が並ぶだけですが、フックには接頭辞が無く、設定ファイル側とプラグイン側の両方が発火します。lintや通知なら2回走るだけで済みますが、コミットやデプロイを叩くフックなら二重実行になります。動作確認が済んだら、元の`hooks`を必ず消してください。

## marketplace.jsonで社内マーケットプレイスを作りGitHubで配る手順

数人に渡すだけならフォルダやzipで足ります。更新を配り続けるなら、マーケットプレイスを立てます。

### marketplace.jsonの必須3項目と登録名・宣言名を揃える理由

[マーケットプレイス作成のドキュメント](https://code.claude.com/docs/en/plugins/create-marketplace)によると、`.claude-plugin/marketplace.json`の必須項目は`name`、`owner`、`plugins`の3つです。各プラグインのエントリは`name`と`source`を持ちます。

```
# my-marketplace/.claude-plugin/marketplace.json
{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A greeting plugin to learn the basics"
    }
  ]
}

claude plugin validate ./my-marketplace
claude plugin marketplace add ./my-marketplace
claude plugin install my-first-plugin@my-marketplace
```

失敗の大半は2種類です。1つは相対パスの起点で、`source`は`.claude-plugin/`の親、つまりマーケットプレイスのルートから書きます。`..`を含むと検証で弾かれ、存在しないフォルダを指すと検証は通るのにインストール時に出るのは`Source path does not exist`というエラーです。もう1つは名前の食い違いで、エントリの`name`とplugin.jsonの`name`が違うと、後者で入れようとしたときに`not found in marketplace`と出ます。両者は常に揃えてください。

### 相対パス・github・git-subdirの3ソースを置き場所で選ぶ基準

エントリの`source`は、プラグインのファイルがどこにあるかで選びます。表のgit-subdir指定は、`source`に`git-subdir`を指定し、`url`と`path`を記述する形です。

| ソース        | 向く置き方          | 最小の書き方                |
| ---------- | -------------- | --------------------- |
| 相対パス       | マーケットプレイス内     | “./plugins/名前”        |
| github     | プラグインごとに別リポジトリ | source: github, repo  |
| git-subdir | モノレポの一部        | git-subdir指定＋url・path |

立ち上げは相対パス一択です。前節のとおり、projectスコープで配るときに各自のinstallが要らなくなるのは相対パスだけだからです。プラグインごとに開発チームや権限を分けたくなった段階で、githubソースへ切り出してください。ほかに`url`、`archive`、`npm`、`command`の4種類もあります。

### プライベートリポジトリの認証条件とCIのビルド時に行うseed事前投入

プライベートリポジトリも同じ`marketplace add`で登録できます。Claude Codeは端末にある既存のgit認証情報を使い、パスワードは尋ねません。HTTPSなら`gh auth login`などの認証ヘルパーが効き、SSHならホストが`known_hosts`に登録済みでパスフレーズ無しで通る鍵が要ります。

CIやコンテナで毎回クローンさせたくないときは、ビルド時にseedを作ります。GitHub Actionsで別リポジトリのマーケットプレイスを読むなら、既定のワークフロートークンでは届かないため、読み取り権限のあるトークンを`GH_TOKEN`に入れて`gh auth setup-git`を実行してください。

```
# イメージのビルド時にseedへ入れる
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

# 実行時の環境変数（初回の問い合わせ前にインストール完了を待たせる）
CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed
CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1
```

seedは読み取り専用で自動更新も止まります。seed内のプラグインは自動では有効にならないので、`enabledPlugins`に別途書く必要があります。

## managed settingsでプラグインを統制する書き方と効かない範囲

十数人を超えたら、各自の善意に頼らずmanaged settingsで配ります。ユーザー側では上書きできません。

### 全端末へプラグインを強制配布するマーケットプレイス登録と有効化の設定

[組織向けのプラグイン管理ドキュメント](https://code.claude.com/docs/en/plugins/org)が示す基本形は、`extraKnownMarketplaces`でマーケットプレイスを登録し、`enabledPlugins`で入れるプラグインを指名する組み合わせです。下の例は、公式と自社の2つだけを許可し、`--plugin-dir`での持ち込みも禁じる構成です。

```
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true
  },
  "disableSideloadFlags": true
}
```

`enabledPlugins`を`false`にすると、そのプラグインはすべてのスコープで止まり、一覧からも消えます。許可済みマーケットプレイスの中から1本だけ禁じたいときの手段はこれです。配布の反映は、次にセッションを起動したときです。

### 許可リストで入手元を絞るときに起きるskills-dirの停止

`strictKnownMarketplaces`は入手元の許可リストで、空配列`[]`にすると公式マーケットプレイスまで含めて全部止まります。`blockedMarketplaces`は拒否リストで、許可リストより先に判定されます。どちらもマーケットプレイスの入手元を見るもので、`--plugin-dir`は対象外です。持ち込みを止めるには`disableSideloadFlags`を併用します。

事故になりやすいのが、上の例にある`{ "source": "skills-dir" }`の1行です。許可リストを1つでも設定し、この行を書かないと、`~/.claude/skills/`などにplugin.json付きで置いた個人のプラグインが一斉に読み込まれなくなります。manifestを持たない素のSKILL.mdは影響を受けません。また、`/plugin`コマンド自体を隠すキーは存在せず、サーバー管理設定は組織の全員に同じ内容が届くため、部署ごとに変えたいならMDMなど端末側の管理設定を分けることになります。

## 受託開発の現場でプラグイン配布を採用するチームの条件と見送る規模

ここからは判断です。仕組みが揃っていても、入れて得をする体制は限られます。

### 3リポジトリ以上で同じ規約を回すチームで採用する基準と見送る規模

採用してよいのは、同じレビュー観点・同じlintフック・同じ社内ツールのMCP接続を、3つ以上のリポジトリで回している場合です。この規模になると、各リポジトリの`.claude/`を手で揃える手間と、どれが古いか分からない状態のほうが高く付きます。PRレビューを束ねた実在のプラグイン例は[pr-review-toolkitとは｜Claude Codeプラグインの導入とreview-prの使い方](https://www.issoh.co.jp/tech/details/10760/)で確認できます。

見送るのは、1人か2人で1案件を回している段階です。この規模でマーケットプレイスまで立てると、plugin.jsonとmarketplace.jsonの版管理、名前の揃え、キャッシュの更新待ちという運用が増えるだけで、戻りがありません。`.claude/`配下に置いてリポジトリごとコミットし、規約が3リポジトリに広がった時点でプラグインへ移してください。移行手順は前述のとおりコピー中心で済みます。

### フックとMCPがサンドボックス外で動く前提での審査と自動更新

[プラグインのセキュリティ文書](https://code.claude.com/docs/en/plugins/security)は冒頭で、インストールしたプラグインはユーザー権限で任意のコードを実行できると明言しています。フックとMCPサーバーはサンドボックスの外で動き、権限ルールが効くのはClaudeのツール呼び出しだけです。導入前の審査では、`hooks/hooks.json`が何を実行するか、`.mcp.json`の接続先、`bin/`配下のファイルの3点を必ず読んでください。

自動更新は、公式名のマーケットプレイスでは一部を除き既定で有効、自社を含むその他では既定で無効です。有効にすると、審査したファイルが裏で差し替わります。社内マーケットプレイスは自動更新を有効にしてよいですが、外部の第三者マーケットプレイスは無効のまま、コミットやタグで固定して入れる運用を勧めます。誰が何を入れたかは、OpenTelemetryの`claude_code.plugin_installed`と`claude_code.plugin_loaded`で追えます（設定は[Claude CodeのOpenTelemetry設定](https://www.issoh.co.jp/tech/details/17005/)を参照）。規約とツール接続を含めたAIコーディングの開発体制づくりは、[生成AI開発・AI受託開発](https://www.issoh.co.jp/service/ai/development/)でご相談いただけます。

## よくある質問

プラグインの導入と配布で問い合わせの多い5点を、公式ドキュメントの記載に沿って答えます。

### Claude CodeのプラグインとClaude Marketplaceは同じものですか？

両者は名前が似ていますが、指している対象が異なります。`/plugin marketplace add`で登録するマーケットプレイスは、プラグインの一覧と取得先を書いたmarketplace.jsonを持つリポジトリやフォルダです。一方のClaude Marketplaceはclaude.com上のWebサイトで、プラグインやコネクタ、パートナー製品を探す場所です。企業購買の仕組みとしての側面は[Claude Marketplaceの全体像](https://www.issoh.co.jp/tech/details/11298/)で扱っています。

### 入れたプラグインはどのコマンドで無効化や削除ができますか？

セッション内なら`/plugin`のInstalledタブで、Spaceキーで有効と無効を切り替えられます。シェルからは`claude plugin disable`、`claude plugin enable`、`claude plugin uninstall`を使い、`--scope`で対象を指定します。アンインストール後もキャッシュのファイルは14日間ディスクに残るため、すぐに消したい場合は`~/.claude/plugins/cache/`配下のフォルダを手で削除してください。

### プラグインを入れると使用量やコンテキストは増えますか？

増えます。有効なプラグインは、Claudeが自発的に呼べるスキルやエージェントの名前と説明を毎ターンのコンテキストに載せるため、使わないセッションでも使用量に数えられる仕組みです。公式マーケットプレイスのプラグインは導入前にContext costの推定が見られ、導入後は`claude plugin details`の`Always-on`行で確認できます。Installedタブには最近使っていないプラグインの一覧も出ます。

### クラウドのセッションやclaude.ai/codeでもプラグインは使えますか？

手元の設定は引き継がれません。ブラウザのclaude.ai/codeを含むクラウドセッションは、自分の端末で入れたプラグインも、リポジトリの`.claude/settings.json`が有効にしたプラグインも読み込みません。組織として配りたい場合は、claude.aiの管理コンソールから届くサーバー管理設定を使います。ターミナル・デスクトップアプリのローカルセッション・VS Code拡張は同じ設定ファイルを読むため、userスコープで入れれば3つで共通になります。

### おすすめのプラグインはどこで探せばよいですか？

まずは`/plugin`のDiscoverタブで公式マーケットプレイスの一覧を見るのが確実です。中身は[GitHubのclaude-plugins-official](https://github.com/anthropics/claude-plugins-official)で公開されており、Anthropic自身の作例は[claude-codeリポジトリのpluginsフォルダ](https://github.com/anthropics/claude-code/tree/main/plugins)にまとまっています。用途別の選び方は[Claude Codeのおすすめ拡張機能6つを役割別に整理](https://www.issoh.co.jp/tech/details/10463/)で紹介しています。ベンダー公式の実例としては、Googleが1つの中身をClaude Code・Codex・Antigravityへ配る[Google Cloud Developer Pluginの中身と導入手順](https://www.issoh.co.jp/tech/details/18296/)が参考になります。

## 関連記事

- [Claude Codeとは？できること・使い方・料金とコード解析の実力](https://www.issoh.co.jp/tech/details/5571/)：Claude Code本体の機能と料金です
- [Claude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順](https://www.issoh.co.jp/tech/details/17375/)：プラグイン以前の導入と権限設定です
- [Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方](https://www.issoh.co.jp/tech/details/9396/)：プラグインに入れるスキルの書き方です
- [Claude Code Hooksの設定方法｜全33イベント一覧とsettings.jsonの書き方](https://www.issoh.co.jp/tech/details/9864/)：hooks.jsonに書くイベントの一覧です
- [MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説](/tech/details/5736/)：.mcp.jsonで束ねるMCPの規格です

---

出典: [Claude Codeプラグインの作り方と社内配布｜marketplace.json・管理設定【2026年9月版】](<https://www.issoh.co.jp/tech/details/17849/>)（株式会社一創）