How Plugin Slug Renames Are Handled in marketplace.json

The marketplace.json file defines a top-level renames object that maps legacy plugin slugs to their current identifiers, enabling automatic resolution and backward compatibility when users reference outdated slugs.

The Claude plugins community repository centralizes plugin metadata in .claude-plugin/marketplace.json, where a dedicated mapping structure ensures that plugin slug renames maintain ecosystem stability without breaking existing installations. When maintainers update a plugin's identifier—such as changing "auth0-sdks" to "auth0"—the marketplace uses this centralized configuration to seamlessly redirect requests to the correct current metadata.

The renames Object Structure

Located at lines 6‑11 of .claude-plugin/marketplace.json, the renames field appears as a top-level JSON object containing simple key-value pairs. Each key represents a legacy slug that users or systems might still reference, while the corresponding value specifies the current canonical identifier.

The mapping follows this structure:

{
  "renames": {
    "qodo-skills": "qodo",
    "wordpress-com": "build-with-wordpress",
    "auth0-sdks": "auth0",
    "twilio": "twilio-developer-kit"
  }
}

This centralized approach ensures that slug transitions are documented in a single authoritative location rather than scattered across multiple configuration files or documentation pages.

Slug Resolution Logic

When Claude resolves a plugin request—such as during installation via /install <slug>—the marketplace logic performs a lookup against the renames map before processing the request.

The resolution follows two distinct steps:

1. Lookup – The system checks if the requested slug exists as a key in the renames object.
2. Substitution – If found, the legacy slug is immediately replaced with the corresponding current identifier; otherwise, the original slug proceeds unchanged to the metadata retrieval stage.

This mechanism allows older documentation, user scripts, and persisted references to continue functioning without requiring manual updates to the newer slugs.

Backward Compatibility and URL Stability

The renames mapping provides critical backward compatibility for the plugin ecosystem. When a plugin maintainer rebrands or simplifies their slug, existing URLs and API calls that embed the old identifier automatically redirect to fetch the new slug's metadata.

For example, a user running /install qodo-skills triggers the system to fetch metadata for "qodo" instead, ensuring the correct plugin description, source repository, and homepage are retrieved. This stability extends to persisted configurations across Claude sessions and external documentation links that hardcode specific slugs.

CI/CD Validation

The repository includes automated validation to ensure the renames object remains well-formed and functional. The workflow defined in .github/workflows/validate-plugins.yml processes marketplace.json during continuous integration runs, verifying that:

• All legacy slugs map to valid, existing plugin identifiers
• No circular references exist within the rename mappings
• The JSON structure adheres to the expected schema

This automated checking prevents broken redirects from being merged into the main branch.

Practical Implementation Examples

When interacting with the Claude plugin system, users can reference either current or legacy slugs interchangeably in installation commands:

# Installing a plugin using a legacy slug triggers automatic resolution

/install qodo-skills        # Internally maps to "qodo"

/install wordpress-com      # Internally maps to "build-with-wordpress"

/install auth0-sdks         # Internally maps to "auth0"

For developers implementing similar resolution logic in Python, the slug lookup follows this pattern against the marketplace manifest:

import json

with open(".claude-plugin/marketplace.json") as f:
    data = json.load(f)

def resolve_slug(requested_slug: str) -> str:
    """Resolve a potentially legacy slug to its current identifier."""
    return data.get("renames", {}).get(requested_slug, requested_slug)

# Examples of resolution

print(resolve_slug("auth0-sdks"))   # → auth0

print(resolve_slug("twilio"))       # → twilio-developer-kit

print(resolve_slug("new-plugin"))   # → new-plugin (unchanged if not in renames)

Summary

• The renames object in .claude-plugin/marketplace.json (lines 6‑11) maps legacy slugs to current identifiers using simple key-value pairs.
• Slug resolution occurs automatically during plugin lookup, substituting outdated references before metadata retrieval.
• This system ensures backward compatibility for existing documentation, scripts, and persisted configurations.
• The .github/workflows/validate-plugins.yml workflow validates rename entries during CI to prevent broken mappings and circular references.

Frequently Asked Questions

What happens if a slug is renamed multiple times?

The resolution system supports chained renames as long as each intermediate slug is listed as a key in the renames object. The final canonical identifier should be the value in the last mapping of the chain, ensuring users can reference any historical version of the slug and still reach the correct plugin.

Can plugin maintainers request a slug rename?

Yes, maintainers can submit a pull request modifying the renames section of .claude-plugin/marketplace.json to add a new mapping from their old slug to the new one. The entry must pass validation in .github/workflows/validate-plugins.yml before merging, ensuring the target slug exists and the mapping is properly formatted.

Do rename mappings affect plugin updates for existing installations?

No, existing installations reference the plugin by their internal ID rather than the slug used during initial installation. The renames mapping primarily affects new installation requests and URL resolution, not the update mechanism for already-installed plugins.

Where is the canonical plugin metadata stored after a rename?

The canonical metadata remains in individual plugin descriptor files (such as .claude-plugin/plugin.json), using the current slug as specified in the renames value. The mapping in marketplace.json simply ensures requests for legacy slugs redirect to these current metadata locations without requiring duplicate entries.

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