How to Handle Plugin Renames in marketplace.json for Claude Plugins

The Claude plugin marketplace handles canonical name changes through a dedicated renames object in .claude-plugin/marketplace.json, which maps legacy names to current entries without creating duplicates or breaking existing installations.

The anthropics/claude-plugins-community repository maintains the centralized marketplace configuration for Claude plugins. When a plugin undergoes rebranding or repository migration, the system preserves backward compatibility by maintaining lightweight redirect mappings rather than duplicating entries or leaving orphaned references.

The Renames Map Structure

The marketplace stores all rename mappings in a top-level "renames" object within .claude-plugin/marketplace.json. This object uses the legacy plugin name as the key and the new canonical name as the value.

{
  "name": "claude-community",
  "owner": { "name": "Anthropic" },
  "renames": {
    "qodo-skills": "qodo",
    "wordpress-com": "build-with-wordpress",
    "auth0-sdks": "auth0",
    "twilio": "twilio-developer-kit"
  },
  "plugins": [ … ]
}

The client resolution logic checks this map before processing any install command. If a user attempts to install "qodo-skills", the CLI automatically resolves it to "qodo" according to the mapping defined in the marketplace configuration.

Step-by-Step Rename Process

When migrating a plugin to a new canonical name, follow this workflow to ensure seamless transitions for existing users.

Update the Source Repository

First, modify the plugin's source repository to ensure the plugin.json metadata uses the new name. This establishes the canonical identity that the marketplace will reference going forward.

Add the Rename Mapping

Insert a new key-value pair into the "renames" object in .claude-plugin/marketplace.json. The key must be the old name, and the value must be the new name.

{
  "renames": {
    "old-plugin": "new-plugin",
    "qodo-skills": "qodo"
  }
}

Remove the Legacy Entry

Delete the old plugin entry from the "plugins" array. The entry is now represented solely by the new name; the rename mapping handles backward compatibility without maintaining duplicate records.

Validate Through CI

Submit your changes to trigger the validation workflow. The bump-plugin-shas GitHub Action (defined in .github/workflows/bump-plugin-shas.yml) executes the bump.sh script, which detects renames within the same owner and emits appropriate warnings:

$ gh workflow run bump-plugin-shas --ref main

# … logs …

WARN  old-plugin: source repo renamed within the same owner (example/old-plugin → example/new-plugin) — bump proceeds; the listed source URL should be refreshed

The validate-plugins action runs .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh to enforce marketplace invariants, ensuring the rename is the only change and that no duplicate names exist.

Client Resolution Logic

The Claude CLI implements resolution logic that checks the renames map before processing installation requests. This pseudocode, extracted from the validation scripts, illustrates the resolution flow:

# Simplified logic from .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh

if [[ "$requested_name" =~ ${RENAMES_KEYS[@]} ]]; then
  target=$(jq -r ".renames[\"$requested_name\"]" "$MARKETPLACE_PATH")
  echo "Redirecting $requested_name → $target"
  requested_name=$target
fi

# continue with normal install flow using $requested_name

When users invoke the install command with a legacy name, they receive transparent redirection:

$ claude plugin marketplace add example/old-plugin
Redirecting old-plugin → new-plugin
Plugin "new-plugin" installed successfully.

Edge Cases and Validation Pitfalls

Several edge cases require manual intervention or special handling during the rename process.

Cross-Owner Moves

If the plugin migrates to a different GitHub owner (not just a repository rename), the CI marks the entry as "repo moved" and requires manual review. The automated bump-plugin-shas workflow cannot resolve ownership changes without explicit administrator approval.

Frozen SHA Entries

Plugins listed in freeze-shas.txt maintain immutable SHA pins regardless of repository changes. If you rename a frozen plugin, the rename mapping applies, but the SHA reference remains locked until the freeze is lifted.

Duplicate Key Constraints

The "renames" object must contain unique keys. Attempting to map multiple legacy names to the same new name (or creating circular references) causes the validate-plugins action to fail, as the client cannot resolve ambiguous targets.

Summary

• Store renames in .claude-plugin/marketplace.json using the top-level "renames" object with legacy names as keys and current names as values.
• Remove old entries from the "plugins" array after adding rename mappings to prevent duplicates.
• Run CI validation via the bump-plugin-shas workflow to detect renames and verify marketplace integrity.
• Handle cross-owner moves manually when plugins transfer between GitHub organizations.
• Respect frozen SHAs listed in freeze-shas.txt, which prevent automatic updates even during renames.

Frequently Asked Questions

Where exactly do I add a plugin rename mapping?

Add the mapping to the "renames" object in .claude-plugin/marketplace.json. The key should be the old plugin name, and the value should be the new canonical name. This file serves as the central registry for the Claude plugin community marketplace.

What happens if a plugin moves to a different GitHub owner?

Cross-owner moves trigger a "repo moved" status in the bump-plugin-shas workflow. Unlike simple renames within the same owner, these require manual review and approval because the source URL changes fundamentally, affecting security verification and trust boundaries.

How does the Claude CLI handle installation of renamed plugins?

The CLI checks the renames map before resolving any plugin reference. If the requested name exists in the renames object, it automatically redirects to the new name, then proceeds with the standard installation flow using the resolved canonical name.

Can I modify a rename mapping for a frozen plugin?

You can add or modify the rename mapping, but the SHA pin remains immutable if the plugin appears in freeze-shas.txt. The rename will redirect users to the correct plugin entry, but the code version stays locked until the freeze entry is removed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}