What Is the Renames Block in marketplace.json and How Does It Work?

The renames block in marketplace.json maps deprecated plugin identifiers to their current canonical names, enabling the Claude Plugins CLI to transparently rewrite installation requests for backward compatibility.

The renames block is a critical component of the marketplace definition in the anthropics/claude-plugins-community repository. Located in .claude-plugin/marketplace.json, this top-level dictionary ensures that users can still install plugins using outdated names while repository maintainers freely update plugin identifiers. This mechanism prevents breaking changes when plugins are renamed to better reflect their functionality.

Understanding the Renames Block Structure

The renames field appears at the top level of the marketplace JSON schema alongside the name, owner, and plugins fields. It defines a simple key-value mapping where each key represents an old plugin identifier and each value specifies the new canonical name.

According to the source code in .claude-plugin/marketplace.json (lines 6-11), the structure follows this pattern:

{
  "name": "claude-community",
  "owner": { "name": "Anthropic" },
  "renames": {
    "qodo-skills": "qodo",
    "wordpress-com": "build-with-wordpress",
    "auth0-sdks": "auth0",
    "twilio": "twilio-developer-kit"
  },
  "plugins": [ ]
}

This mapping lives directly within the marketplace definition, allowing the CLI to resolve aliases in a single file read without external redirect files.

How the Renames Block Works

When executing commands like claude plugin install, the CLI performs a lookup sequence that checks the renames dictionary before processing the request.

CLI Resolution Process

The resolution follows these steps:

1. The CLI loads .claude-plugin/marketplace.json from the repository
2. It checks if the requested plugin name exists in the renames map
3. If found, the CLI transparently replaces the old name with the new canonical name
4. The installation, validation, or lookup proceeds using the resolved name

This happens automatically when users run commands like claude plugin install wordpress-com@claude-community, which internally resolves to build-with-wordpress@claude-community.

Backward Compatibility Benefits

The renames block provides three key advantages:

• Uninterrupted workflows: Users referencing outdated plugin names avoid "plugin not found" errors
• Flexible refactoring: Repository maintainers can rename plugins to improve clarity without breaking existing references
• Single-source resolution: Alias information coexists with plugin definitions, eliminating the need for separate redirect files or additional network requests

Practical Examples

Querying Aliases with jq

You can inspect the current alias mappings directly from the marketplace file using jq:

# Show the new name for an old identifier

jq -r '.renames["qodo-skills"]' .claude-plugin/marketplace.json

# → qodo

This command extracts the canonical name for the deprecated qodo-skills identifier from the JSON structure.

Installing Plugins by Old Names

The CLI handles alias resolution transparently during installation:

# The CLI resolves "wordpress-com" → "build-with-wordpress"

claude plugin install wordpress-com@claude-community

Internally, the validation and installation scripts process this resolution before executing the actual plugin validation logic.

Programmatic Resolution

When building tools that interact with the marketplace programmatically, implement the same resolution logic:

const fs = require('fs');
const path = '.claude-plugin/marketplace.json';
const marketplace = JSON.parse(fs.readFileSync(path, 'utf8'));

function resolvePluginName(name) {
  const alias = marketplace.renames?.[name];
  return alias ?? name;
}

console.log(resolvePluginName('auth0-sdks')); // prints "auth0"

This Node.js implementation mirrors the behavior of the official CLI, checking the renames dictionary before falling back to the original name.

Key Files and Validation

The aliasing behavior relies on several components within the repository structure:

• .claude-plugin/marketplace.json: Contains the authoritative renames map and plugin definitions
• .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh: Reads the assembled marketplace JSON (including renames) before running claude plugin validate
• .github/workflows/validate-plugins.yml: CI workflow that assembles the marketplace and supplies the file to validation actions
• README.md: Documents the marketplace JSON as the read-only mirror used by Claude Plugins

These files work together to ensure that alias resolution functions correctly across the CLI validation pipeline.

Summary

• The renames block in marketplace.json maps old plugin identifiers to new canonical names for backward compatibility
• Located at .claude-plugin/marketplace.json, it enables transparent name resolution without external redirect files
• The Claude Plugins CLI automatically rewrites requests when it finds matches in the renames dictionary
• Repository maintainers can safely rename plugins while preserving existing user workflows
• The validation pipeline in .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh processes these aliases during CI/CD

Frequently Asked Questions

Where is the renames block located in the repository?

The renames block is located in .claude-plugin/marketplace.json at the top level of the JSON structure, alongside fields like name, owner, and plugins. This placement allows the Claude Plugins CLI to access alias mappings in a single file read during plugin resolution.

What happens if I install a plugin using its old name?

The CLI automatically resolves the old name to the current canonical name using the renames map. For example, running claude plugin install wordpress-com@claude-community transparently installs build-with-wordpress@claude-community without requiring you to update your command scripts or documentation references.

Can I view the current alias mappings without installing plugins?

Yes, you can query the renames dictionary directly using command-line tools like jq. Run jq '.renames' .claude-plugin/marketplace.json to display all current aliases, or target specific entries with jq -r '.renames["old-name"]' to see individual mappings.

How does the renames block differ from other plugin marketplace systems?

Unlike systems that require separate redirect files or database entries for renamed plugins, the renames block in marketplace.json keeps alias information co-located with plugin definitions. This single-file approach allows the validation scripts in .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh to resolve names in one pass without additional network requests or file reads.

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