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

The Claude Code marketplace uses a "renames" section in .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 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 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:

{
  "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:

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

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

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

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