# How the `renames` Field in `marketplace.json` Enables Backward Compatibility

> Learn how the renames field in marketplace.json ensures backward compatibility by mapping legacy plugin identifiers to current names for seamless Claude Code integration.

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

---

**The `renames` field in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) maps legacy plugin identifiers to current canonical names, allowing Claude Code to transparently redirect old plugin references to their updated counterparts without breaking existing user workflows.**

The `anthropics/claude-plugins-community` repository manages plugin availability through a centralized marketplace manifest. Within [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), the **`renames`** object functions as a compatibility layer that ensures existing scripts, tutorials, and CLI commands referencing deprecated plugin names continue to function seamlessly as the ecosystem evolves.

## The Structure of the `renames` Mapping

The `renames` section exists as a top-level key in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), containing simple key-value pairs where each key represents a legacy identifier and its value specifies the current canonical name.

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

```

This indirection layer allows the marketplace to modernize plugin naming conventions—switching from vendor-specific suffixes like `-skills` or `-sdks` to cleaner canonical names—while maintaining full backward compatibility for any code or documentation referencing the original identifiers.

## Plugin Resolution Algorithm

When Claude Code resolves a plugin request, the system implements a two-phase lookup strategy that prioritizes direct matches before consulting the rename map.

### Step-by-Step Resolution Process

1. **Direct lookup** – The resolver searches the `plugins` array in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) for an exact match against the requested name.

2. **Rename fallback** – If no direct match exists, the system checks the `renames` map for the requested identifier.

3. **Canonical substitution** – When found, the resolver substitutes the legacy name with the corresponding canonical value (e.g., `qodo-skills` becomes `qodo`).

4. **Final resolution** – The resolver repeats the lookup using the canonical name and loads the plugin definition from [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json).

For example, when a user executes `/skill qodo-skills`, the system internally rewrites the request to `qodo` and proceeds with loading the corrected plugin definition, making the transition invisible to end users.

## Implementing the Lookup Logic

The resolution logic can be implemented manually using the following pattern, which mirrors the behavior of the Claude Code resolver:

```javascript
// Simplified resolution routine
function resolvePlugin(requestedName, marketplace) {
  // Direct match?
  const direct = marketplace.plugins.find(p => p.name === requestedName);
  if (direct) return direct;

  // Check renames
  const canonical = marketplace.renames?.[requestedName];
  if (canonical) {
    return marketplace.plugins.find(p => p.name === canonical);
  }

  throw new Error(`Plugin "${requestedName}" not found`);
}

```

This implementation demonstrates how the `renames` object acts as a transparent middleware layer, intercepting legacy identifiers before they reach the core plugin loading mechanism.

## CI Validation of Rename Consistency

The marketplace validation pipeline ensures that rename mappings remain consistent across development and production environments. The validation script located at [`.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) reads the same [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file used by the runtime resolver.

This validation guarantees that every key in the `renames` map corresponds to a valid, loadable plugin identifier and that no circular references exist between legacy and canonical names. Because the CI enforces these rules, developers cannot accidentally break backward compatibility by removing a plugin without updating its corresponding rename entry.

## Summary

- The **`renames`** field in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) maps legacy identifiers like `qodo-skills` to canonical names like `qodo`.
- Claude Code implements a two-phase resolution that checks direct matches first, then falls back to the rename map for backward compatibility.
- Real-world mappings include `wordpress-com` → `build-with-wordpress` and `auth0-sdks` → `auth0`.
- The CI validation script at [`.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) enforces rename consistency during the build process.
- This architecture allows the plugin ecosystem to evolve its naming conventions without breaking existing user workflows or documentation.

## Frequently Asked Questions

### What happens if a plugin name exists in both the `plugins` array and the `renames` map?

The resolver always checks the `plugins` array first for an exact match. If the name exists as a canonical plugin, that definition takes precedence, and the `renames` map is never consulted. This ensures that current names always resolve directly without indirection overhead.

### Can I still use legacy plugin names in Claude CLI commands?

Yes. According to the `anthropics/claude-plugins-community` source code, commands like `claude skill qodo-skills` continue to function because the resolver automatically redirects the legacy identifier to its canonical counterpart (`qodo`) using the mapping defined in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json).

### How does the marketplace validator check rename entries?

The validation script at [`.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) parses [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) and verifies that every target value in the `renames` object corresponds to an existing plugin definition. This prevents "dangling" renames that point to non-existent plugins.

### Where are the canonical plugin definitions stored?

While the `renames` field lives in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), the actual plugin definitions—including those referenced by canonical names like `qodo` or `auth0`—are stored in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and referenced by the resolver after completing the rename substitution.