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

> Learn to manage plugin renames in marketplace.json for Claude plugins. Discover how the renames object ensures smooth transitions and prevents duplicate entries for seamless integration.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-25

---

**The Claude plugin marketplace handles canonical name changes through a dedicated `renames` object in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). This object uses the legacy plugin name as the key and the new canonical name as the value.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). The key must be the **old** name, and the value must be the **new** name.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml)) executes the [`bump.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/bump.sh) script, which detects renames within the same owner and emits appropriate warnings:

```bash
$ 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```bash

# 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:

```bash
$ 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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.