# Claude Plugins Marketplace Schema: Complete Guide to Plugin Entry Structure

> Understand the Claude Plugins Marketplace schema. Learn the required name, description, and source fields, plus optional metadata for your plugin entry. Submit your plugin with confidence.

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

---

**A plugin entry in the Claude Plugins Marketplace is a JSON object inside the `plugins` array of [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) that requires `name`, `description`, and `source` fields, with optional metadata like `homepage`, `author`, and `category` validated by the repository’s CI pipeline.**

The `anthropics/claude-plugins-community` repository defines the exact schema specifications that every plugin must follow to appear in the marketplace. Understanding this schema is essential for developers submitting plugins, as the **Validate-plugins** GitHub Action enforces strict invariants including HTTPS-only URLs, immutable SHA pinning, and mandatory field presence.

## Required Fields for Marketplace Entries

Every plugin entry must include three core properties to pass validation.

### name

The **name** field is a unique string identifier for the plugin (e.g., `"10x-shopping"`). This value must be distinct across the entire marketplace and typically uses kebab-case formatting.

### description

The **description** field provides a human-readable summary of the plugin’s functionality. This text appears in the marketplace listing and should concisely explain what the plugin enables Claude to do.

### source

The **source** object describes where the plugin code resides and requires specific sub-properties depending on the distribution method. The schema supports two source types with different required fields.

## Source Object Schema Details

The `source` property is an object that must contain a `source` type discriminator and repository location data. According to the validation rules in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), the structure varies by source type.

### URL Source Type

For plugins in standalone repositories, use `"source": "url"` with these fields:

- **source**: Must be the literal string `"url"`
- **url**: HTTPS Git URL of the repository (e.g., `"https://github.com/qressy/10x-claude-plugin.git"`)
- **sha**: Exact 40-character commit SHA for immutability (e.g., `"5cd3d90ec0cfa99773dd2c075e492bd280b3826a"`)

```json
{
  "name": "my-plugin",
  "description": "Brief description of the plugin.",
  "source": {
    "source": "url",
    "url": "https://github.com/username/my-plugin-repo.git",
    "sha": "abcdef1234567890abcdef1234567890abcdef12"
  }
}

```

### Git-Subdir Source Type

For plugins residing in subdirectories of larger repositories (monorepos), use `"source": "git-subdir"` with these fields:

- **source**: Must be `"git-subdir"`
- **url**: HTTPS Git URL of the parent repository
- **sha**: Exact commit SHA pinning the version
- **path**: Relative path inside the repository where the plugin lives (e.g., `"plugins/my-subplugin"`)
- **ref**: Optional branch or tag name (e.g., `"v2.0.0"`)

```json
{
  "name": "my-subplugin",
  "description": "Plugin residing in a subdirectory of a larger repo.",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/username/monorepo.git",
    "path": "plugins/my-subplugin",
    "ref": "v2.0.0",
    "sha": "12345abcde67890f12345abcde67890f12345abc"
  }
}

```

## Optional Fields

The Claude Plugins Marketplace schema accepts three optional metadata fields to enhance plugin discoverability.

### homepage

The **homepage** property specifies a URL to the plugin’s documentation, landing page, or repository. While optional, including this improves user trust and navigation.

### author

The **author** object contains metadata about the plugin creator with a `name` sub-property: `{ "name": "Developer Name" }`. This helps users identify plugin maintainers in the marketplace listing.

### category

The **category** string classifies the plugin’s purpose (e.g., `"testing"`, `"productivity"`). This classification aids in filtering and organizing marketplace entries by function.

## Validation and CI Enforcement

The repository enforces the Claude Plugins Marketplace schema through automated validation at [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md). This CI pipeline implements several critical invariants:

1. **HTTPS-only URLs**: All repository URLs must use HTTPS protocol, not SSH or HTTP
2. **SHA pinning**: Every entry must specify an exact commit SHA to ensure immutable plugin versions
3. **No direct edits**: Developers cannot directly modify the assembled [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json); changes must flow through the validation pipeline
4. **Field validation**: Missing required fields or invalid source configurations trigger CI failures

## Complete Example Entry

The following example from `anthropics/claude-plugins-community` demonstrates a valid entry using the URL source type with all optional fields populated:

```json
{
  "name": "10x-shopping",
  "description": "An AI-powered shopping assistant that connects Claude to Shopify's global product catalog. Browse products, manage carts, and complete purchases through natural conversation",
  "source": {
    "source": "url",
    "url": "https://github.com/qressy/10x-claude-plugin.git",
    "sha": "5cd3d90ec0cfa99773dd2c075e492bd280b3826a"
  },
  "homepage": "https://www.10xgeo.com/",
  "author": {
    "name": "10x Geo Team"
  },
  "category": "shopping"
}

```

## Summary

- Plugin entries reside in the `plugins` array inside [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)
- Required fields are **name** (unique identifier), **description** (human-readable summary), and **source** (repository location)
- The **source** object supports two types: `"url"` for standalone repos and `"git-subdir"` for monorepo subdirectories
- URL sources require `url` and `sha`; git-subdir sources additionally require `path` and may include `ref`
- Optional fields include **homepage**, **author** (with `name` property), and **category**
- The **Validate-plugins** CI action enforces HTTPS URLs, SHA pinning, and schema compliance

## Frequently Asked Questions

### What file contains the Claude Plugins Marketplace schema definition?

The schema is defined in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), which serves as the master manifest containing the `plugins` array. Validation rules are documented in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md).

### What are the minimum required fields for a plugin entry?

Every entry must include three fields: `name` (string identifier), `description` (functionality summary), and `source` (object containing repository location and commit SHA).

### How does the marketplace ensure plugin immutability?

The schema requires an exact `sha` commit hash in the source object. The CI validation at `anthropics/claude-plugins-community` enforces this SHA pinning to ensure marketplace entries always point to specific, unchangeable code versions.

### Can I publish a plugin that lives in a subdirectory of my repository?

Yes. Use `"source": "git-subdir"` instead of `"url"` and include the `path` property specifying the subdirectory location (e.g., `"path": "plugins/my-tool"`). You may also specify an optional `ref` field for branch or tag names.