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

> Understand the renames field in marketplace.json. Learn how this backward-compatibility mapping ensures seamless plugin resolution after rebranding or renaming.

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

---

**The `renames` field in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)

The `renames` object is defined as a top-level field in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

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

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