【2026年9月】Claude Codeプラグイン完全ガイド｜使い方と企業配布

正直に言うと、私が複数のクライアント案件で Claude Code を回し始めて最初にぶつかったのが「設定の使い回し問題」でした。あるプロジェクトで作った /deploy スキルや PostToolUse の lint フックを別リポジトリにも入れたい。けれど .claude/commands/ や settings.json をコピペすると版がズレて「あっちでは動くのにこっちでは動かない」が必ず起きる。100社以上の現場を見てきましたが、規模を問わず発生します。

この記事は2026年6月の初版を、9月2日公開の v2.1.259 までの公式 changelogと、Create plugins / Plugins reference / plugin marketplace の現行ドキュメントで照合し直したものです。skills-dir 自動読み込み（5/29・v2.1.157）、archive ソース（8/7・v2.1.224）、command ソース（8/12・v2.1.229）、headersHelper（8/20・v2.1.238）、validate --json（9/2・v2.1.259）と更新が続き、6月の手順のままだと遠回りになる箇所がいくつもあります。

プラグインとは何か — 2026年9月時点で束ねられるもの

Claude Code のプラグインは、独立したディレクトリに各種コンポーネントを置き、必要に応じて .claude-plugin/plugin.json で「名前・説明・バージョン」を宣言したものです。マニフェストは省略可能で、省略するとディレクトリ名がプラグイン名になります。プラグイン経由のスキルは /plugin-name:skill-name と名前空間付きで呼ばれ、同名スキルが衝突しません。ルート直下に置けるものは次のとおりです（初版から output-styles/ workflows/ themes/ が増えました）。

ディレクトリ / ファイル	役割
.claude-plugin/plugin.json	マニフェスト（任意）。これだけは .claude-plugin/ 内に置く
skills/	<name>/SKILL.md 形式。新規の推奨。スキル1つだけならルート直下の SKILL.md でも可
commands/	フラットな Markdown のスキル。互換用
agents/	サブエージェント。hooks / mcpServers / permissionMode は安全上サポート外
hooks/hooks.json	イベントハンドラ（settings.json の hooks と同形式）
.mcp.json / .lsp.json	MCP サーバー / LSP サーバー設定
monitors/monitors.json	バックグラウンド監視（experimental・対話セッションのみ）
themes/ / output-styles/ / workflows/	配色テーマ（experimental）/ 出力スタイル / ワークフロー
bin/	有効時に Bash ツールの PATH へ追加。claude.ai の組織設定から配る場合は置けない
settings.json	有効時の既定設定。対応キーは agent と subagentStatusLine だけ

最大のハマりどころは変わっていません。commands/ agents/ skills/ hooks/ を .claude-plugin/ の中に入れない。公式が Warning に追記したとおり、プラグインルートは ~/.claude/ ではないので ~/.claude/.mcp.json を置いても読まれません。ルートの CLAUDE.md もコンテキストにならず、claude plugin validate が警告します。指示を配りたいなら skill にします。

マニフェストの最小形は次のとおり。必須は name だけ。version を書くとその文字列を変えたときだけ更新が届き、省略すると git のコミット SHA（archive ソースなら SHA-256 ダイジェスト）が版になります。

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

サブエージェントを束ねるならサブエージェントの並列実行の解説、MCP サーバーを同梱するならClaude Code MCP実践ガイド｜設定から自作までも合わせて読むと、各コンポーネント単体の作法が掴めます。

最短で試す — claude plugin init と –plugin-dir

初版では「mkdir して plugin.json を書いて --plugin-dir で起動」が入口でしたが、v2.1.157（2026年5月29日）以降は claude plugin init が雛形を作ります。

# ~/.claude/skills/my-tool/ に plugin.json と SKILL.md を生成
claude plugin init my-tool

# フックと MCP の雛形も一緒に
claude plugin init my-tool --with hooks mcp

これで作ったプラグインは次のセッションから my-tool@skills-dir として自動で読み込まれ、登録もインストールも不要です。~/.claude/skills/ なら全プロジェクト、<cwd>/.claude/skills/ ならそのフォルダを trust した後だけ読まれ、プロジェクト側は MCP がサーバーごとの承認を要求し、monitors は読まれません。プロジェクト側はプライマリ作業ディレクトリしか見ないので、サブディレクトリから起動するとルートのプラグインを取りこぼします（v2.1.246 以降は /cd で移動可）。SKILL.md は即時反映、hooks/ .mcp.json agents/ は /reload-plugins で反映。止めるときは claude plugin disable my-tool@skills-dir。

