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

The marketplace.json file is a JSON descriptor located at .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 manifest in your plugin's .claude-plugin directory and append an entry to the plugins array in 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 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 file inside a .claude-plugin subdirectory:

{
  "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": "[email protected]"
  }
}

Reference the existing 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.

Step 3: Register in marketplace.json

Open .claude-plugin/marketplace.json and append your plugin to the plugins array:

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

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:

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 manifest inside a .claude-plugin directory
• Registration involves appending an entry to the plugins array in .claude-plugin/marketplace.json
• Use 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 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 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. This convention matches the existing structure seen in pm-toolkit/.claude-plugin/plugin.json.

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