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

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

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

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:

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 – 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 – Example plugin documentation illustrating how canonical names appear in practice after legacy resolution completes.

• 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 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, 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.

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