マーケットプレイス配布を前提に別の場所で開発するなら従来どおり claude --plugin-dir ./my-plugin（複数指定可）。v2.1.129（5月6日）からは .zip と、CI 成果物などの URL をそのセッションだけ読む --plugin-url も使えます。インストール済みの同名プラグインより --plugin-dir 側が優先されるので、消さずに変更を試せます。キャッシュを無効化する変更は /reload-plugins --force で適用します。

マーケットプレイスからインストールする — /plugin と claude plugin

導入は「①マーケットプレイス（カタログ）を追加 → ②個別プラグインをインストール」の2段階。変わったのは反映のタイミングとカタログ更新の自動化です。

1. 公式マーケットプレイス claude-plugins-official は初回の対話起動で自動登録される。無ければ /plugin marketplace add anthropics/claude-plugins-official
2. /plugin で Discover / Installed / Marketplaces / Errors の4タブを Tab で切り替える。Discover では Context cost（毎ターンのトークン目安）・Last updated・Will install（追加される部品一覧）を入れる前に確認できる
3. コマンドなら /plugin install github@claude-plugins-official。スコープは user（既定）/ project（.claude/settings.json）/ local
4. v2.1.221（8月4日）以降、/plugin からのインストールは安全なら即時有効化。サマリが Run /reload-plugins to activate. のときだけ手動反映
5. v2.1.232（8月13日）以降、/plugin install name@marketplace は先にそのマーケットプレイスを更新してから探す

追加元は GitHub の owner/repo、git URL、ローカルパス、marketplace.json の直接 URL。初版で「非 GitHub の git ホストは .git を付ける」と書きましたが、v2.1.232 で gitlab.com はサフィックスなしでもクローン扱いになりました。それ以外のホスト（セルフホスト GitLab 含む）は引き続き .git が必要、Azure DevOps は逆に付けると失敗します。

# GitHub / GitLab（.git 省略可）
/plugin marketplace add anthropics/claude-code
/plugin marketplace add https://gitlab.com/group/subgroup/project

# その他の git ホスト（.git 必須・# で ref 指定）
/plugin marketplace add https://git.example.com/company/plugins.git#v1.0.0

# コミュニティマーケットプレイス（審査済みサードパーティ・手動追加）
/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-community

管理系はセッション内の /plugin disable 等がパネルを開いたままにするので、スクリプトからは claude plugin のシェルコマンドを使うのが公式の推奨です。

/plugin list --enabled                                          # v2.1.163〜
claude plugin details commit-commands@claude-plugins-official   # v2.1.139〜
claude plugin uninstall plugin-name@marketplace-name --scope project
claude plugin update plugin-name                                # v2.1.246〜 bare name 可

claude plugin details は常時コンテキストに乗る Always-on と発火時の On-invoke のトークンを部品ごとに出し、Installed タブは「2週間以上・10セッション以上未使用」を Not used recently として並べます。起動コストだけ払っている拡張の棚卸しに使えます。切り分けには v2.1.169（6月8日）の claude --safe-mode（全カスタマイズ無効で起動）が便利です。

marketplace.json を書く — 7種のソースと検証

配る側は、リポジトリルートに .claude-plugin/marketplace.json を置きます。必須は name（kebab-case・公開名）・owner.name・plugins。claude-plugins-official や anthropic-plugins など公式を装う名前は予約済みで使えません。

{
  "name": "company-tools",
  "owner": { "name": "DevTools Team", "email": "[email protected]" },
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    { "name": "code-formatter", "source": "formatter", "description": "Automatic code formatting on save", "version": "2.1.0" },
    { "name": "deploy-tools", "source": { "source": "github", "repo": "company/deploy-plugin", "ref": "v2.0.0" } },
    { "name": "internal-zip", "source": { "source": "archive", "url": "https://artifacts.example.com/claude-plugins/internal-2.1.0.zip", "sha256": "6bfa50e3...cca5e1" } }
  ],
  "renames": { "formatter": "code-formatter", "legacy-linter": null }
}

ソース	主なフィールド	要点
相対パス	"./plugins/x"	同一リポ内。metadata.pluginRoot（v2.1.239〜）でベア名可。URL 配信では解決不可
github / url	repo or url, ref?, sha?	sha を書けば ref が消えても固定コミットを取得
git-subdir	url, path, ref?, sha?	monorepo のサブディレクトリを sparse clone
npm	package, version?, registry?	版は unknown になるので version を明示
archive（v2.1.224〜）	url（https のみ）, sha256?	git も npm も無い端末に zip で配布。256 MiB 上限。不一致は拒否
command（v2.1.229〜）	command, timeout?, mode?	ローカルコマンドの出力ディレクトリを取り込み、セッションごとに再実行

