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

The renames field in 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, 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, containing simple key-value pairs where each key represents a legacy identifier and its value specifies the current canonical name.

{
  "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 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.

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:

// 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 reads the same 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 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 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.

How does the marketplace validator check rename entries?

The validation script at .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh parses .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, the actual plugin definitions—including those referenced by canonical names like qodo or auth0—are stored in .claude-plugin/plugin.json and referenced by the resolver after completing the rename substitution.

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