# How to Contribute to phuryn/pm-skills: A Complete Guide to the Product Management Plugin Marketplace

> Learn how to contribute to phuryn/pm-skills. Follow our guide to fork, validate, and submit pull requests for the product management plugin marketplace.

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

---

**Contribute to phuryn/pm-skills by forking the repository, creating a topic branch, running `python3 validate_plugins.py` to validate structural integrity, and submitting a pull request that synchronizes version numbers across all [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifests and [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json).**

The **phuryn/pm-skills** repository is a decentralized marketplace comprising 9 independent plugins that collectively expose 68 skills and 42 commands for product management workflows. Each plugin operates within its own top-level `pm-{area}` directory (such as `pm-execution` or `pm-go-to-market`), making the architecture deliberately modular so that individual components can be installed or upgraded without affecting the broader ecosystem. When you contribute to phuryn/pm-skills, you are adding to a system where **skills** (noun-oriented knowledge modules) and **commands** (verb-oriented workflows) are defined by Markdown files with strict front-matter requirements governed by the **[CLAUDE.md](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** specification.

## Understanding the Repository Architecture

### Modular Plugin Structure

The repository organizes functionality into self-contained plugins under directories named `pm-{area}` (e.g., `pm-execution`, `pm-go-to-market`). Each plugin ships with a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest, a [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) description, and two critical subdirectories:

- **`skills/`** – Contains knowledge modules as [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files that Claude auto-loads based on trigger phrases.
- **`commands/`** – Contains verb-oriented workflows as `*.md` files that chain skills together via a single `$ARGUMENTS` placeholder.

This modularity ensures that installing, upgrading, or removing one plugin never affects the others.

### Core Configuration Files

Several files govern contribution quality and marketplace integration:

| File | Purpose |
|------|---------|
| **[`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md)** | Step-by-step workflow, style guidelines, and validator usage. |
| **[`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** | Architectural blueprint defining naming conventions, versioning rules, and post-change procedures. |
| **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** | CLI validator that checks manifests, front-matter, naming consistency, and intra-plugin references. |
| **[`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)** | Root marketplace manifest listing all 9 plugins and their versions. |
| **`pm-{plugin}/.claude-plugin/plugin.json`** | Per-plugin metadata (description, author, keywords, version). |

## Step-by-Step Contribution Workflow

### 1. Fork and Clone the Repository

```bash
git clone https://github.com/your-username/pm-skills.git
cd pm-skills

```

### 2. Create a Topic Branch

Use descriptive branch names that reflect the single change you intend to make:

```bash
git checkout -b fix-typo-readme

```

### 3. Make Changes Following Structural Rules

According to **[CONTRIBUTING.md](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md)**, observe these constraints:

- **Skills** must reside in a directory-name-matched folder within `pm-{plugin}/skills/` and include a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with front-matter containing `name` and `description`.
- **Commands** must include front-matter with `description` and `argument-hint` in their `pm-{plugin}/commands/*.md` files.
- Never create cross-plugin command references; use natural-language suggestions only.

### 4. Run the Validator

Execute the structural integrity checker before committing:

```bash
python3 validate_plugins.py

```

This script flags missing fields, mismatched names, version inconsistencies, or broken intra-plugin references. Resolve all errors before proceeding.

### 5. Update Counts and Versions

If your contribution adds or deletes skills or commands:

- Update the totals in **[README.md](https://github.com/phuryn/pm-skills/blob/main/README.md)** (section "Available Plugins").
- Sync the plugin description in the corresponding `pm-{plugin}/.claude-plugin/plugin.json` and the marketplace description in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json).
- Bump the version number across **all** [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) files and the marketplace file according to the *Versioning* rules in **[CLAUDE.md](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)**.

### 6. Commit and Push

```bash
git add .
git commit -m "Fix typo in pm-execution README"
git push origin fix-typo-readme

```

### 7. Open a Pull Request

Target the upstream `main` branch. Include a brief description of changes and reference any related issue numbers. The CI system will re-run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py); a passing check is mandatory for merge approval.

### 8. Review and Merge

Repository maintainers will review your PR. Once approved, the merge triggers publication of the new version to the marketplace.

## Practical Code Examples for Contributors

### Adding a New Skill

To add a **roadmap-visualization** skill to the `pm-execution` plugin:

```bash

# 1️⃣ Create the folder structure

mkdir -p pm-execution/skills/roadmap-visualization

# 2️⃣ Create SKILL.md with required front-matter

cat > pm-execution/skills/roadmap-visualization/SKILL.md << 'EOF'
---
name: roadmap-visualization
description: Generate a visual roadmap from a list of outcomes and timelines.
---
The skill accepts a plain-text list of outcomes and dates, then returns a Mermaid diagram...
EOF

# 3️⃣ Validate the structure

python3 validate_plugins.py

```

### Updating a Command's Argument Hint

Edit the command file to adjust user-facing hints:

```markdown
---
description: Create a PRD from a feature idea or problem statement
argument-hint: "<feature-title> — <short-description>"
---

```

After editing, run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) and update the README command count if the total number of commands changed.

### Bumping Versions Across the Marketplace

When releasing a new version (e.g., from `2.0.0` to `2.0.1`), update all manifests simultaneously:

```bash

# Update each plugin's manifest

sed -i 's/"2\.0\.0"/"2.0.1"/g' pm-*/.claude-plugin/plugin.json

# Update the root marketplace manifest

sed -i 's/"2\.0\.0"/"2.0.1"/g' .claude-plugin/marketplace.json

git commit -am "Bump all plugin versions to 2.0.1"

```

## Summary

- **phuryn/pm-skills** uses a modular architecture where 9 independent plugins contain skills in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files and commands in `*.md` files.
- Always run **`python3 validate_plugins.py`** locally before submitting a pull request to ensure structural compliance.
- Maintain version consistency by updating **all** `pm-{plugin}/.claude-plugin/plugin.json` files and [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) when bumping versions.
- Follow the front-matter requirements in **[CLAUDE.md](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** for both skills (`name`, `description`) and commands (`description`, `argument-hint`).
- Keep pull requests focused on single changes and update the README plugin counts when adding or removing functionality.

## Frequently Asked Questions

### What is the purpose of the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script?

The **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** script serves as the single source of truth for structural correctness in the phuryn/pm-skills repository. It checks for missing front-matter fields in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) and command files, mismatched directory names, version inconsistencies between [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifests and the marketplace root, and broken intra-plugin references. Running this script locally before pushing ensures your contribution passes the mandatory CI checks required for merge approval.

### How do I structure a new skill for the pm-skills marketplace?

Create a new directory under `pm-{plugin}/skills/` that matches the skill's system name (e.g., `pm-execution/skills/create-prd/`). Inside this directory, create a **[`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)** file containing a YAML front-matter block with `name` and `description` fields, followed by the skill's body content. The skill name must match the directory name exactly, and the description should explain what noun-oriented knowledge the skill provides to agent systems like Claude.

### Where do I update version numbers when contributing to phuryn/pm-skills?

You must synchronize version numbers across multiple files simultaneously. Update the `version` field in every **`pm-{plugin}/.claude-plugin/plugin.json`** file (all 9 plugins), and update the corresponding version in the root **[`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)**. The **[CLAUDE.md](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** file specifies that version bumps must be atomic across the entire marketplace to maintain consistency, even if you only modified one plugin.

### Can I reference commands from other plugins in my contribution?

No. The architecture explicitly forbids cross-plugin command references. Commands within `pm-{plugin}/commands/*.md` must only reference skills available within the same plugin directory. If you need to suggest functionality from another plugin, use natural-language suggestions in the command description rather than programmatic references or links. This isolation preserves the modular integrity that allows individual plugins to be installed, upgraded, or removed independently.