What Does the `renames` Field in `marketplace.json` Signify? A Developer's Guide

The renames field in marketplace.json is a backward-compatibility mapping that translates outdated plugin identifiers to their current canonical names, ensuring seamless plugin resolution even after rebranding or renaming.

The anthropics/claude-plugins-community repository powers the Claude plugin marketplace through a centralized manifest file. Understanding the renames field in marketplace.json is essential for developers maintaining plugins that have undergone name changes, as it prevents "plugin not found" errors for users with existing configurations while preserving functional continuity.

How the renames Mapping Works in marketplace.json

The renames object is defined as a top-level field in .claude-plugin/marketplace.json, specifically occupying lines 6-11 of the manifest. This mapping tells the Claude plugin marketplace how to handle plugins that have been rebranded or reorganized.

Structure and Key-Value Syntax

The field follows a straightforward object structure where:

• Keys represent old plugin identifiers that may persist in existing user configurations or legacy manifests.
• Values specify the new canonical names that the marketplace should resolve to instead.

When the marketplace loads the plugin list, it consults this mapping to automatically resolve any reference to an outdated name to its current equivalent.

Real-World Examples from the Source Code

The current implementation in the anthropics/claude-plugins-community repository includes several active rename mappings:

{
  "renames": {
    "qodo-skills": "qodo",
    "wordpress-com": "build-with-wordpress",
    "auth0-sdks": "auth0",
    "twilio": "twilio-developer-kit"
  }
}

In this configuration, if a user attempts to install the plugin twilio, the marketplace automatically resolves this request to twilio-developer-kit. Similarly, references to qodo-skills are transparently mapped to qodo without requiring users to update their configuration files.

Implementing Rename Resolution in Your Code

You can implement identical resolution logic in your own tooling by loading the manifest and checking user input against the renames dictionary.

Python Resolution Example

The following script demonstrates how to resolve plugin names using the same logic as the Claude marketplace:

import json
import pathlib

# Load the marketplace manifest from the repository

manifest_path = pathlib.Path('.claude-plugin/marketplace.json')
manifest = json.loads(manifest_path.read_text())

# Build the rename map from the renames field

renames = manifest.get('renames', {})

def resolve_name(name: str) -> str:
    """Return the canonical plugin name, applying any rename mapping."""
    return renames.get(name, name)

# Example usage

print(resolve_name('twilio'))          # → twilio-developer-kit

print(resolve_name('unknown-plugin'))  # → unknown-plugin (unchanged)

This approach ensures your applications handle plugin renames consistently with the official anthropics/claude-plugins-community implementation, providing the same backward-compatibility guarantees for your users.

Why the renames Field Matters for Plugin Stability

Without the renames field, any plugin reorganization would immediately break existing installations and scripts. By maintaining this mapping in .claude-plugin/marketplace.json, the Claude ecosystem supports:

• Seamless rebranding when organizations change product names.
• Consolidation when multiple plugins merge into single offerings.
• Legacy support for tutorials and documentation referencing old identifiers.

The resolution happens transparently during the plugin loading phase, meaning users experience no interruption when canonical names change.

Summary

• The renames field in .claude-plugin/marketplace.json maps old plugin identifiers to new canonical names for backward compatibility.
• It is located at lines 6-11 of the manifest file in the anthropics/claude-plugins-community repository.
• Each key-value pair represents one rename, where the key is the outdated name and the value is the current identifier.
• When resolving plugin names, the marketplace automatically substitutes outdated identifiers with their current equivalents.
• Developers can implement identical resolution logic by checking input names against the renames dictionary before processing.

Frequently Asked Questions

What happens if a plugin name is not found in the renames mapping?

If a plugin identifier does not exist as a key in the renames object, the marketplace returns the name unchanged. This passthrough behavior ensures that current, non-renamed plugins continue to function normally without requiring entries in the mapping.

Where exactly is the renames field defined in the repository?

The renames field is defined at the top of .claude-plugin/marketplace.json in the anthropics/claude-plugins-community repository. According to the source analysis, the mapping occupies lines 6-11 of the file, immediately following the opening JSON structure.

Can a plugin undergo multiple renames over time?

Yes, though the renames mapping should always point directly to the current canonical name. If a plugin changes names multiple times, all historical identifiers should map to the final current name rather than chaining through intermediate names. This ensures O(1) lookup performance regardless of how many times a plugin has been renamed.

Do users need to update their configurations when a plugin is renamed?

No, users do not need to immediately update their configurations. The renames field exists specifically to avoid breaking changes, allowing existing installations and scripts to continue using old identifiers indefinitely. However, updating to the canonical name is recommended for clarity and future-proofing.

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