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

> Explore the structure of the marketplace.json file for Claude Code plugins. Learn the schema for describing plugins with required and optional properties.

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

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file as the central registry for community-contributed Claude Code plugins. This machine-readable file located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file resides at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). The workflow executes shell scripts located at [`.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), which performs JSON schema validation against the marketplace file. Helper functions in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```python
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:

```javascript
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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) array for specific functionality using tag filtering:

```python
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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) and is validated by CI workflows in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) in the repository root. This specific path is referenced by the validation scripts in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.