Claude Codeのマーケットプレイスでrenamesを使いプラグイン名を移行する

プラグインの name を変えたいときは、marketplace.json のトップレベルに renames マップを足します。旧名を新名に対応づけ、削除したプラグインは null に対応づける形です。これで既存ユーザーの設定が自動で書き換わり、Plugin "<name>" not found in marketplace を避けられます。自動移行はClaude Code v2.1.193以降で動きます。

この記事は、マーケットプレイスを配布する側の手順です。まず改名が本当に必要かを見分け、次に renames の書き方、ユーザー側に起きること、削除と forceRemoveDeletedPlugins の使い分け、リリース前の検証までを順に見ます。

名前を変える前に、displayNameで足りないか確認する

プラグインの name は識別子です。ユーザーは enabledPlugins と pluginConfigs の設定キーや /plugin install でこの名前を参照します。変更すると、既存のインストールがすべて壊れます。

見た目のラベルを変えたいだけなら、plugin.json に displayName を設定します。name は動かしません。/plugin に表示される名前だけが変わり、設定キーには影響しません。

displayName は、マーケットプレイスのエントリ側にも plugin.json 側にも置けます。どちらにも無いときは name がそのまま表示されます。ブランド名の表記を整えたい程度の改名は、まずここで済ませるのが安全です。

renamesマップの書き方

renames は marketplace.json のトップレベルに置くオブジェクトです。キーが旧名、値が現在の名前で、プラグインが消えた場合は値を null にします。公式の例では、formatter を code-formatter に改名し、legacy-linter を削除済みとして記録しています。

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

plugins の配列から旧名のエントリを消し、新名のエントリを置くのを忘れないでください。renames は旧名の行き先を案内するだけで、新名のプラグイン本体は plugins に載っている必要があります。

改名を重ねるときは追記だけにする

renames は追記専用の履歴として扱います。全員が移行し終えても古い行は残します。もう一度改名するときは、最初の行を書き換えず、2行目を足します。Claude Codeは最も古い名前から連鎖をたどるためです。

たとえば formatter を code-formatter にした後、さらに fmt-tools へ改名するなら、次のように書きます。

"renames": {
  "formatter": "code-formatter",
  "code-formatter": "fmt-tools"
}

連鎖は最も古い名前からたどられるので、formatter も code-formatter も最終的に fmt-tools に行き着く書き方です。

既存ユーザーには何が起きるか

pushした後、旧名を有効にしたままのユーザーには、エントリの種類に応じて次のことが起きます。

• 改名エントリ: プラグインは新名で読み込まれます。claude plugin list と /plugin の詳細画面に、Renamed to "code-formatter" in the "your-marketplace" marketplace が一度だけ表示されます。Claude Codeは、ユーザー・プロジェクト・ローカルの各スコープで、enabledPlugins と pluginConfigs の旧キーを新キーに書き換えます
• null エントリ: 旧キーがそれらのスコープから削除され、Removed from the "your-marketplace" marketplace と表示されます
• 管理設定で有効にしている場合: プラグインは新名で読み込まれます。ただしClaude Codeは管理設定を書き換えられないため、通知は管理者が enabledPlugins を更新するまで繰り返し出ます

三つ目は組織で配布している場合の見落としどころです。管理設定側の enabledPlugins は、マーケットプレイスの管理者ではなく設定の管理者が直す必要があります。マーケットプレイスの運用者と管理設定の管理者が別のチームなら、改名の予定を事前に共有しておくと通知の繰り返しを避けられます。管理設定の配り方はGHESプラグインマーケットプレイスの許可リスト運用やマーケットプレイス必須化の設定の記事にまとめています。

v2.1.193より古いClaude Codeのユーザー

自動移行はv2.1.193以降の機能なので、それより古いClaude Codeを使い続けているユーザーには renames が働きません。旧名のままでは解決されないため、Claude Codeの更新を案内するか、新名で /plugin install し直してもらう形になります。

gitやURLで追加したマーケットプレイスでは再インストールが要る

gitリポジトリやURLから追加したマーケットプレイスでは、改名されたプラグインが Plugin "<name>" not cached at <path> を報告します。ユーザーがセッションの中で一度、次のコマンドを実行するまで続きます。

/plugin install code-formatter@your-marketplace

改名は設定キーの書き換えまでは自動ですが、新名のキャッシュは作られません。改名を告知するときは、この一行を添えておくと問い合わせが減ります。キャッシュを消した後などに not cached at が出たときは、シェルから次のように再インストールできます。

claude plugin install <name>@<marketplace>

その後、セッションで /reload-plugins を実行します。

削除したプラグインを端末から消すには

