Claude Plugins Marketplace Schema: Complete Guide to Plugin Entry Structure

A plugin entry in the Claude Plugins Marketplace is a JSON object inside the plugins array of .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, 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")

{
  "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")

{
  "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. 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; 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:

{
  "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
• 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, which serves as the master manifest containing the plugins array. Validation rules are documented in .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.

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