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

> Discover the purpose of marketplace.json in the phuryn/pm-skills repository. This file aggregates metadata for nine product management plugins, synchronizes versions, and aids AI discovery.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: api-reference
- Published: 2026-06-21

---

**The [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) file functions as the authoritative catalog for the entire plugin ecosystem. Located at [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) documentation, whenever any individual plugin's [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) receives a version bump, the same version must be simultaneously reflected in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script that treats [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) as the canonical reference for structural integrity. This validation script checks consistency between the root manifest and the per-plugin [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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:

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

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

```bash
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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) file operates within a specific architectural context:

- **[`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)** – The root manifest located at the repository root that lists all plugins and the overall version.
- **[`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** – Documentation explaining the role of [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) and its relationship to other manifests, including versioning requirements.
- **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** – The validation script that checks consistency between [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json), per-plugin [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json).

## Summary

- **[`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json)** acts as the **root marketplace manifest** for the pm-skills repository, residing at [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** uses this file as the canonical reference to check consistency with per-plugin [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script detects inconsistencies between the root manifest and per-plugin [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) files. The script validates that all plugins listed in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) files contain plugin-specific configurations, [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/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.