# How Plugins Are Structured and Managed in the PM Skills Marketplace

> Discover how PM Skills Marketplace plugins are structured and managed. Learn about standardized layouts, manifest files, skills, commands, and documentation for easy integration and automation.

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

---

**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`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)** file located at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/README.md)** file containing specific required sections: `overview`, `install`, `skill`, and `command`. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** to enforce structural integrity. The validator performs the following checks:

- **Schema validation**: Verifies that [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) contains all required fields including matching directory names, valid semantic versions, author fields, and keywords
- **Skill verification**: Ensures each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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

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

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

```

This triggers the **review-resume** skill defined in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md).

### Listing Available Plugins

```javascript
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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json), `skills/*/SKILL.md`, `commands/*.md`, and [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) with specific required sections
- **Validation** occurs through [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script prints specific error messages indicating which checks failed. Common issues include missing required fields in [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files. The validator enforces this relationship to ensure all commands point to valid implementations.