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

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 files for each component.

What is marketplace.json?

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 in the repository root. When the CI pipeline processes the repository, it reads each bundled plugin's local 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, while the tres-finance-plugin uses tres-finance-plugin/.claude-plugin/marketplace.json.

Core Schema Fields

Each marketplace.json file contains a JSON object with the following structure:

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

{
  "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 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), 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 is validated against the master schema defined in the repository-root .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:

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

This configuration at 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 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.

Installing Bundled Plugins via the CLI

Users interact with these manifests through the Claude CLI, which reads the marketplace.json entries to resolve and install plugins.

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

# 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 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 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 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 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 replaces the need for a separate plugin.json file. The Claude CLI extracts all necessary installation metadata from the 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 conforms to the schema defined in the repository-root .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.

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