Understanding the Structure of the marketplace.json File in Claude Plugins

The marketplace.json file is a JSON array where each element describes a single Claude Code plugin using a consistent schema of required and optional properties.

The anthropics/claude-plugins-community repository maintains the marketplace.json file as the central registry for community-contributed Claude Code plugins. This machine-readable file located at .claude-plugin/marketplace.json defines the metadata structure that allows Claude Code to discover, display, and install third-party skills.

Core Schema and Required Fields

Every plugin entry in the marketplace.json array must include three core properties. These required fields enable the Claude Code plugin manager to identify and resolve the source code for installation.

• name: A human-readable string identifying the plugin or skill.
• description: A short summary that appears in the Claude Code plugin browser, explaining the plugin's functionality.
• url: The GitHub repository or Git URL where the plugin source lives. This can be formatted as owner/repo shorthand or a full HTTPS URL like https://github.com/user/repo.git.

A minimal valid entry contains only these three fields:

{
  "name": "claude-trading-skills-marketplace",
  "description": "A Claude plugin marketplace packaging tradermonty's claude-trading-skills as themed, installable plugins",
  "url": "https://github.com/pasie15/claude-trading-skills-marketplace.git"
}

Optional Metadata Properties

Beyond the core schema, the marketplace.json structure supports additional optional fields that enhance discoverability and provide legal attribution.

• homepage: URL to a landing page or documentation site separate from the repository.
• tags: An array of keyword strings used for categorization and search filtering within the marketplace UI.
• license: An SPDX identifier specifying the plugin's open-source license (e.g., "MIT", "Apache-2.0").
• version: A semantic version string (e.g., "1.2.0") indicating the plugin package release.
• authors: An array of objects containing contributor information such as name and email.
• extra: A flexible object for plugin-specific metadata including ref, sha, or dependencies required for installation.

The presence of these optional fields varies across entries in the repository. For example, some plugins include detailed tags for filtering, while others rely solely on the required core fields.

File Location and Validation

The marketplace.json file resides at .claude-plugin/marketplace.json in the repository root. This location is hardcoded into the validation workflows that ensure data integrity before merging community submissions.

According to the source code, the repository enforces schema compliance through automated CI checks defined in .github/workflows/validate-plugins.yml. The workflow executes shell scripts located at .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh, which performs JSON schema validation against the marketplace file. Helper functions in .github/actions/validate-plugins/lib/common.sh support these validation steps by providing shared parsing utilities.

These validation mechanisms ensure that every entry remains machine-readable and can be safely consumed by Claude Code's plugin manager without causing parsing errors.

Programmatic Interaction with marketplace.json

Developers can interact with the marketplace.json structure programmatically to query existing plugins or automate submissions.

Loading and Parsing in Python

This Python snippet demonstrates how to load the file and iterate through plugin entries:

import json
from pathlib import Path

marketplace_path = Path(__file__).parent / ".claude-plugin" / "marketplace.json"
with marketplace_path.open() as f:
    plugins = json.load(f)

# Print the names of all available plugins

for p in plugins:
    print(p["name"])

Adding a New Plugin Entry with JavaScript

The following Node.js example shows how to append a new plugin object while maintaining the required structure:

const fs = require('fs');
const path = require('path');

const marketplaceFile = path.join(__dirname, '.claude-plugin', 'marketplace.json');
const marketplace = JSON.parse(fs.readFileSync(marketplaceFile, 'utf8'));

marketplace.push({
  name: "my-awesome-plugin",
  description: "An example plugin demonstrating the marketplace schema.",
  url: "github.com/myuser/my-awesome-plugin",
  homepage: "https://github.com/myuser/my-awesome-plugin",
  tags: ["example", "demo"],
  license: "MIT",
  version: "0.1.0"
});

fs.writeFileSync(marketplaceFile, JSON.stringify(marketplace, null, 2));

Filtering Plugins by Tag

You can search the marketplace.json array for specific functionality using tag filtering:

def find_by_tag(tag):
    return [p for p in plugins if "tags" in p and tag in p["tags"]]

trading_plugins = find_by_tag("trading")
for p in trading_plugins:
    print(p["name"], p["url"])

Summary

• The marketplace.json file follows a flat JSON array structure where each object represents one Claude Code plugin.
• Three core fields are mandatory: name, description, and url.
• Six optional fields provide enhanced metadata: homepage, tags, license, version, authors, and extra.
• The file is located at .claude-plugin/marketplace.json and is validated by CI workflows in .github/workflows/validate-plugins.yml.
• The structure is designed to be machine-readable by Claude Code tooling while remaining simple enough for manual editing.

Frequently Asked Questions

Where is the marketplace.json file located in the repository?

The file resides at .claude-plugin/marketplace.json in the repository root. This specific path is referenced by the validation scripts in .github/workflows/validate-plugins.yml to ensure community submissions are checked automatically.

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

Every plugin object must include name (human-readable identifier), description (summary text), and url (source repository location). These three fields allow the Claude Code plugin manager to display and install the skill.

How does the repository validate the marketplace.json structure?

The repository uses GitHub Actions workflows defined in .github/workflows/validate-plugins.yml to validate the file. These workflows execute shell scripts in .github/actions/validate-plugins/scripts/ that check JSON syntax and verify that required fields are present in every array element.

Can I include custom metadata in my plugin entry that isn't part of the standard schema?

Yes, the optional extra object accepts arbitrary key-value pairs for plugin-specific requirements. According to the source code, this field can store values like ref, sha, or dependencies that specific plugins need for proper installation or operation.

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