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

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 manifests and .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 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 manifest, a README.md description, and two critical subdirectories:

• skills/ – Contains knowledge modules as 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	Step-by-step workflow, style guidelines, and validator usage.
CLAUDE.md	Architectural blueprint defining naming conventions, versioning rules, and post-change procedures.
validate_plugins.py	CLI validator that checks manifests, front-matter, naming consistency, and intra-plugin references.
.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

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:

git checkout -b fix-typo-readme

3. Make Changes Following Structural Rules

According to CONTRIBUTING.md, observe these constraints:

• Skills must reside in a directory-name-matched folder within pm-{plugin}/skills/ and include a 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:

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 (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.
• Bump the version number across all plugin.json files and the marketplace file according to the Versioning rules in CLAUDE.md.

6. Commit and Push

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; 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:

# 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:

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

After editing, run 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:

# 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 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 when bumping versions.
• Follow the front-matter requirements in 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 script?

The 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 and command files, mismatched directory names, version inconsistencies between 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 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. The 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.

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