初版から一番変わったのが認証付き配布です。社内サーバーの zip を配るとき、固定ヘッダーなら headers、短命トークンなら v2.1.238（8月20日）の headersHelper をエントリに置きます（詳細はheadersHelper 認証の解説）。エントリ側に置くなら "strict": false が必須で、利用者がインストール時に表示されたコマンドを承認して初めて実行されます。コマンドは 500 文字以内の printable ASCII、10秒以内にヘッダーの JSON オブジェクトを stdout に出して exit 0。環境からは TOKEN / SECRET / KEY / AUTH を含む変数が取り除かれます。

公開前の検証は claude plugin validate。マーケットプレイスディレクトリに対して実行すると JSON 構文・名前重複・パストラバーサル・各 plugin.json との版整合を見ます。v2.1.259（9月2日）で --json が増え、CI で機械判定しやすくなりました。

claude plugin validate ./my-plugin --strict   # 警告も失敗扱い
claude plugin validate . --json                # exit 0=PASS / 1=FAIL / 2=実行失敗
claude plugin validate .claude/skills          # マニフェスト無しの frontmatter 検査（v2.1.233〜）

チームに配る・企業で統制する — settings.json と managed settings

ここがプラグインの真価です。プロジェクトの .claude/settings.json に extraKnownMarketplaces を書くと、メンバーがそのフォルダを trust した時点でマーケットプレイスが登録されます。enabledPlugins を併記すれば既定で有効にするプラグインまで指定できます。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

• 外部ソースのプラグインは登録だけでは入らない（v2.1.195〜）。github や npm ソースは各メンバーが claude plugin install を叩くまで「未インストール」表示。相対パスのプラグインは登録と同時に使える
• キーの別名：v2.1.232 から additionalMarketplaces / allowedMarketplaces が通る。旧バージョンは無視するので混在環境は正式名で書く
• 自動更新は起動後に最大10分の遅延で走り、更新があれば /reload-plugins を促す。公式は既定 ON、サードパーティは既定 OFF。DISABLE_AUTOUPDATER=1 と FORCE_AUTOUPDATE_PLUGINS=1 の併用で本体は止めてプラグインだけ更新できる

非公開リポジトリは初版の「GITHUB_TOKEN があれば背景更新が通る」を訂正します。手動コマンドは git の credential helper や ssh-agent をそのまま使う一方、背景の自動更新は HTTPS の credential helper を無効にして git pull するため、環境変数のトークン単体では効きません。gh auth setup-git で helper を設定するか、次の URL 書き換えでトークンを埋め込みます。失敗時に既存クローンを消したくなければ CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 です。

git config --global url."https://x-access-token:[email protected]/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

Team / Enterprise プランでは claude.ai の Organization settings > Plugins から配る経路もあります。マーケットプレイスリポジトリが private / internal、ソースが github / url / git-subdir / ./ 始まりの相対パス、そしてトップレベル bin/ を持つプラグインは拒否が条件です。実行ファイルは scripts/ に置き ${CLAUDE_PLUGIN_ROOT}/scripts/<name> で参照します。CI やコンテナでは、ビルド時に CLAUDE_CODE_PLUGIN_CACHE_DIR へインストールし、実行時に CLAUDE_CODE_PLUGIN_SEED_DIR で読み取り専用シードとして渡せば、起動時のクローンなしで同じ一式が立ち上がります。

「誰が何を追加できるか」は managed settings（管理設定）で決めます。初版の strictKnownMarketplaces に加え、現在は次のように重ねられます。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "acme-corp/*" },
    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" },
    { "source": "skills-dir" }
  ],
  "blockedMarketplaces": [ { "source": "github", "repo": "untrusted-org/*" } ],
  "strictPluginOnlyCustomization": ["skills", "hooks", "mcp"],
  "disableCommandPluginSources": true,
  "pluginTrustMessage": "All plugins from our marketplace are approved by IT"
}

