# Understanding `marketplace.json` in Claude Bundled Plugins: Structure and Role

> Discover the essential role of marketplace.json in Claude bundled plugins. Learn how this manifest file enables plugin discovery and automated installation via the Claude CLI.

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

---

**[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) serves as the manifest file that describes the plugins or skills shipped inside a bundled Claude plugin directory, enabling discovery and automated installation through the Claude CLI.**

In the `anthropics/claude-plugins-community` repository, bundled plugins rely on a specific metadata file to bridge local code with the community marketplace. This file defines how individual skills are discovered, validated, and installed without requiring separate [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) files for each component.

## What is [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)?

[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) is the **authoritative manifest** that lives within the hidden `.claude-plugin/` subdirectory of every bundled plugin. Unlike standalone plugins that might define metadata at the root level, bundled plugins (such as `tres-finance-plugin` or `testdino`) use this file to declare one or more plugin entries contained within their directory structure.

According to the repository structure, this file follows the exact same schema as the top-level community marketplace file located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) in the repository root. When the CI pipeline processes the repository, it reads each bundled plugin's local [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) to assemble the complete marketplace catalog that users can query.

## File Location and Schema Requirements

Each bundled plugin must place its manifest at a specific path to be recognized by the validation workflows and CLI tools.

### Required File Path

The file must reside at:

```

<plugin-name>/.claude-plugin/marketplace.json

```

For example, the `testdino` plugin stores its manifest at [`testdino/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/marketplace.json), while the `tres-finance-plugin` uses [`tres-finance-plugin/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/marketplace.json).

### Core Schema Fields

Each [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file contains a JSON object with the following structure:

```json
{
  "name": "plugin-bundle-name",
  "owner": { "name": "Community" },
  "plugins": [
    {
      "name": "specific-skill-name",
      "source": "./",
      "strict": false,
      "description": "Optional description",
      "homepage": "https://optional-homepage.url"
    }
  ]
}

```

The **required fields** include:

- **`name`**: The identifier for the plugin bundle
- **`owner`**: An object containing the owner information (typically `{ "name": "Community" }` for community submissions)
- **`plugins`**: An array of plugin entries, each containing:
  - **`name`**: The specific skill identifier
  - **`source`**: The resolution path (see below)
  - **`strict`**: Boolean flag controlling manifest validation strictness

## Source Resolution: Local vs. External

The **`source`** field determines how the Claude CLI resolves the plugin code during installation.

### Local Bundled Sources

For plugins contained within the current directory structure, use a relative path:

```json
{
  "name": "testdino",
  "source": "./",
  "strict": false
}

```

The `"./"` value tells the CLI that the plugin source code resides at the root of the current bundled plugin directory. This is the standard pattern for bundled plugins in the `anthropics/claude-plugins-community` repository.

### External Git Sources

The `source` field can also point to external Git URLs, allowing the marketplace to reference plugins hosted outside the main repository. The CLI (`claude plugin marketplace add …`) resolves these references during the installation process.

## CI Validation and Marketplace Assembly

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) files play a critical role in the repository's continuous integration pipeline. When the *Validate plugins* workflow runs (defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)), it processes each bundled plugin's manifest to construct the full marketplace JSON.

The workflow performs the following steps:

1. **Schema Validation**: Each [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) is validated against the master schema defined in the repository-root [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)
2. **Source Resolution**: The CI checks that `source` paths (whether `"./"` or external URLs) resolve correctly
3. **Assembly**: Valid entries are aggregated into the community marketplace catalog

This automated process ensures that only properly structured plugins appear in the public marketplace and that installation commands will succeed when users run them locally.

## Real-World Examples from the Repository

### Minimal Example: testdino

The `testdino` bundled plugin demonstrates the simplest valid configuration:

```json
{
  "name": "testdino-plugins",
  "owner": { "name": "Community" },
  "plugins": [
    { "name": "testdino", "source": "./", "strict": false }
  ]
}

```

This configuration at [`testdino/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/marketplace.json) marks the plugin as non-strict (allowing more permissive validation) and points to the current directory for source files.

### Production Example: tres-finance-plugin

The `tres-finance-plugin` includes documentation referencing its [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) as the "Marketplace listing" in its directory tree. While the specific contents follow the same schema, this example illustrates how complex, multi-skill bundles structure their discovery metadata in the same location: [`tres-finance-plugin/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/marketplace.json).

## Installing Bundled Plugins via the CLI

Users interact with these manifests through the Claude CLI, which reads the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) entries to resolve and install plugins.

To add and install a bundled plugin from the community repository:

```bash

# Add the plugin's marketplace entry to the local catalog

claude plugin marketplace add my-awesome-plugin/my-awesome-plugin

# Install the specific skill

claude plugin install my-awesome-skill

```

During execution, the CLI:

1. Locates the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) within the bundled plugin directory
2. Resolves the `source` field (`"./"` for local bundles)
3. Copies the skill files into `~/.claude/plugins/...` for local use

This workflow eliminates the need for manual file copying or external configuration files.

## Summary

- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** acts as the discovery bridge between bundled plugin code and the Claude community marketplace
- **Location**: Must reside at `<plugin-name>/.claude-plugin/marketplace.json` within each bundled plugin directory
- **Schema**: Matches the top-level community marketplace format, requiring `name`, `owner`, and `plugins` array with `source` and `strict` fields
- **Source Resolution**: Uses `"./"` for local bundled content or Git URLs for external references
- **CI Integration**: The validation workflow assembles the full marketplace by aggregating individual [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) files
- **Installation**: The Claude CLI reads these manifests to automatically resolve, validate, and install plugin skills

## Frequently Asked Questions

### Can a bundled plugin contain multiple skills in one marketplace.json?

Yes. The `plugins` array in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) supports multiple entries, allowing a single bundled plugin directory to ship several related skills. Each entry requires its own `name` and `source` configuration, though typically bundled plugins use `"./"` for all entries when the skills share the same root directory.

### What happens if I omit the strict field in marketplace.json?

The `strict` field controls validation behavior during CI processing. When set to `false`, the validation pipeline applies more permissive checks to the plugin manifest. While the field may have a default value in the CLI, explicitly setting `strict: false` (as seen in the `testdino` example) ensures compatibility with the community validation workflow.

### Do I need a separate plugin.json if I have marketplace.json?

No. For bundled plugins in the `anthropics/claude-plugins-community` repository, [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) replaces the need for a separate [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file. The Claude CLI extracts all necessary installation metadata from the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) manifest, including the source location and plugin metadata, making additional configuration files redundant.

### How does the CI validate marketplace.json files?

The validation workflow runs `claude plugin validate` against the assembled marketplace path. It checks that each [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) conforms to the schema defined in the repository-root [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), verifies that `source` paths resolve correctly (whether local `"./"` paths or external Git URLs), and ensures all required fields are present before publishing to the community catalog.