# How Legacy Plugin Names Are Handled with the Renames Field in Claude Plugins

> Learn how Claude plugins handle legacy names using the renames field. Ensure backward compatibility and smooth transitions with automatic identifier substitution.

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

---

**The `renames` field in the marketplace manifest provides a mapping of legacy plugin identifiers to their current canonical names, enabling automatic substitution during plugin resolution to maintain backward compatibility.**

The `anthropics/claude-plugins-community` repository uses a centralized redirection mechanism to ensure renamed plugins remain accessible through their previous identifiers. This system prevents breaking changes for users with existing configurations while allowing maintainers to update plugin branding or naming conventions.

## Understanding the Renames Field Structure

The **marketplace manifest** located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) contains a top-level object called `renames` that defines the legacy-to-canonical name mappings.

According to the source code at lines 6‑11, this field stores key-value pairs where each **key** represents a legacy plugin identifier and each **value** specifies the new canonical name that should be used for resolution. For example, the mapping `"qodo-skills": "qodo"` ensures that requests for the legacy identifier automatically resolve to the current plugin definition.

## The Three-Phase Resolution Process

When Claude Code or compatible clients process a plugin request, they execute a transparent substitution workflow:

### 1. Lookup Phase

The client checks if the requested plugin name exists as a key within the `renames` object. If the name appears in the mapping table, the system flags it for substitution.

### 2. Substitution Phase

The client replaces the legacy identifier with its corresponding canonical value from the `renames` mapping. If no mapping exists, the requested name passes through unchanged.

### 3. Resolution Phase

Using the canonical name (whether substituted or original), the client searches the `plugins` array in the marketplace manifest to locate the complete plugin definition and metadata.

This process remains **invisible to end-users**, ensuring that scripts, documentation links, and configuration files referencing legacy names like `"wordpress-com"` continue functioning while resolving to updated canonical names such as `"build-with-wordpress"`.

## Implementation Examples

### JavaScript Resolution Logic

```javascript
import manifest from '.claude-plugin/marketplace.json';

function resolvePluginName(requestedName) {
  // Apply legacy rename if present, otherwise use original name
  const canonical = manifest.renames?.[requestedName] ?? requestedName;
  // Locate plugin definition using canonical name
  return manifest.plugins.find(p => p.name === canonical);
}

// Legacy name "qodo-skills" resolves to "qodo"
const plugin = resolvePluginName('qodo-skills');
console.log(plugin?.name); // → "qodo"

```

### Python Resolution Logic

```python
import json
from pathlib import Path

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

def resolve_plugin(name: str):
    # Check renames mapping for legacy identifiers

    canonical = manifest.get('renames', {}).get(name, name)
    # Return matching plugin from plugins array

    return next((p for p in manifest['plugins'] if p['name'] == canonical), None)

# Legacy identifier lookup

plugin = resolve_plugin('wordpress-com')
print(plugin['name'])   # → "build-with-wordpress"

```

### Fallback Behavior

When a requested name does not exist in the `renames` mapping, the system treats it as a canonical name and attempts direct resolution:

```javascript
console.log(resolvePluginName('nonexistent-plugin')); // → undefined
// No entry in `renames`, so request proceeds with original name

```

## Key Files in the Architecture

- **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** – The central manifest defining the `renames` object and the complete `plugins` array. This file serves as the authoritative source for name mappings and plugin metadata.

- **[`testdino/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/README.md)** – Example plugin documentation illustrating how canonical names appear in practice after legacy resolution completes.

- **[`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json)** – Individual plugin metadata file referenced after the name resolution process determines the correct canonical identifier.

## 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 to current canonical plugin names at lines 6‑11.
- **Automatic substitution** occurs through a three-phase process: lookup, substitution, and resolution.
- **Zero breaking changes** result from renaming plugins, as existing configurations reference legacy names that transparently resolve to current definitions.
- **Multiple language implementations** (JavaScript and Python) can leverage the same JSON mapping structure for consistent resolution behavior.

## Frequently Asked Questions

### What happens if a legacy name is not listed in the renames field?

If the requested plugin name does not appear as a key in the `renames` object, the system uses the requested name directly as the canonical identifier and searches the `plugins` array without modification. This ensures that current names continue to function normally while providing an upgrade path for legacy identifiers.

### Can a plugin have multiple legacy names pointing to it?

Yes, the structure allows multiple legacy identifiers to map to a single canonical name. Each legacy name appears as a separate key in the `renames` object with the same canonical value, enabling gradual migration from multiple old naming conventions to one current standard.

### Where exactly is the renames field located within the repository?

The `renames` field exists as a top-level property in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), specifically defined at lines 6‑11 according to the source analysis. This placement ensures the mapping loads simultaneously with the plugin registry for efficient resolution.

### Is the name substitution visible to end users or affecting plugin functionality?

No, the substitution is completely transparent. End users and automated scripts continue referencing legacy names, while the resolution layer handles the translation internally. The plugin receives and operates under its canonical name regardless of which identifier initiated the request.