• strictKnownMarketplaces：空配列 [] で公式含め全面ロックダウン、配列で許可リスト。v2.1.223（8月6日）から owner/* の所有者ワイルドカード、hostPattern（社内 GitHub Enterprise / GitLab 向け）、pathPattern が使える。許可リストを置くと skills-dir プラグインも止まるので、残すなら { "source": "skills-dir" } を足す
• blockedMarketplaces：追加時だけでなく install / update / auto-update の前にも照合され、ポリシー前に追加済みのものも止まる
• strictPluginOnlyCustomization：skills / agents / hooks / mcp をユーザー・プロジェクト設定から読まなくし、プラグインと managed settings 経由だけに絞る。true で4つ全部ロック
• disableCommandPluginSources：command ソースと headersHelper を止める。allowManagedHooksOnly 設定済みの組織は未設定でも止まる
• pluginSuggestionMarketplaces（v2.1.152〜）：エントリの relevance（cwd / cli / filesRead / manifestDeps）に基づく「このディレクトリでおすすめ」表示を許可する

strictKnownMarketplaces は「追加を制限する」だけで登録はしないので、社内マーケットプレイスを全員に自動登録したいときは同じファイルの extraKnownMarketplaces に併記します。公式マーケットプレイスの自動登録も初回の対話起動でしか走らないため、非対話環境やロックダウン後に緩めた端末はここに入れておくのが確実です。

依存関係・バージョン・設定値 — 壊れない配布のための3点

バージョンは更新検知のキャッシュキーです。解決順は「plugin.json の version → マーケットプレイスエントリの version → git コミット SHA → archive の SHA-256（先頭12桁）→ unknown」。command ソースだけは常に出力内容のハッシュが版です。明示バージョンを据え置いたまま push しても届かない、という初版の注意はそのまま有効です。

依存関係は dependencies に semver 範囲付きで書け（例：{ "name": "secrets-vault", "version": "~2.1.0" }）、v2.1.143（5月15日）から強制されます。範囲解決は依存先リポジトリの {plugin-name}--v{version} 形式の git タグに対して行われ、タグは claude plugin tag --push がマニフェストとの整合を検証してから作ります。別マーケットプレイスを指すにはルート側の allowCrossMarketplaceDependenciesOn が必要。claude plugin disable は依存されていると拒否され、enable は依存先をまとめて有効化、孤立した依存は claude plugin prune で掃除。依存だけ列挙した plugin.json なら「バックエンド標準セット」のようなバンドル配布もできます。

設定値は userConfig で有効化時に利用者へプロンプトします。sensitive: true の値は macOS Keychain（不可なら ~/.claude/.credentials.json）、非機密値は user settings の pluginConfigs に保存。v2.1.207 からの変更が2つ。①シェル形式の hook・monitor・headersHelper では ${user_config.KEY} の展開が拒否される（シェルインジェクション対策）。hook は exec 形式（args 配列）か環境変数 CLAUDE_PLUGIN_OPTION_<KEY> で受け取る。②pluginConfigs はプロジェクトの .claude/settings.json / settings.local.json から読まれない（クローンしたリポジトリが値を注入できないようにするため）。

パス変数は ${CLAUDE_PLUGIN_ROOT}（更新で変わる）、${CLAUDE_PLUGIN_DATA}（~/.claude/plugins/data/<id>/・更新をまたいで残る）、${CLAUDE_PROJECT_DIR} の3つ。package-lock.json か bun.lock を同梱した npm 依存はキャッシュ時に npm ci --ignore-scripts（60秒上限）で自動インストールされ、ライフサイクルスクリプトは走りません。Python の venv や Yarn / pnpm の依存は ${CLAUDE_PLUGIN_DATA} に SessionStart フックで入れます。

コードインテリジェンス系プラグインなどの実用例

「実際どれを入れると効くのか」。私が現場でまず勧めるのはコードインテリジェンス（LSP）系です。編集直後に言語サーバーが型エラー・未解決インポートを返し、Claude が同じターンで直します。公式マーケットプレイス収録の LSP プラグインは初版の6言語から11言語に増えました。バイナリは別途インストールが必要で、クラウドセッションでは言語サーバーが起動しません。

言語	プラグイン	必要バイナリ
C/C++	clangd-lsp	clangd
C#	csharp-lsp	csharp-ls
Go	gopls-lsp	gopls
Java	jdtls-lsp	jdtls
Kotlin	kotlin-lsp	kotlin-language-server
Lua	lua-lsp	lua-language-server
PHP	php-lsp	intelephense
Python	pyright-lsp	pyright-langserver
Rust	rust-analyzer-lsp	rust-analyzer
Swift	swift-lsp	sourcekit-lsp
TypeScript	typescript-lsp	typescript-language-server

LSP 以外の公式カテゴリは、MCP 同梱の外部連携（github / gitlab / atlassian / linear / notion / figma / supabase / slack / sentry など）、各変更を脆弱性観点でレビューして同セッション内で直させる security-guidance、開発ワークフローの commit-commands / pr-review-toolkit / plugin-dev です。フックで format / test / 通知を自動化したい場合は、Claude Code の hooks 自動化の解説も参照してください。プラグインなら、その hooks 設定ごとチームに配れます。

よくある失敗パターン

• ❌ commands/ や skills/ を .claude-plugin/ の中に入れる → ⭕ .claude-plugin/ に置くのは plugin.json だけ。~/.claude/ をプラグインルート扱いしない
• ❌ plugin.json の "version": "1.0.0" を据え置いたまま新コミットを push → ⭕ 利用者には届かない。リリースごとに上げるか、省略してコミット SHA を版にする。エントリと両方に書くと plugin.json が黙って勝つ
• ❌ GITHUB_TOKEN を環境変数に置いて非公開マーケットプレイスの自動更新が通ると思う → ⭕ 背景更新は credential helper 無効で pull する。gh auth setup-git か URL 書き換えでトークンを渡す
• ❌ hook コマンドに ${user_config.api_endpoint} を直接埋め込む → ⭕ v2.1.207 以降は拒否される。exec 形式の args か CLAUDE_PLUGIN_OPTION_API_ENDPOINT で受ける
• ❌ URL 配信の marketplace.json で相対パスの source を使う → ⭕ URL 方式は marketplace.json 本体しか落とさない。同一ホストの archive か GitHub / git ソースにする

FAQ

Q. プラグインとスタンドアロン設定、どちらを使うべき？
個人・実験段階なら .claude/、共有・版管理が要るタイミングでプラグインに切り出す二段構えが公式推奨です。claude plugin init なら最初からプラグインにしても手間は変わらないので、私は「他人に渡す可能性が1割でもあるならプラグイン」で決めています。

Q. 入れた直後の設定変更は即反映される？
v2.1.221 以降、/plugin からのインストールは安全なら即時有効化されます。サマリが Run /reload-plugins to activate. のときだけ /reload-plugins、キャッシュ無効化の警告が出たら --force。シェルの claude plugin install は次回起動か /reload-plugins で読まれます。

Q. 自作プラグインを公式マーケットプレイスに載せられる？
公式 claude-plugins-official は Anthropic の裁量で選定され、申請窓口はありません。サードパーティはコミュニティマーケットプレイス anthropics/claude-plugins-community が受け皿で、claude.ai（Team / Enterprise の管理者）または Console の提出フォームから審査に出します。承認されるとコミット SHA 固定でカタログに載ります。

Q. claude plugin eval というコマンドはある？
2026年9月時点の公式 Plugins reference の CLI 一覧（init / install / uninstall / prune / enable / disable / update / list / details / validate / tag）と changelog には eval サブコマンドの記載がなく、公式に確認できていません。検索で見つかる「plugin eval」はサードパーティ製の評価プラグインです。品質検査の公式ルートは現状 validate --strict と details のトークンコスト確認です。

Q. 安全性は？
プラグインはユーザー権限で任意のコードを実行しうる「高信頼コンポーネント」で、Anthropic は第三者プラグインの中身を検証していません。信頼できるソースだけ追加し、組織は strictKnownMarketplaces と strictPluginOnlyCustomization で供給経路を固定してください。

出典

いずれも2026年9月3日に確認。

• Claude Code 公式ドキュメント「Create plugins」
• Claude Code 公式ドキュメント「Create and distribute a plugin marketplace」
• Claude Code 公式ドキュメント「Discover and install prebuilt plugins」
• Claude Code 公式ドキュメント「Plugins reference」
• Claude Code 公式ドキュメント「Constrain plugin dependency versions」
• Claude Code 公式ドキュメント「Settings reference」Plugins and skills 節
• Claude Code changelog（v2.1.129〜v2.1.259・2026年5月6日〜9月2日）

---

著者：佐藤傑（さとう・すぐる）　株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆。

関連記事（Claude Code 実践ガイド）

• まとめ：Claude Code 実践テクニック完全ガイド（12スキル）
• カスタムスラッシュコマンド作成ガイド
• Plan Mode実践ガイド｜安全に大きな変更を進める
• ヘッドレス自動実行ガイド｜-p・SDK・CI
• Skills作成ガイド｜SKILL.md入門

あわせて読みたい

• ▸ 【2026年9月】Claude Code×Figma MCP接続の実装手順
• ▸ 【2026年9月】Claude CodeにGit操作を任せる7手順
• ▸ 【2026年9月】Claude Codeトークン使用量の確認｜キャッシュ節約
• ▸ 【2026年9月】Claude Code研修・講師の依頼先6社比較と選び方
• ▸ 【2026年最新】Claude Code /compact｜長時間開発の5手順