claude plugin detailsでプラグインのコンテキスト消費を測る
claude plugin detailsはプラグインが毎セッション足すトークンを見積もります。Always-onとon-invokeの読み方、下げ方、/pluginのContext costが出る条件をまとめます。
claude plugin details <name> は、プラグインがセッションに足すコンテキストの量を見積もるコマンドです。プラグインを有効にしたセッションでは、スキル・エージェント・コマンドの名前と説明が毎回Claudeのコンテキストに入ります。使われなくても、そのトークンは利用量に数えられます。この記事では出力の読み方、数字の下げ方、/plugin に出るContext costとの違いを扱います。
claude plugin detailsはシェルで実行する
このコマンドはClaude Codeのプロンプトではなく、シェルで実行します。対象のプラグインは読み込まれている必要があります。条件は次のいずれかです。
- インストール済み
- スキルディレクトリにある
- 同じコマンドで
--plugin-dirか--plugin-urlを渡している
<name> は name でも name@marketplace でも指定できます。オプションは --help だけです。
# インストール済みのプラグインを測る
claude plugin details formatter
# ディスク上の未インストールのプラグインを測る
claude --plugin-dir ./formatter plugin details formatter読み込まれていない名前を渡すと失敗します。空の設定ディレクトリでv2.1.296を動かしたところ、次のメッセージが出て終了コードは1でした。
Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.CIで測るなら、終了コードが1のとき「測れなかった」のか「プラグインが無い」のかを切り分けます。名前の確認にはclaude plugin list --jsonの棚卸しが使えます。
出力は3つのブロックでできている
measureページの例は、スキル3つ・エージェント1つ・フック1つ・MCPサーバー1つを持つ formatter プラグインです。出力は次の形になります(例示であり、実環境の数字ではありません)。
Component inventory
Skills (3) format-all, format-code, lint-fix
Agents (1) style-reviewer
Hooks (1) PostToolUse (harness-only — no model context cost)
MCP servers (1) formatter-tools (tool schemas resolved at runtime; not counted)
LSP servers (0)
Projected token cost
Always-on: ~146 tok added to every session
Per-component (rounded)
component always-on on-invoke
format-code ~40 ~30
lint-fix ~50 ~30
style-reviewer ~40 ~40
format-all < 20 ~30ブロックごとに答える問いが違います。
| ブロック | 答える問い | 注意点 |
|---|---|---|
| Component inventory | 答える問いClaude Codeがプラグインの中に何を見つけたか | 注意点コマンドはスキルに数えられる(format-all がSkillsに出る理由) |
| Projected token cost | 答える問い全ユーザーが毎セッション背負う量 | 注意点下げる対象はこの数字 |
| Per-component | 答える問いどの部品が一番食っているか | 注意点部品ごとにAlways-onとon-invokeを並べる(値は丸め) |
読み方の要点は「Always-on」と「on-invoke」の区別です。Always-onは名前と説明だけで、何も実行されなくても毎セッション載ります。on-invokeはスキルやエージェントが動いたときにだけ読み込まれる本文分で、発火のたびに払います。例では lint-fix のAlways-onが約50、on-invokeが約30です。
末尾には「トークン数は見積もりで、実際の利用量と違うことがある」という注記が付きます。順位づけや前後比較には向きますが、請求額の予測には使えません。
フックとMCPサーバーは数字に入らない
出力の Hooks 行には「harness-only — no model context cost」、MCP servers 行には「tool schemas resolved at runtime; not counted」と付いています。フックとMCPサーバーにはコスト見積もりも、Per-componentの行もありません。
ここから分かるのは、Always-onの数字が小さくても、プラグインが同梱するMCPサーバーのツール定義は別に載ることがあるということです。MCPツールの分は、プラグインを有効にしたセッションで /context を実行し、MCP tools カテゴリで確かめられます。プラグインのMCPサーバーの仕組みはプラグイン同梱MCPサーバーの記事にあります。
Always-onを下げる
Always-onの値は、各コンポーネントの名前に、description と when_to_use のフロントマターを足したものです。プラグインの作者が下げる手段は2つです。
- スキルとエージェントの説明を短くする
- 大きなプラグインを分割し、必要な部品だけ入れられるようにする
説明を削るときは注意が要ります。スキルの説明は、Claudeがリクエストと突き合わせて発火を決める材料でもあります。短くしすぎると、呼ばれるべき場面で呼ばれなくなります。削った後は、評価スイートの tool_used: Skill グレーダーで発火を確かめられます。
利用者の側から数字を下げる手段は、プラグインを無効化するかアンインストールすることだけです。説明文には手を出せません。
出力例の lint-fix で考えると、Always-onの約50は名前、description、when_to_use の合計です。on-invokeの約30は本文分なので、説明を削ってもそちらは動きません。description はClaudeが発火を判断する材料でもあるので、削ると呼ばれ方に響きかねません。when_to_use が description とほぼ同じ内容なら、片方に寄せるだけでAlways-onの数字は下がります。発火に効く説明そのものを削るより、影響が読みやすい手順です。
測定を回す例
次の例は、導入済みの全プラグインのAlways-on行だけを抜き出す書き方です。claude plugin list --json の id を使う想定で、Always-on: の行は上の出力例に合わせています。手元の出力形式で確かめてから使ってください。
claude plugin list --json | jq -r '.[].id' | while read -r id; do
echo "== $id"
claude plugin details "$id" | grep 'Always-on'
done数字の大きいプラグインから、Per-componentの行で重い部品を探す流れになります。
/pluginのContext costは「公式マーケットプレイスだけ」
/plugin でも同じ種類の数字を見られますが、出る条件が狭くなっています。
- 対象はAnthropicの公式マーケットプレイスのプラグイン
- 詳細ペインにContext cost節が出て、
Every turn:とWhen invoked:の2行が並ぶ - Always-onの値が2,000トークン以上のとき、
Every turn:の行が強調表示される - 自前のマーケットプレイスのプラグインには、この節が出ない
さらに、公式マーケットプレイスのプラグインでも、表示される経路が限られます。インストール手順のページによると、マーケットプレイス名を指定してプラグインを開いたときか、Marketplacesタブから開いたときに出ます。Discoverの一覧から入った詳細ペインには出ません。
名称の対応は次のとおりです。
claude plugin details | /plugin の詳細ペイン |
|---|---|
| Always-on | /plugin の詳細ペインEvery turn |
| on-invoke | /plugin の詳細ペインWhen invoked |
自前のマーケットプレイスで配るプラグインを作る側は、利用者のペインに数字が出ないので、自分でこのコマンドを回して数字を把握しておくことになります。一覧の中身はプラグイン一覧の記事で確認できます。
使われているかは別のコマンドで見る
費用が分かっても、使われているかは分かりません。利用状況の確認先は次のように分かれます。
利用状況を見る4つの場所
/plugin の Installed タブ
マーケットプレイスから入れたプラグインが、14日間かつ10セッション使われないとNot used recentlyの下に移ります。詳細には
Last used:の行が出ます。LSPサーバーを持つプラグインは、診断を返したりコード移動の要求に答えたりすると「使用中」に数えられます。/skill-doctor
各スキルの費用と利用頻度を出し、スキル一覧に載っているのに一度も呼ばれていないものを、プラグイン由来も含めて示します。対話セッションでは
/pluginのStatsタブにレポートが開きます。詳しくはskill-doctorの使い方です。/doctor
ユーザーが入れたスキル・MCPサーバー・プラグインを並べ、使われていないものの無効化を勧めます。/doctorのチェックアップも参照してください。
/usage
Pro・Max・Team・Enterpriseで、直近の利用がスキル・サブエージェント・プラグイン・MCPサーバーに占める割合を出します。
4つとも、ユーザー自身がClaude Codeのセッション内で実行するコマンドです。結果はその人の画面にだけ出ます。組織全体の利用を見るには、次の節のOpenTelemetryかAnalytics APIを使います。
Not used recentlyには出ない例外があります。--plugin-dir やスキルディレクトリから読み込んだもの、管理設定で有効化されたものやシードディレクトリのもの、テーマ・出力スタイル・モニター・ワークフローを含むものです。strictKnownMarketplaces を組織が設定している場合は、見出しも Last used: の行も出ません。
「毎ターンの費用が大きく、しかも使われていない」プラグインが、削る候補の筆頭です。前者は claude plugin details、後者は上のコマンドで確かめます。費用と利用の組み合わせで、扱いは次のように分かれます。
| 使われている | 使われていない | |
|---|---|---|
| Always-onが大きい | 使われている説明を詰めるか、プラグインを分割する | 使われていない無効化かアンインストール |
| Always-onが小さい | 使われているそのまま残す | 使われていない手間をかけて消すほどの費用ではない |
大きいうえに使われている場合は、削る前に発火を評価で確かめる手間が加わります。
組織全体で測るなら
利用者の手元ではなく組織で測るなら、OpenTelemetryのイベントか、Enterpriseプランで使えるAnalytics APIです。イベントと属性の対応は次のとおりです。
| 知りたいこと | 使うもの |
|---|---|
| どのプラグインがどこから入ったか | 使うものclaude_code.plugin_installed |
| 何セッションで有効か | 使うものclaude_code.plugin_loaded |
| どのスキルが動いたか | 使うものclaude_code.skill_activated |
| APIコストの帰属 | 使うものコストカウンターの plugin.name と marketplace.name |
公式マーケットプレイス以外のプラグインは、既定では名前が伏せられます。OTEL_LOG_TOOL_DETAILS=1 を設定すると実名が出ます。ただしコストカウンターでは、marketplace.name は実名にしても出ないままです。組織自前のマーケットプレイスのプラグインも伏せられる点に注意が要ります。伏せ方はイベントで違います。loadedイベントでは、公式ティア以外の plugin.name と marketplace.name が文字列 third-party になり、plugin.scope は org や user-local のように導入元を示し続けます。installedイベントでは、名前の項目そのものが出ません。Analytics APIは、公式とコミュニティのティアだけを名前つきで報告し、残りは third-party にまとめます。設定の組み立てはOpenTelemetryでプラグインの導入と利用を測る記事にまとめています。
Analytics APIは GET /v1/organizations/analytics/plugins で、プラグインごと・日ごとの導入数と起動数を、ユーザー・RBACグループ・プロダクト別に集計できます。read:analytics スコープのAPIキーが必要で、Primary Ownerが作成します。
まとめ
claude plugin details が見せるのは、プラグインを入れた時点で毎セッション払い続ける固定費です。on-invokeは使った分だけの変動費で、フックとMCPサーバーはそもそも計算に入っていません。固定費の大きなプラグインを見つけたら、説明を詰めるか分割し、発火を評価で確かめます。数字が /plugin に出ない自前マーケットプレイスでは、配る側が自分で測っておく必要があります。