Claude Code plugin の userConfig はユーザー設定の単一値だが project 設定の pluginConfigs 手書きで上書きできる
Claude Code の plugin が宣言する userConfig(有効化時に値を尋ねる仕組み)は、標準フロー(plugin install の config オプションや対話的な configure)では常にユーザー設定ファイル(ホーム配下の settings.json)の pluginConfigs に単一値として保存される。install 時に scope を local や project にしても、有効化フラグ(enabledPlugins)だけがそのスコープに書かれ、userConfig の値はユーザー設定に行く。別プロジェクトで同じ plugin に別の値を設定すると、前の値は黙って上書きされる。
誤解しやすい条件
- 「install の scope を分ければ設定値もプロジェクト毎になる」は誤り。値は全プロジェクト共通の1つだけになる。
- プロジェクトを行き来しながら configure し直す運用は、もう一方のプロジェクトの値を静かに壊す。
プロジェクト毎に別値にする方法(実測で確認した未文書挙動)
pluginConfigs は設定スコープのマージに乗るため、プロジェクトの settings ファイル(.claude/settings.local.json など)に pluginConfigs のエントリ(キーは plugin名@marketplace名、その下の options に値)を手書きすると、実行時にユーザー設定の値より優先される。スキル本文内のプレースホルダー展開と、plugin 同梱 MCP 設定の URL 内展開の両方で、プロジェクト側の値が使われることを確認済み。
検証方法
plugin に user_config のプレースホルダーを含む観測点(スキル本文に埋め込む、または MCP 一覧表示で URL の展開結果を見る)を用意し、2つのプロジェクトで別値を設定して独立に反映されるかを見る。
適用上の注意
2026-07 時点の実測で、公式ドキュメントには保存スコープの明記がない。plugin を配布する側は「既定は全プロジェクト共通、プロジェクト毎に変える場合は project 設定への手書き」を利用者向け案内に含めるとよい。