Claude Plugins Community `marketplace.json` Structure: Complete Schema Guide

The marketplace.json file in the anthropics/claude-plugins-community repository is a canonical JSON manifest at .claude-plugin/marketplace.json that describes every community-published Claude Code plugin with fields for name, description, source location, author metadata, and category, using either url or git-subdir retrieval strategies.

This file powers the Claude CLI's plugin discovery, validation, and installation system. Understanding its schema is essential for contributing new plugins or building tools that consume the marketplace.

Top-Level Structure of marketplace.json

The root object contains four key properties that define the marketplace metadata and plugin collection.

Property	Type	Required	Description
name	string	✅	Always "claude-community" — the marketplace identifier
owner	object	✅	Metadata container with name field (currently "Anthropic")
renames	object	—	Maps legacy plugin IDs to current canonical IDs for CLI redirection
plugins	array	✅	Core collection of plugin entry objects

{
  "name": "claude-community",
  "owner": {
    "name": "Anthropic"
  },
  "renames": {
    "qodo-skills": "qodo"
  },
  "plugins": [...]
}

Source: Lines 1-12 of .claude-plugin/marketplace.json define these fields【/cache/repos/github.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json†L1-L12】.

Individual Plugin Object Schema

Each element in the plugins array follows a consistent baseline with optional extensions for richer metadata.

Property	Type	Required	Description
name	string	✅	CLI identifier used in /plugin install <name>
description	string	✅	Human-readable summary; supports newlines
source	object	✅	Retrieval configuration with nested source method field
homepage	string (URL)	✅	Plugin website or repository link
author	object	—	Attribution with { "name": "..." } structure
category	string	—	Classification like "testing" or "developer-tools"
sha	string (in source)	✅*	Exact commit SHA for reproducible installs
ref	string (in source)	—	Branch or tag reference for git-subdir sources
path	string (in source)	—	Relative subdirectory path for multi-plugin repos

*Required when source.source is url or git-subdir.

The meticulous entry demonstrates optional fields in practice, including author and category: "testing"【/cache/repos/github.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json†L100-L106】.

Source Retrieval Strategies

The source object supports two mutually exclusive retrieval methods specified by its nested source field.

url Method: Full Repository Clone

Use when a plugin occupies its entire repository.

{
  "name": "0x",
  "description": "Guide developers through swapping ERC-20 tokens...",
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  },
  "homepage": "https://github.com/0xProject/0x-ai"
}

git-subdir Method: Subdirectory Extraction

Use when multiple plugins live in one repository — the CLI extracts only the specified path.

{
  "name": "a11y-fixer",
  "description": "Scan HTML/JSX for accessibility issues",
  "source": {
    "source": "git-subdir",
    "url": "barnburner121/claude-plugin-marketplace",
    "path": "generated-plugins/a11y-fixer",
    "ref": "main",
    "sha": "5f6b5d32d9f457dc9c2c7c0fb1d67dffc9140f33"
  },
  "homepage": "https://github.com/barnburner121/claude-plugin-marketplace"
}

Both strategies guarantee reproducible installs through exact SHA pinning regardless of upstream changes.

Extensibility and Schema Evolution

The marketplace.json schema is intentionally open — additional keys are tolerated without breaking older CLI versions. This design allows:

• Future metadata additions (e.g., license, tags, version)
• Plugin-specific custom fields
• Gradual schema evolution across the ecosystem

The validation system at .github/workflows/validate-plugins.yml enforces baseline requirements while permitting extensions.

Validation and CI Integration

The repository's validate-plugins GitHub Action runs claude plugin validate to enforce manifest integrity:

• Required top-level keys (name, owner, plugins) must exist
• Every plugin entry must contain a valid, reachable source object with SHA
• Plugin name values must be unique across the collection

This automated gating keeps the marketplace install-ready and prevents broken references from reaching users.

How the Claude CLI Consumes marketplace.json

When a user executes claude plugin install <name>, the CLI performs:

1. Fetch — Downloads the marketplace JSON (with local caching)
2. Lookup — Resolves the plugin by its name field
3. Source resolution — Determines url vs git-subdir strategy
4. Checkout — Retrieves exact sha (or ref + sha for subdirectories)

This flow makes marketplace.json the single source of truth for plugin discovery, versioning, and installation across all Claude CLI installations.

Related Files in the Repository

File Path	Purpose
.claude-plugin/marketplace.json	Central manifest — primary subject of this guide
.github/workflows/validate-plugins.yml	CI workflow for schema validation
.github/actions/validate-plugins/README.md	Documentation for the validation action
.github/actions/owner-liveness-sweep/action.yml	Handles renames map for ownership changes

Summary

• Location: .claude-plugin/marketplace.json in anthropics/claude-plugins-community
• Root fields: name, owner, renames (optional), plugins (array)
• Plugin required fields: name, description, source, homepage
• Source methods: url (full repo) or git-subdir (subdirectory extraction)
• Reproducibility: Exact sha pinning mandatory for all sources
• Validation: Automated via claude plugin validate in CI

Frequently Asked Questions

What happens if a plugin name changes?

The renames object at the top level maps legacy IDs to current canonical IDs. The CLI checks this map during lookup and transparently redirects old references to new locations.

Can I add custom fields to my plugin entry?

Yes — the schema is open and extensible. Custom fields like author, category, or future additions are tolerated. Only baseline required fields are enforced by validation.

Why does git-subdir require both ref and sha?

The ref (branch/tag) provides human-readable context while sha guarantees exact reproducibility. The CLI uses ref for display and sha for the actual checkout, ensuring users always receive identical code regardless of upstream branch movement.

How do I validate my plugin contribution before submitting?

Run claude plugin validate locally against your modified marketplace.json. The same command executes in CI via .github/workflows/validate-plugins.yml, so local validation prevents failed builds.

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