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

> Learn how to contribute to the PM Skills Marketplace by adding new skills and commands. This guide covers forking the repository, creating skills, validation, and submitting a pull request.

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

---

**Fork the repository, create a skill under the appropriate plugin directory, validate with [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file
- **`commands/`** – Houses slash-command definitions (e.g., [`discover.md`](https://github.com/phuryn/pm-skills/blob/main/discover.md), [`plan-launch.md`](https://github.com/phuryn/pm-skills/blob/main/plan-launch.md)) that chain multiple skills into workflows
- **[`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json)** – The manifest file describing plugin metadata, version, and compatibility

### Core Components

Every skill follows the universal [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) format recognized by Claude Code. These markdown files must include YAML front-matter with `name` and `description` fields:

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

# Example Framework

Detailed guidance for the AI assistant...

```

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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:

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

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

```

### Step 2: Write the SKILL.md File

Create the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with proper front-matter. The file path should follow the pattern: `pm-<domain>/skills/<skill-name>/SKILL.md`.

```markdown
---
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`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) file to maintain consistency with the marketplace release cycle:

*File path:* [`pm-product-strategy/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/.claude-plugin/plugin.json)

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

```bash
python3 validate_plugins.py

```

The validator checks for:
- Missing front-matter in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files
- Version mismatches between plugin manifests
- Malformed command definitions

Follow up with the test suite to ensure no regressions:

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

```bash
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`](https://github.com/phuryn/pm-skills/blob/main/CHANGELOG.md) under the **Unreleased** heading:

```markdown

## Unreleased

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

```

The CI workflow automatically executes [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files and [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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.