Claude Code plugin init/installコマンドの全オプション
claude plugin initとclaude plugin installの引数・オプションを表で網羅し、--withで足せるコンポーネントとスコープの書き込み先まで示します。
Claude Code plugin init/installコマンドの全オプション
claude plugin initはプラグインの雛形を作り、claude plugin installはマーケットプレイスからプラグインを導入します。どちらも非対話的にスクリプトから呼べるよう設計されていて、--withで足すコンポーネントの種類や--scopeの書き込み先まで細かく指定できます。本記事はこの2コマンドの引数・オプションを表で網羅し、周辺のサブコマンドとの使い分けも示します。
claude plugin initでプラグインを雛形化する
claude plugin initは~/.claude/skills/<name>/にプラグインを新規作成します。作った直後から次のセッションで自動的に<name>@skills-dirとして読み込まれ、インストール操作なしで/pluginやclaude plugin listに現れます。
claude plugin init <name> [options]引数: <name>はプラグイン名です。スキルの名前空間と~/.claude/skills/配下のディレクトリ名を兼ねるため、空白やパス区切り文字は使えません。
オプション:
| オプション | 説明 | デフォルト |
|---|---|---|
--description <text> | 説明マニフェストの説明文 | デフォルト— |
--author <name> | 説明作者名 | デフォルトgit config user.name |
--author-email <email> | 説明作者のメールアドレス | デフォルトgit config user.email |
--with <components...> | 説明コンポーネント用のフォルダも追加で雛形化する | デフォルト— |
-f, --force | 説明対象に既存の.claude-plugin/があれば上書きする | デフォルト— |
-h, --help | 説明ヘルプを表示 | デフォルト— |
エイリアスはnewです。
--withで追加できるコンポーネント一覧
--withに渡せる値は7種類あり、それぞれすぐ編集できるスターターファイルを1つ追加します。
| コンポーネント | 追加されるもの |
|---|---|
skills | 追加されるものデフォルトのスキルに加えて名前空間付きの<name>:exampleスキル |
agents | 追加されるものagents/配下のサブエージェント定義 |
hooks | 追加されるものサンプルイベントハンドラ入りのhooks/hooks.json |
mcp | 追加されるものHTTPとstdioのサーバー例を含む.mcp.json |
lsp | 追加されるもの言語サーバー設定の例.lsp.json |
output-style | 追加されるものプラグイン有効時に自動適用されるoutput-styles/<name>.md |
channel | 追加されるものMCPベースのチャンネル一式(server.ts / .mcp.json / package.json) |
# 最小構成で雛形化
claude plugin init my-helper
# skillとhookのフォルダも足す
claude plugin init my-helper --with skills hooks
# 既存の雛形を上書き
claude plugin init my-helper --forceplugin initが管理者にブロックされる条件
雛形化されたプラグインは@skills-dirソースを使い、マーケットプレイス経由ではありません。管理者はstrictKnownMarketplacesか、managed settingsのblockedMarketplacesに{"source": "skills-dir"}を追加することでこのソースをブロックできます。ブロックされている環境ではplugin initは書き込みを行う前に失敗します。組織でプラグインのソースを絞り込んでいるチームは、雛形化コマンドが使えるかどうかもこの設定に左右されることを覚えておく必要があります。
plugin initが作るプラグインはどう読み込まれるか
plugin initが書き込む~/.claude/skills/<name>/は個人スコープのスキルディレクトリで、マーケットプレイスもインストール記録も経由しません。プロジェクト側の<cwd>/.claude/skills/に同じ構造の.claude-plugin/plugin.jsonを置いた場合は、挙動が個人スコープとは大きく異なります。
| スキルディレクトリ | スコープ | 読み込まれる条件 |
|---|---|---|
~/.claude/skills/ | スコープ個人 | 読み込まれる条件場所が自分専用のため、どのプロジェクトでも読み込まれる |
<cwd>/.claude/skills/ | スコーププロジェクト | 読み込まれる条件そのフォルダの信頼ダイアログを承認したあとにのみ読み込まれる |
プロジェクトスコープの@skills-dirプラグインには、通常のスキル探索とは違うもう一つの制約があります。読み込まれるのはセッションの主作業ディレクトリ直下の.claude/skills/だけで、通常のスキルのようにリポジトリルートへ遡って探しにいくことはありません。そのためサブディレクトリでセッションを起動すると、リポジトリルート直下に置いたプロジェクトスコープのプラグインを読み落とします。v2.1.246以降は/cdでセッションの作業ディレクトリを移せるため、ルートへ移動してから読み込ませることができます。
プロジェクトスコープのスキルディレクトリ由来プラグインのスコープ表・信頼ゲート・MCP/LSP/Monitorの制限・変更反映のタイミングや無効化の手順は、Claude Code skills-directoryでプラグインをそのまま動かす手順で扱っています。init直後に効く差分は、変更の反映タイミングが個人スコープと変わらない点です。スキルのSKILL.mdを編集した変更は現在のセッションに即座に反映されますが、hooks/ .mcp.json agents/ output-styles/などほかのコンポーネントへの変更は/reload-pluginsの実行かセッション再起動まで反映されません。マーケットプレイス経由のインストールと違いuninstallという手順は無く、フォルダを削除するか名前で無効化して止めます。
claude plugin disable my-tool@skills-dirclaude plugin installでマーケットプレイスから導入する
claude plugin installは登録済みのマーケットプレイスからプラグインをインストールします。
claude plugin install <plugin> [options]引数: <plugin>はプラグイン名、または特定のマーケットプレイスを指定するplugin-name@marketplace-name形式です。
オプション:
| オプション | 説明 | デフォルト |
|---|---|---|
-s, --scope <scope> | 説明インストール先スコープ: user project local | デフォルトuser |
--config <key=value> | 説明マニフェストが宣言するuserConfigオプションを設定。複数回指定で複数値を設定できる | デフォルト— |
-y, --yes | 説明マーケットプレイスが宣言する確認プロンプトを省略する(下記参照) | デフォルト— |
-h, --help | 説明ヘルプを表示 | デフォルト— |
# userスコープにインストール(デフォルト)
claude plugin install formatter@my-marketplace
# projectスコープにインストール(チームで共有)
claude plugin install formatter@my-marketplace --scope project
# localスコープにインストール(チームには共有しない)
claude plugin install formatter@my-marketplace --scope localスコープはどの設定ファイルに書き込まれるか
--scopeはどの設定ファイルのenabledPluginsにプラグインを追加するかを決めます。installが受け付けるのはuser project localの3つですが、スコープ自体はmanagedを含めて4種類あります。
| スコープ | 書き込み先 | 用途 |
|---|---|---|
user | 書き込み先~/.claude/settings.json | 用途全プロジェクト共通の個人用プラグイン(デフォルト) |
project | 書き込み先.claude/settings.json | 用途バージョン管理経由でチームに共有するプラグイン |
local | 書き込み先.claude/settings.local.json | 用途プロジェクト固有だがgit管理には含めないプラグイン |
managed | 書き込み先managed settings | 用途管理者が配布する読み取り専用のプラグイン(更新のみ可能) |
--scope projectは.claude/settings.jsonのenabledPluginsに書き込むため、そのプロジェクトのリポジトリをクローンした全員が同じプラグインを使える状態になります。逆に--scope localはチームに共有されないファイルに書き込まれるため、個人の実験目的で使う設定に向きます。この書き込み先の区別はinstallだけでなく、uninstall enable disable update pruneの各コマンドでも共通していて、updateだけは読み取り専用のmanagedスコープも指定対象に含みます。
--configでuserConfigの値を渡す
プラグインがuserConfigを宣言している場合、対話プロンプトを待たずに--config key=valueで値を渡せます。フラグは繰り返し指定でき、複数のオプションを一度に埋められます。
-y/--yesが必須になる場面
-yが省略可能なのは対話端末で実行しているときだけです。標準入力または標準出力がTTYでない場合、-yを付けない限りinstallとupdateは先に進みません。-yが省略を許可する対象は次の2つです。
commandソースを持つマーケットプレイスエントリが、プラグインを生成するために実行するコマンド- アーカイブダウンロードを認証する
headersHelper(受け入れにはClaude Code v2.1.238以降が必要)
-yを付けても、実行されるコマンド自体は先に画面へ表示されます。またこのフラグはClaude Codeセッション内では効果を持たず、自分のターミナルから直接コマンドを実行する必要があります。CI・コンテナのプロビジョニングスクリプトなど非対話環境でプラグインを自動インストールする場合は、-yを付け忘れるとスクリプトがそこで止まる点に注意してください。
init/installでよくあるつまずき
claude plugin initやclaude plugin installのあとにプラグインが正しく動かないときは、まずclaude --debugで読み込みログを確認します。どのプラグインが読み込まれているか、マニフェストのエラー、スキル・エージェント・フックの登録状況、MCPサーバーの初期化までが表示されます。
| 症状 | 原因 | 対処 |
|---|---|---|
| プラグインが読み込まれない | 原因plugin.jsonが不正 | 対処claude plugin validate ./my-pluginでシンタックス・スキーマエラーを確認する |
| スキルが表示されない | 原因ディレクトリ構造が間違っている | 対処skills/やcommands/が.claude-plugin/の中ではなくプラグインのルート直下にあるか確認する |
| フックが発火しない | 原因スクリプトに実行権限がない | 対処chmod +x script.shを実行する |
| MCPサーバーが失敗する | 原因${CLAUDE_PLUGIN_ROOT}を使っていない | 対処プラグインが持つパスはすべてこの変数経由で参照する |
| パスエラーが出る | 原因絶対パスを使っている | 対処./から始まる相対パスに直す(skillsだけは"."も許可) |
installで特に遭遇しやすいのは次の2つのエラーです。
Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.:marketplace.jsonのsourceが指すディレクトリが実在しないときに出ます。マーケットプレイス側の設定ミスなので、インストール元のマーケットプレイス管理者に修正を依頼しますPlugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.:plugin.jsonとマーケットプレイスエントリの両方がコンポーネントを定義しているときに出ます。どちらか一方の定義を削除するか、マーケットプレイスエントリのstrict: falseを外します
init直後によく踏むのは、雛形化されたディレクトリ構造をそのまま.claude-plugin/の中へ移動させてしまうミスです。コンポーネント用のフォルダはプラグインのルート直下に置き、.claude-plugin/配下に置くのはplugin.jsonだけにします。
init/install以外の主要サブコマンド早見表
pluginサブコマンド群は導入だけでなく、削除・有効化・更新・検査までを一通りカバーしています。それぞれの役割を把握しておくと、initとinstallをどこで使い分けるべきかが見えやすくなります。
| コマンド | 用途 | 主なオプション |
|---|---|---|
plugin uninstall | 用途インストール済みプラグインを削除(エイリアスremove rm) | 主なオプション--scope --keep-data --prune |
plugin prune | 用途使われなくなった自動インストール依存を掃除(エイリアスautoremove) | 主なオプション--scope --dry-run |
plugin enable / plugin disable | 用途アンインストールせずに無効化/再有効化 | 主なオプション--scope -a, --all(disableのみ) |
plugin update | 用途最新版へ更新 | 主なオプション--scope(managedも指定可) -y |
plugin list | 用途インストール済み一覧をバージョン・マーケットプレイス・状態付きで表示 | 主なオプション--json --available |
plugin details <name> | 用途コンポーネント構成とトークンコストの見積もりを表示 | 主なオプション— |
plugin validate <path> | 用途公開前にスキーマとシンタックスを検証 | 主なオプション--strict --json |
plugin tag [path] | 用途バージョン解決用のgitタグを打つ | 主なオプション--push --dry-run |
plugin installは「マーケットプレイスにある既存のプラグインを導入する」コマンドで、plugin initは「自分のマシンにゼロから新しいプラグインを作る」コマンドです。両者は導入元が違うだけでなく、書き込み先もenabledPlugins(install)と~/.claude/skills/(init)で完全に分かれています。
同名プラグインが複数マーケットプレイスにある場合の注意
installはplugin-name@marketplace-name形式でマーケットプレイスを明示できますが、ベア名(マーケットプレイス指定なし)でupdateやuninstallを実行したときの解決先は、対象がインストール済みかどうかで挙動が変わります。異なるマーケットプレイスから同名のプラグインをインストール済みの場合、Claude Codeはupdateを拒否し、実行すべきplugin-name@marketplace-name形式のコマンドを一覧します(Claude Code v2.1.246より前はベア名自体が「見つからない」エラーで拒否されていました)。同様にuninstallの完全修飾形は、指定したマーケットプレイスのプラグインだけを対象にします(v2.1.212より前は同名の別マーケットプレイス側まで誤って削除される場合がありました)。複数のマーケットプレイスを併用するチームでは、install時点から完全修飾形を使う習慣にしておくと、あとのupdateやuninstallでも迷いません。
インストール後にplugin listとplugin detailsで確認する
installが成功したかどうかはclaude plugin listで確認します。--jsonでJSON出力、--available(--jsonと併用が必須)でマーケットプレイス上のまだ未インストールなプラグインまで含められます。セッション内で使う/plugin listはこれと似ていますが対象範囲が異なり、マーケットプレイスからインストールしたプラグインしか一覧しません。スキルディレクトリ由来のプラグインは/pluginインターフェースとclaude plugin listには現れますが、/plugin listのインライン出力には現れません。--plugin-dirで読み込んだセッション限定のプラグインも同様で、claude --plugin-dir <dir> plugin listのようにフラグを同じコマンドラインに付けたときだけ拾われます。
インストールしたプラグインがセッションにどれだけの負荷をかけるかはclaude plugin details <name>で見積もれます。常時トークンを消費する「Always-on」コスト(スキル説明・エージェント説明・コマンド名など、そのプラグインの一覧テキストが毎セッション占める分)と、発火したときだけ消費する「On-invoke」コストをコンポーネントごとに分けて表示します。
dependency-guard 1.2.0
Dependency analysis for Claude Code sessions
Source: dependency-guard@example-marketplace
Component inventory
Skills (2) scan-dependencies, review-changes
Hooks (1) SessionStart (harness-only — no model context cost)
Projected token cost
Always-on: ~180 tok added to every sessionトークンコストの見積もりはアクティブなモデルのcount_tokens APIで計算され、APIに到達できない場合は文字数ベースの概算にフォールバックします。複数のプラグインをインストールしたあと、常時消費するトークンが想定より大きくなっていないかを確認する用途に向きます。
まとめ
claude plugin initは~/.claude/skills/への雛形作成で、--withが足すコンポーネントの種類とスコープの概念を持たない点がinstallとの最大の違いです。claude plugin installは--scopeでどの設定ファイルに書き込むかを、--configでuserConfigの値を、-yで非対話環境の確認プロンプトをそれぞれ制御します。プラグインの作り方全体はClaude Codeプラグイン完全ガイド、再起動なしで変更を反映する運用は/reload-pluginsで再起動なしにプラグインを反映するを参照してください。