Contributing to the PM Skills Marketplace: A Developer Guide to Adding Skills and Commands

Fork the repository, create a skill under the appropriate plugin directory, validate with validate_plugins.py, and submit a PR with a changelog entry.

The PM Skills Marketplace is a modular collection of product management frameworks hosted in the phuryn/pm-skills repository. Each plugin contains reusable AI skills and slash commands that integrate with Claude Code and Claude Cowork, making it easy for product managers to access structured methodologies like Opportunity-Solution Trees or Go-to-Market strategies.

Understanding the Repository Architecture

The repository follows a plugin-based architecture where nine distinct domains (e.g., product discovery, go-to-market, AI shipping) each maintain their own isolated skill sets.

Plugin Structure

Each top-level directory represents a plugin (e.g., pm-product-discovery/, pm-go-to-market/, pm-toolkit/). Inside every plugin, you will find:

• skills/ – Contains subdirectories for individual frameworks, each holding a SKILL.md file
• commands/ – Houses slash-command definitions (e.g., discover.md, plan-launch.md) that chain multiple skills into workflows
• .claude-plugin/plugin.json – The manifest file describing plugin metadata, version, and compatibility

Core Components

Every skill follows the universal SKILL.md format recognized by Claude Code. These markdown files must include YAML front-matter with name and description fields:

---
name: example-framework
description: A concise description of the framework.
---

# Example Framework

Detailed guidance for the AI assistant...

The validate_plugins.py script enforces structural consistency across all plugins, checking for manifest version alignment, required front-matter fields, and command syntax validity.

Setting Up Your Development Environment

Start by forking and cloning the repository to your local machine:

git clone https://github.com/your-username/pm-skills.git
cd pm-skills
git checkout -b feature/add-my-skill

Install Python dependencies if you plan to run the validation suite locally, though the repository only requires standard Python 3 for the validator.

How to Add a New Skill to the Marketplace

Creating a new skill involves three concrete steps: directory creation, content writing, and manifest updating.

Step 1: Create the Skill Directory

Navigate to the appropriate plugin and create a new skill folder:

mkdir -p pm-product-strategy/skills/my-new-framework

Step 2: Write the SKILL.md File

Create the SKILL.md file with proper front-matter. The file path should follow the pattern: pm-<domain>/skills/<skill-name>/SKILL.md.

---
name: my-new-framework
description: A framework for evaluating product opportunities through structured ideation.
---

# My New Framework

## Overview

This framework helps product teams...

## Usage Instructions

1. Step one...
2. Step two...

Step 3: Update the Plugin Manifest

If you added a new command or modified plugin metadata, increment the version field in the plugin's plugin.json file to maintain consistency with the marketplace release cycle:

File path: pm-product-strategy/.claude-plugin/plugin.json

{
  "name": "pm-product-strategy",
  "version": "1.2.0",
  "description": "Product strategy frameworks"
}

Validating Your Contribution

Before submitting, run the validation script to catch structural errors early:

python3 validate_plugins.py

The validator checks for:

• Missing front-matter in SKILL.md files
• Version mismatches between plugin manifests
• Malformed command definitions

Follow up with the test suite to ensure no regressions:

python3 -m unittest discover -s tests

Both commands must pass before your pull request can be merged.

Submitting Your Pull Request

Commit your changes with a clear message and push to your fork:

git add .
git commit -m "Add My New Framework skill"
git push origin feature/add-my-skill

Open a Pull Request on GitHub and update CHANGELOG.md under the Unreleased heading:

## Unreleased

- Add My New Framework skill (#123, thanks @your-handle)

The CI workflow automatically executes validate_plugins.py and the test suite; upon success, maintainers will merge and trigger a new release.

Summary

• The PM Skills Marketplace uses a plugin architecture with SKILL.md files and plugin.json manifests
• Each skill requires YAML front-matter with name and description fields
• Run python3 validate_plugins.py before submitting to check for structural errors
• Update the CHANGELOG.md under Unreleased with your contribution details
• The test suite in tests/ validates plugin compatibility and marketplace integrity

Frequently Asked Questions

What is the required format for a SKILL.md file?

Every SKILL.md must begin with YAML front-matter containing the name and description keys, followed by standard markdown content. The file resides in pm-<domain>/skills/<skill-name>/SKILL.md and validates against the marketplace schema using validate_plugins.py.

How do I update the plugin version when adding a new command?

Increment the version field in the plugin's .claude-plugin/plugin.json file using semantic versioning. This ensures Claude Code and Claude Cowork receive the updated manifest when the marketplace releases a new version.

What does the validate_plugins.py script check?

The script enforces manifest version consistency across all plugins, verifies the presence of required front-matter fields in each SKILL.md, and validates command definition syntax. It runs automatically in CI but should be executed locally before committing.

Where should I add changelog entries for my contribution?

Add a bullet point under the Unreleased heading in CHANGELOG.md at the repository root, following the format - Description (#PR-number, thanks @your-handle). This file serves as the source of truth for release notes and version history.

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