# Understanding the marketplace.json Schema in pm-skills: How to Add a New Plugin

> Learn about the marketplace.json schema to register Claude plugins. Discover how to add a new plugin with a simple plugin.json manifest. Get started today.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-06-24

---

**The [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) file is a JSON descriptor located at [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) that registers Claude plugins by listing their names, descriptions, repositories, and paths; to add a new plugin, create a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest in your plugin's `.claude-plugin` directory and append an entry to the `plugins` array in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json).**

The `pm-skills` repository provides a collection of Claude plugins for product management workflows. At the heart of this system lies the **marketplace.json schema**, a lightweight JSON structure that tells Claude where to find and how to load individual plugins. Understanding this schema is essential for extending the collection with custom capabilities.

## Understanding the marketplace.json Schema

The central registry file [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) follows a straightforward structure designed to be machine-readable and human-maintainable.

### Top-Level Fields

The root object contains metadata about the marketplace itself:

- `name`: Human-readable identifier (e.g., `pm-skills`)
- `description`: Brief summary of the collection
- `author`: Object containing `name`, `email`, and `url`
- `plugins`: Array of plugin descriptor objects

### Plugin Object Structure

Each object in the `plugins` array requires specific fields:

- `name`: Display name of the plugin
- `description`: One-sentence summary of functionality
- `repo`: URL to the GitHub repository
- `path`: Relative path to the plugin root (typically `.<folder>/.claude-plugin`)
- `version` (optional): Semantic version string
- `author` (optional): Override author information for specific plugins

## How to Add a New Plugin to the pm-skills Marketplace

Adding a plugin requires creating a local manifest and registering it in the central marketplace file.

### Step 1: Create the Plugin Directory and Manifest

Create a new folder for your plugin (e.g., `pm-my-plugin/`) and add a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) file inside a `.claude-plugin` subdirectory:

```json
{
  "name": "pm-my-plugin",
  "description": "Your custom PM helper.",
  "repo": "https://github.com/phuryn/pm-skills",
  "path": "pm-my-plugin/.claude-plugin",
  "version": "0.1.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  }
}

```

Reference the existing [`pm-toolkit/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json) for a working example of the expected structure.

### Step 2: Add Supporting Files

Place any additional plugin assets (prompts, schemas, or configuration files) inside the `pm-my-plugin/.claude-plugin/` directory alongside the [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json).

### Step 3: Register in marketplace.json

Open [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) and append your plugin to the `plugins` array:

```json
{
  "name": "pm-my-plugin",
  "description": "Your custom PM helper.",
  "repo": "https://github.com/phuryn/pm-skills",
  "path": "pm-my-plugin/.claude-plugin"
}

```

The repository already contains entries for built-in plugins like `pm-product-discovery` and `pm-product-strategy` in this same format.

### Step 4: Validate Your Configuration

Run the validation script to ensure your JSON conforms to the expected schema:

```bash
python validate_plugins.py

```

Successful execution indicates the plugin is correctly described and ready for integration.

### Step 5: Commit and Push

Stage your changes and push to the repository:

```bash
git add .
git commit -m "Add pm-my-plugin to marketplace"
git push

```

Claude will automatically discover the new plugin on the next marketplace load.

## Summary

- The **marketplace.json schema** requires `name`, `description`, `repo`, and `path` fields for each plugin entry
- Each plugin must maintain its own [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest inside a `.claude-plugin` directory
- Registration involves appending an entry to the `plugins` array in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)
- Use [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) to verify schema compliance before committing
- Claude automatically detects new plugins after changes are pushed to the repository

## Frequently Asked Questions

### What are the minimum required fields for marketplace.json entries?

Claude requires only four fields to locate and load a plugin: `name`, `description`, `repo`, and `path`. While `version` and `author` are optional, including them improves traceability and version management.

### Can I add plugins from external repositories?

Yes. The `repo` field accepts any valid GitHub URL, allowing you to reference plugins hosted outside the `phuryn/pm-skills` repository. Simply set the `repo` field to the external repository URL and ensure the `path` points to the correct `.claude-plugin` directory within that repository.

### How does Claude discover new plugins after I update marketplace.json?

Claude loads the [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) file from the repository root and parses the `plugins` array to identify available capabilities. When you push updates to the repository, Claude refreshes its plugin registry automatically, making new entries available immediately without manual intervention.

### Where should I place the plugin.json file within my plugin directory?

Each plugin must store its manifest at [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) inside a `.claude-plugin` folder at the plugin root. For example, if your plugin is named `pm-custom`, the full path should be [`pm-custom/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-custom/.claude-plugin/plugin.json). This convention matches the existing structure seen in [`pm-toolkit/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json).