How Plugins Are Structured and Managed in the PM Skills Marketplace

PM Skills Marketplace plugins are self-contained directories that follow a standardized layout comprising a JSON manifest, markdown-based skills with YAML front-matter, command definitions, and required documentation sections, all validated by automated checks before merging.

The PM Skills Marketplace is a curated collection of Claude-Code plugins designed for product management workflows. Each plugin resides in its own top-level directory within the phuryn/pm-skills repository and adheres to a machine-readable structure that enables automated validation and discovery. Understanding this architecture is essential for contributing new functionality or customizing existing plugins.

Plugin Directory Structure

Every plugin in the marketplace follows an identical layout to ensure consistency across the ecosystem.

The Manifest File

Each plugin must contain a plugin.json file located at .claude-plugin/plugin.json relative to the plugin root. This manifest declares the plugin's metadata including name, version, description, author, keywords, and license. According to the source code in validate_plugins.py, the validator checks that the plugin name matches the directory name and that the version follows semantic versioning (x.y.z) format.

Skills Directory

Skills are defined in markdown files stored under skills/<skill-name>/SKILL.md. Each file must include a YAML front-matter block specifying the name and description fields, followed by the skill logic, inputs, and output format documentation. For example, pm-toolkit/skills/review-resume/SKILL.md defines the resume review functionality with the required front-matter headers.

Commands Directory

Commands expose a command-line-style interface used by Claude, accessible via the syntax /plugin-name:command. These are defined in commands/<command-name>.md files and must include YAML front-matter with at least a description field and optionally an argument-hint field. The validator parses these files to ensure they reference valid skills within the same plugin.

README Documentation

Every plugin must include a README.md file containing specific required sections: overview, install, skill, and command. The validate_plugins.py script checks for the presence of these sections to ensure users have complete documentation before the plugin can be merged.

Marketplace Index and Discovery

All plugins are cataloged in a central marketplace manifest located at .claude-plugin/marketplace.json. Each entry contains the plugin name, description, source directory path, and category classification. This file serves as the authoritative source for the marketplace UI and command-line interfaces, enabling users to discover available plugins across the repository.

Validation and Quality Assurance

Before any plugin can be published, the repository runs validate_plugins.py to enforce structural integrity. The validator performs the following checks:

• Schema validation: Verifies that plugin.json contains all required fields including matching directory names, valid semantic versions, author fields, and keywords
• Skill verification: Ensures each SKILL.md file exists and contains valid YAML front-matter with name and description fields
• Command validation: Confirms command files include proper front-matter with descriptions and valid cross-references to existing skills
• Documentation completeness: Checks that README files contain the four required sections (overview, install, skill, command)

If validation fails, the CI pipeline blocks the merge, ensuring the marketplace maintains high quality standards.

Managing the Plugin Lifecycle

Adding New Plugins

To contribute a new plugin, create a top-level directory with the plugin name, add the .claude-plugin/plugin.json manifest, populate the skills/ and commands/ directories with properly formatted markdown files, and write a compliant README. Run python validate_plugins.py locally before submitting to ensure compliance with marketplace requirements.

Updating Existing Plugins

When modifying an existing plugin, increment the version field in plugin.json following semantic versioning principles. Update descriptions or documentation as needed, then execute the validator. The repository's CI automatically synchronizes the central marketplace.json file when individual plugin versions change.

Removing Plugins

To remove a plugin, delete its directory and remove the corresponding entry from .claude-plugin/marketplace.json. The validator will flag any dangling references in other plugins that might depend on the removed functionality.

Working with Plugin Files

Loading a Plugin Manifest

import json
import pathlib

def load_manifest(plugin_name: str) -> dict:
    manifest_path = pathlib.Path(plugin_name) / ".claude-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

pm_toolkit = load_manifest("pm-toolkit")
print(pm_toolkit["description"])

# → PM utility skills: resume review, NDA drafting, …

Calling Plugin Commands

Users interact with plugins through Claude using the command syntax:

/pm-toolkit:review-resume $RESUME="…your text…" $JOB_POSTING="…"

This triggers the review-resume skill defined in pm-toolkit/skills/review-resume/SKILL.md.

Listing Available Plugins

import { readFile } from 'fs/promises';
import path from 'path';

async function listPlugins() {
  const data = await readFile(
    path.resolve('.claude-plugin/marketplace.json'), 'utf8'
  );
  const { plugins } = JSON.parse(data);
  return plugins.map(p => p.name);
}

listPlugins().then(console.log);
// → [ 'pm-product-discovery', 'pm-product-strategy', … ]

Summary

• PM Skills Marketplace plugins are self-contained directories under the repository root with a standardized five-component structure
• Required files include .claude-plugin/plugin.json, skills/*/SKILL.md, commands/*.md, and README.md with specific required sections
• Validation occurs through validate_plugins.py, which checks schemas, YAML front-matter, cross-references between commands and skills, and documentation completeness
• Discovery happens through .claude-plugin/marketplace.json, which serves as the centralized catalog for the UI and CLI
• Versioning follows semantic versioning (x.y.z) and must be updated when modifying existing plugins, triggering automatic marketplace synchronization

Frequently Asked Questions

What happens if my plugin fails validation?

The validate_plugins.py script prints specific error messages indicating which checks failed. Common issues include missing required fields in plugin.json, malformed YAML front-matter in skills or commands, missing README sections, or invalid cross-references between commands and non-existent skills. The CI pipeline will block merging until all errors are resolved and the structure conforms to marketplace standards.

Can I include assets like images in my plugin?

Yes, while not required for marketplace validation, you may include optional assets such as images, examples, or tests within your plugin directory. These files help users understand and utilize your plugin but are not validated by the automated checks, allowing flexibility in documentation and demonstration materials.

How does the marketplace stay synchronized with individual plugin changes?

The repository's CI pipeline automatically updates .claude-plugin/marketplace.json when detecting version changes in individual plugin manifests. You only need to manually update the marketplace file when adding or removing entire plugins; version bumps in existing plugin.json files are handled automatically by the validation workflow.

What is the relationship between commands and skills?

Commands provide the user-facing interface accessible via /plugin:command syntax, while skills contain the actual implementation logic. Each command must reference a skill that exists within the same plugin directory, creating a binding between the CLI interface and the underlying functionality defined in the SKILL.md files. The validator enforces this relationship to ensure all commands point to valid implementations.

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