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

> Discover the 'renames' block in marketplace.json. Learn how it maps deprecated plugin IDs to current names for seamless backward compatibility with the Claude Plugins CLI.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: api-reference
- Published: 2026-09-11

---

**The `renames` block in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (lines 6-11), the structure follows this pattern:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`:

```sh

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

```sh

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

```js
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json): Contains the authoritative `renames` map and plugin definitions
- [`.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 assembled marketplace JSON (including `renames`) before running `claude plugin validate`
- [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml): CI workflow that assembles the marketplace and supplies the file to validation actions
- [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) maps old plugin identifiers to new canonical names for backward compatibility
- Located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh) to resolve names in one pass without additional network requests or file reads.