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

> Understand the marketplace.json schema for Claude Plugins Community. Discover fields for name, description, source, author, and category to effectively list your Claude Code plugins.

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

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file in the `anthropics/claude-plugins-community` repository is a canonical JSON manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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 |

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

```

*Source:* Lines 1-12 of [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.

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

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) | Central manifest — primary subject of this guide |
| [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) | CI workflow for schema validation |
| [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) | Documentation for the validation action |
| [`.github/actions/owner-liveness-sweep/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/owner-liveness-sweep/action.yml) | Handles `renames` map for ownership changes |

## Summary

- **Location**: [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json). The same command executes in CI via [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), so local validation prevents failed builds.