# How Plugin Name Renames Work in Claude Code's marketplace.json

> Learn how Claude Code's marketplace.json handles plugin name renames for backward compatibility. Understand the "renames" section and maintain seamless transitions for your plugins.

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

---

**The Claude Code marketplace uses a `"renames"` section in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) to map historic plugin identifiers to their current names, enabling seamless backward compatibility.**

The `anthropics/claude-plugins-community` repository powers the official Claude Code plugin ecosystem. Understanding how name renames work in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) is essential for plugin maintainers who need to rebrand or consolidate their offerings without breaking existing user installations. The rename mechanism ensures that commands referencing old identifiers—like `qodo-skills`—automatically resolve to the canonical name `qodo`.

## The Renames Mechanism in marketplace.json

The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file contains two critical sections working together: `"renames"` for identifier mapping and `"plugins"` for actual plugin definitions.

Rename entries are simple key-value pairs where the key is the **legacy identifier** and the value is the **current canonical name**:

```json
{
  "renames": {
    "qodo-skills": "qodo",
    "wordpress-com": "build-with-wordpress",
    "auth0-sdks": "auth0",
    "twilio": "twilio-developer-kit"
  },
  "plugins": [
    {
      "name": "qodo",
      "description": "...",
      "source": { "source": "url", "url": "https://github.com/qodo-ai/qodo-skills.git" },
      "homepage": "https://qodo.ai"
    }
  ]
}

```

This indirection layer means users can install plugins using either the old or new name, with the marketplace loader handling the translation transparently.

## How the Rename Resolution Works

When the marketplace loader processes a plugin request, it follows a three-step resolution chain:

1. **Lookup** – The loader checks if the requested name exists as a key in the `"renames"` object.
2. **Substitution** – If matched, the loader replaces the requested name with the mapped value.
3. **Resolution** – The loader searches the `"plugins"` array for a definition whose `"name"` field equals the substituted (or original) name.

The resolution logic behaves like this pseudocode from the Claude Code client runtime:

```ts
function resolvePlugin(requestedName: string) {
  const renames = marketplace.renames;
  const canonicalName = renames[requestedName] ?? requestedName;
  return marketplace.plugins.find(p => p.name === canonicalName);
}

```

## Practical Example: qodo-skills to qodo

The `qodo` plugin demonstrates a real-world rename in the [anthropics/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) repository. The plugin originally published under `qodo-skills` was consolidated under the simpler `qodo` brand.

Legacy commands continue working after the rename entry is added:

```bash

# This command works both before and after the rename

claude plugin install qodo-skills@qodo

# The loader resolves "qodo-skills" → "qodo" and installs

# the plugin defined under "name": "qodo"

```

Users can also reference the canonical name directly:

```bash

# Preferred modern syntax

claude plugin install qodo@qodo

```

Both commands resolve to identical plugin definitions because the rename map bridges the identifier gap.

## Adding or Updating a Rename Entry

The rename system requires **no code changes** to the Claude Code client. Modifications are purely data-driven:

- Edit [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) directly
- Add or update entries in the `"renames"` object
- Submit a pull request to the `anthropics/claude-plugins-community` repository

The marketplace runtime automatically honors updated maps on the next configuration reload. This static JSON approach eliminates deployment complexity for plugin renames.

## Key Design Benefits

- **Backward compatibility** – Existing projects, CI pipelines, and documentation referencing old names remain functional indefinitely
- **Zero-downtime migration** – Plugin maintainers can rename without coordinating user-facing changes
- **Simplified consolidation** – Multiple legacy plugins can map to a single canonical definition
- **Version-agnostic resolution** – The rename applies regardless of which plugin version users request

## Summary

- The `"renames"` section in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) maps old plugin identifiers to current names
- Resolution follows lookup → substitution → plugin array search
- Renames enable seamless backward compatibility for branding changes and consolidations
- Adding renames requires only JSON edits—no runtime code changes needed
- The `qodo-skills` → `qodo` rename in the `anthropics/claude-plugins-community` repository demonstrates production usage

## Frequently Asked Questions

### Where is the renames configuration stored?

The rename mappings live in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) at the root of the `anthropics/claude-plugins-community` repository, specifically in the `"renames"` object alongside the `"plugins"` array.

### Do I need to update the Claude Code client when a plugin renames?

No. The rename resolution happens server-side when the marketplace configuration loads. Users with any recent Claude Code version automatically receive rename support without updating their local installation.

### Can multiple old names map to the same new plugin?

Yes. The JSON structure permits any number of keys in `"renames"` to point to identical values. This supports complex consolidation scenarios where several legacy plugins merge into one canonical offering.

### What happens if a rename entry points to a non-existent plugin name?

The resolution fails gracefully. After substitution, if no plugin definition matches the canonical name, the marketplace returns a "plugin not found" error. Maintainers should verify that every value in `"renames"` corresponds to an actual `"name"` in the `"plugins"` array.