What Is the Purpose of the `marketplace.json` File in the PM Skills Repository?

The marketplace.json file serves as the root marketplace manifest that aggregates metadata for nine product management plugins, synchronizes their versioning, and enables discovery by AI assistants like Claude Code.

In the phuryn/pm-skills repository, the marketplace.json file functions as the authoritative catalog for the entire plugin ecosystem. Located at .claude-plugin/marketplace.json, this JSON manifest coordinates the discovery, installation, and validation of specialized product management skills across the codebase.

Core Functions of the marketplace.json Manifest

Aggregating Plugin Metadata

The primary role of marketplace.json is to enumerate all nine first-class plugins distributed throughout the repository. According to the source code, this file collates critical metadata including each plugin's name, version, description, source directory, and category.

For example, the manifest lists plugins such as pm-product-discovery, pm-execution, and pm-ai-shipping within a unified structure. This aggregation allows the marketplace UI to display a complete catalog without traversing the individual plugin directories directly.

Providing a Single Source of Truth

The top-level "description" field in marketplace.json provides a concise one-liner that appears in both the Cowork marketplace browser and Claude Code's marketplace view. This ensures consistent messaging across all distribution channels.

When users browse available skills, they encounter the same descriptive text regardless of whether they access the repository through the CLI, web interface, or AI assistant integration.

Synchronizing Versioning Across Plugins

All nine plugins share a common version number (currently 2.0.0) defined in the root manifest. This design enforces version consistency across the entire ecosystem.

According to the repository's CLAUDE.md documentation, whenever any individual plugin's plugin.json receives a version bump, the same version must be simultaneously reflected in .claude-plugin/marketplace.json. This lockstep versioning ensures that the marketplace view and individual plugins remain synchronized, preventing version drift between the catalog and the actual plugin implementations.

Driving Automated Validation

The repository includes a validate_plugins.py script that treats marketplace.json as the canonical reference for structural integrity. This validation script checks consistency between the root manifest and the per-plugin plugin.json files distributed across subdirectories.

If a developer adds a plugin to a source directory but forgets to update the marketplace manifest, or if version numbers diverge between files, the validation script flags the discrepancy before commit.

Enabling AI Assistant Discovery

Claude Code and Claude Cowork read marketplace.json to expose the full set of PM skills to end users. Rather than requiring users to know the internal folder structure (e.g., pm-product-discovery/.claude-plugin/), the AI assistants parse this manifest to present a browsable, installable catalog.

This abstraction layer allows users to invoke any plugin without navigating the repository's physical directory layout.

Working with marketplace.json

Reading the Manifest at Runtime

To programmatically access the plugin catalog, parse the JSON file directly:

import json
import pathlib

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

print(f"PM Skills version: {data['version']}")
for plugin in data["plugins"]:
    print(f"- {plugin['name']}: {plugin['description']}")

Listing All Plugin Sources

Use jq to extract the source directories for automation or build scripts:

jq -r '.plugins[].source' .claude-plugin/marketplace.json

# → ./pm-product-discovery

# → ./pm-product-strategy

# → ./pm-execution

# → ...

Updating the Version

When bumping the shared version across all plugins, modify the root manifest:

NEW_VERSION="2.1.0"
jq --arg v "$NEW_VERSION" '.version = $v' .claude-plugin/marketplace.json > tmp && mv tmp .claude-plugin/marketplace.json
git add .claude-plugin/marketplace.json
git commit -m "Bump marketplace version to $NEW_VERSION"

Key Files and Relationships

The marketplace.json file operates within a specific architectural context:

• .claude-plugin/marketplace.json – The root manifest located at the repository root that lists all plugins and the overall version.
• CLAUDE.md – Documentation explaining the role of marketplace.json and its relationship to other manifests, including versioning requirements.
• validate_plugins.py – The validation script that checks consistency between marketplace.json, per-plugin plugin.json files, and the repository structure.
• pm-{plugin}/.claude-plugin/plugin.json – Individual plugin manifests distributed across nine directories that must stay in sync with the root marketplace.json.

Summary

• marketplace.json acts as the root marketplace manifest for the pm-skills repository, residing at .claude-plugin/marketplace.json.
• It aggregates metadata for nine first-class plugins, providing a unified catalog of product management skills.
• The file enforces version synchronization (currently 2.0.0) across all plugins to prevent drift between the catalog and individual implementations.
• validate_plugins.py uses this file as the canonical reference to check consistency with per-plugin plugin.json manifests.
• Claude Code and Claude Cowork consume this JSON to enable discovery, allowing users to browse and install plugins without knowing the internal directory structure.

Frequently Asked Questions

Where is the marketplace.json file located in the pm-skills repository?

The file is located at .claude-plugin/marketplace.json in the repository root. This specific path allows Claude Code and other AI assistants to locate the manifest predictably when scanning the repository structure.

How does marketplace.json handle versioning across multiple plugins?

All nine plugins share a common version defined in the "version" field of marketplace.json. When any plugin updates, this root version must be bumped simultaneously, ensuring the marketplace catalog and individual plugin manifests remain synchronized according to the repository's validation rules.

What happens if marketplace.json is out of sync with individual plugin.json files?

The repository's validate_plugins.py script detects inconsistencies between the root manifest and per-plugin plugin.json files. The script validates that all plugins listed in marketplace.json exist, that their individual manifests match the aggregated data, and that version numbers align across the ecosystem.

Why is marketplace.json necessary if each plugin has its own plugin.json?

While individual plugin.json files contain plugin-specific configurations, marketplace.json serves as the discovery layer that AI assistants and marketplace browsers read first. Without this root manifest, tools would need to traverse the entire repository to find plugins, whereas the manifest provides immediate access to the complete catalog and shared metadata like the global version.

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