プラグインを plugins から外して renames に null を書くと、設定キーは消えます。一方、すでにインストール済みのコピーが端末から消えるとは限りません。

公式の説明では、forceRemoveDeletedPlugins を付けない場合、削除されたプラグインはインストールされたまま残ります。セッション読み込み時に Plugin "<name>" not found in marketplace と報告されます。端末からアンインストールしたいときは、marketplace.json のトップレベルに次を足します。

{
  "forceRemoveDeletedPlugins": true
}

有効にすると、Claude Codeはセッション開始のたびに次の処理をします。

1. ユーザーがそのマーケットプレイスからインストールしたものを、plugins のエントリと renames マップに照らします。どちらにも無いプラグインは削除済みとみなします
2. 削除済みのプラグインを、ユーザー・プロジェクト・ローカルの各スコープからアンインストールします。管理設定だけでインストールされたものは残ります
3. /plugin のFlagged見出しの下に、削除済みのプラグインを Removed from marketplace の状態で並べます

公式には、プラグインの「非推奨」という状態はありません。非推奨にしたいときの選択肢は、エントリを消して renames で null にし、必要なら forceRemoveDeletedPlugins を足すことです。「もうすぐ消えます」と予告する状態は、マーケットプレイス側に用意されていません。予告が要るなら、プラグインの説明文やREADMEで伝えます。

判断の早見表

リリース前にclaude plugin validateで検証する

renames を編集したら、シェルで次を実行します。

claude plugin validate .

連鎖が循環していたり、null か plugins の名前以外で終わっていたりすると、renames.<name>: chain does not resolve で弾かれます。リファレンスの検証メッセージ表には、chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null と、target "x" is not a valid plugin name (PluginIdSchema) の二つが renames 関連のエラーとして載っています。

行き先として認められるのは、plugins の名前、renames のキー、null のいずれかです。これを外れる書き方は二通りあります。一つは、行き先が輪になっている場合です。

"renames": {
  "a": "b",
  "b": "a"
}

もう一つは、行き先の名前が plugins にも renames のキーにもなく、null でもない場合です。

"renames": {
  "formatter": "fmt-tols"
}

後者は plugins 側の名前と renames の値が一文字ずれた打ち間違いで起きやすい形です(この例では fmt-tools の綴りが崩れています)。この検証をCIに入れておくと、push前に気づけます。

Plugin not found in marketplaceが出たときの切り分け

このエラーは改名や削除以外でも出ます。ユーザーから報告を受けたときは、次の順で見ます。

1. リフレッシュのヒントが付いているか: メッセージに Your local copy may be out of date があれば、手元のカタログが古いだけです。claude plugin marketplace update <marketplace> でカタログを更新して、もう一度インストールします
2. ヒントが無いか: 名前そのものの誤りが最も疑わしくなります。/plugin のDiscoverで名前をコピーして使います
3. 改名や削除の直後か: 旧名で有効にしているなら、renames に旧名の行があるかを確認します。v2.1.193より古いClaude Codeでは、この自動移行が働きません

v2.1.193の変更点は、Claude Code v2.1.193のリリースノートに「プラグインの自動改名追従」として載っています。ユーザーのClaude Codeが古いままなら、renames を書いても効かない点に注意してください。

not found in marketplace に加えて Plugin "<name>" not found in any marketplace という別のメッセージもあります。こちらは @marketplace を付けずにインストールしたときに、登録済みのどのマーケットプレイスにも該当がない場合です。原因の切り分けが変わるので、混同しないようにします。

運用のチェックリスト

改名や削除を出す前に、次を確認します。

• 本当に name の変更が必要か。displayName で足りないか
• 旧名の行を renames に追加したか(既存の行は消さない)
• 新名のエントリが plugins に入っているか
• claude plugin validate . がエラー 0で通るか
• 管理設定で旧名を有効にしている組織へ、事前に連絡したか
• 改名なら、gitやURLで追加したユーザー向けに /plugin install 新名@マーケットプレイス名 の案内を出したか
• 端末から消したい削除なら、forceRemoveDeletedPlugins を付けるか決めたか

バージョンやブランチでの配布チャネルの分け方はプラグインの配布チャネル、プラグイン全体の仕組みはClaude Codeプラグイン完全ガイドで扱っています。

まとめ

プラグインの name は設定キーそのものなので、変えると既存の導入が壊れます。表示だけの変更なら displayName、識別子を変えるなら renames に旧名から新名を、削除なら null を書きます。renames は追記専用で、改名を重ねるときは行を足します。端末から消すには forceRemoveDeletedPlugins が別に要ります。管理設定と、gitやURLで追加したマーケットプレイスの二点が、自動移行でも手が残る場所です。