Claude Plugins Community marketplace.json Schema: Complete Field Reference

The marketplace.json schema defines a top-level plugins array containing plugin entries with required fields name, description, url, and a nested source object with repo and sha properties, plus optional fields like homepage, tags, icon, license, authors, and dependencies.

The marketplace.json file serves as the canonical manifest for all community-published Claude plugins in the anthropics/claude-plugins-community repository. This JSON file powers the plugin marketplace UI and installation system, with strict schema enforcement handled through Zod-based validation in CI.

marketplace.json Structure Overview

The file contains a single top-level object with one required key:

Key	Type	Description
plugins	array	List of all registered community plugins

Every entry in the plugins array must conform to the schema enforced by the validate-plugins GitHub Action.

Required Fields for Each Plugin Entry

Each plugin object must include these core properties:

name (string)

The unique human-readable identifier for the plugin. This value must be globally unique across all marketplace entries and match certain filename conventions.

description (string)

A concise summary displayed in the marketplace UI to help users understand the plugin's purpose.

url (string, HTTPS)

The Git URL of the source repository. Must use HTTPS protocol. Example: https://github.com/user/repo.git

source (object)

Specifies how the plugin code is fetched. This object requires:

• repo (string, HTTPS): Git URL matching the top-level url field
• sha (string): Exact commit SHA that the marketplace pins to for reproducible installs

Optional source subfield:

• subdir (string): Relative path inside the repository where the .claude-plugin directory resides

Optional Fields for Plugin Entries

homepage (string, HTTPS)

Public landing page URL for the plugin, typically a GitHub repository page.

tags (array of strings)

Keywords enabling plugin discovery. Common values include "devtools", "prisma", "zod", "testing".

icon (string, URL)

Direct link to an SVG or PNG icon displayed in the marketplace UI.

license (string)

SPDX license identifier (e.g., "MIT", "Apache-2.0").

authors (array of strings)

Names or GitHub handles of primary contributors.

dependencies (object)

NPM-style dependency map that mirrors declarations in the plugin's package.json.

Complete Example: marketplace.json Entry

Based on entries in [.claude-plugin/marketplace.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), a valid plugin entry looks like:

{
  "plugins": [
    {
      "name": "prisma-zod-consistency",
      "description": "Audit Prisma + Zod + TypeScript projects for cross-layer drift...",
      "url": "https://github.com/rshelekhov/prisma-zod-consistency.git",
      "homepage": "https://github.com/rshelekhov/prisma-zod-consistency",
      "source": {
        "repo": "https://github.com/rshelekhov/prisma-zod-consistency.git",
        "sha": "a1b2c3d4e5f6g7h8i9j0k..."
      },
      "tags": ["devtools", "prisma", "zod"],
      "icon": "https://raw.githubusercontent.com/rshelekhov/prisma-zod-consistency/main/icon.svg"
    }
  ]
}

Schema Enforcement and Validation

The marketplace.json schema is validated through a multi-layer CI process defined in .github/actions/validate-plugins/.

Validation Checks

Per the action's README.md, which states the Zod schema is the "source of truth for the marketplace/plugin schema", the validator enforces:

• All required fields present (name, description, url, source.repo, source.sha)
• HTTPS-only URLs for security
• SHA pinning (no floating version tags allowed)
• Filename-to-entry name consistency
• No shell metacharacters in string fields
• Global uniqueness of plugin names

CI Validation Script

The validation executes through [.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh):

#!/bin/bash

# Validates marketplace.json against the Claude CLI schema

claude plugin validate .claude-plugin/marketplace.json

The action configuration in [.github/actions/validate-plugins/action.yml](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml) orchestrates this validation on every pull request.

Working with marketplace.json Programmatically

Adding a Plugin Entry via Command Line

jq '.plugins += [{
  "name": "my-cool-plugin",
  "description": "Do something awesome with Claude",
  "url": "https://github.com/me/my-cool-plugin.git",
  "source": {
    "repo": "https://github.com/me/my-cool-plugin.git",
    "sha": "abc123def456789"
  },
  "tags": ["cool", "demo"]
}]' .claude-plugin/marketplace.json > tmp.json && mv tmp.json .claude-plugin/marketplace.json

Reading Plugin Data in Node.js

const fs = require('fs');

const market = JSON.parse(
  fs.readFileSync('.claude-plugin/marketplace.json', 'utf8')
);

const entry = market.plugins.find(p => p.name === 'my-cool-plugin');
console.log(entry.source.sha);  // exact pinned commit

Validating Locally

claude plugin validate .claude-plugin/marketplace.json

Key Files Defining the Schema

File	Purpose
[.claude-plugin/marketplace.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)	Live marketplace manifest with all plugin entries
[.github/actions/validate-plugins/README.md](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md)	Documents the Zod schema as source of truth
[.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh)	CLI validation execution script
[.github/actions/validate-plugins/action.yml](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml)	GitHub Action configuration for CI enforcement

Summary

• The marketplace.json schema centers on a plugins array containing standardized plugin objects
• Required fields: name, description, url, source.repo, source.sha
• Optional fields: homepage, source.subdir, tags, icon, license, authors, dependencies
• SHA pinning in source.sha ensures reproducible installations
• Zod-based validation in the validate-plugins GitHub Action enforces schema compliance before merge
• All URL fields must use HTTPS protocol for security

Frequently Asked Questions

Where is the marketplace.json schema officially defined?

The schema is officially defined in the validate-plugins GitHub Action using Zod. According to [.github/actions/validate-plugins/README.md](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), the Zod definition serves as the "source of truth for the marketplace/plugin schema". The actual validation runs through claude plugin validate as implemented in [.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh).

Why does source.sha use exact commits instead of version tags?

The source.sha field requires exact commit SHAs to guarantee reproducible installations. Floating version tags could change downstream, leading to inconsistent plugin behavior or security issues. This immutable pinning ensures every installation retrieves identical code.

What happens if my marketplace.json entry fails validation?

The CI job fails and blocks merge. The validate-plugins action runs on every pull request via [.github/actions/validate-plugins/action.yml](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml), checking for required fields, HTTPS URLs, SHA format, name uniqueness, and prohibited characters. Fix reported errors and push updates to pass validation.

Can I specify a subdirectory for my plugin files?

Yes. Use the source.subdir field to indicate a relative path inside your repository where the .claude-plugin directory lives. This supports monorepo structures where multiple packages or plugins exist in subdirectories.

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