# How to Contribute to the phuryn/pm-skills Project: A Complete Guide

> Learn how to contribute to the phuryn/pm-skills project. Follow this guide to fork the repo, add new skills, update READMEs, validate, and submit a pull request easily.

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

---

**To contribute to the phuryn/pm-skills project, fork the repository, create a new skill markdown file under the appropriate plugin's `skills/` directory, update the README count tables, run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) to ensure consistency, and submit a pull request following the template in `.github/`.**

The **phuryn/pm-skills** repository is an open-source marketplace of AI-driven product management plugins designed for Claude and other AI assistants. It organizes reusable knowledge into nine distinct plugins covering domains like discovery, strategy, and execution. Understanding how to contribute to this project requires familiarity with its modular architecture of skills and commands.

## Understanding the Repository Architecture

### Core Concepts

The repository is built around three fundamental concepts that define how contributions should be structured:

- **Skill**: A markdown file ([`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)) that defines a single PM framework, analysis, or utility. Skills are loaded automatically by Claude when a relevant prompt is detected. Each skill lives in `pm-<area>/skills/*/SKILL.md` (for example, [`pm-product-discovery/skills/brainstorm-ideas-existing/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/skills/brainstorm-ideas-existing/SKILL.md)).
- **Command**: A markdown file (`*.md`) that describes a slash-command (such as `/discover` or `/write-prd`) and specifies the ordered list of skills it invokes. Commands serve as explicit entry points for users and reside in `pm-<area>/commands/`.
- **Plugin**: A folder bundling related skills and commands. The repository contains nine plugins: discovery, strategy, execution, market-research, data-analytics, marketing-growth, go-to-market, toolkit, and AI-shipping.

### Repository Layout

```

/README.md                ← high-level overview, installation, plugin list
/CONTRIBUTING.md          ← contribution guidelines
/CLAUDE.md                ← internal guidelines for keeping README/plugin sync
/pm-<area>/               ← plugin directories (e.g., pm-toolkit, pm-execution)
    ├─ skills/            ← individual skill folders, each with SKILL.md
    └─ commands/          ← command markdown files
/validate_plugins.py      ← validation script for CI pipeline

```

## Step-by-Step Contribution Workflow

### 1. Review the Contribution Guidelines

Before writing code, read [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) to understand the PR process, code-style expectations, and the requirement to keep counts in the top-level README synchronized with any added or removed skills or commands. The [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) file provides additional internal rules for maintaining alignment between README and plugin metadata.

### 2. Create a New Skill

To add a new skill, create a folder under the appropriate plugin's `skills/` directory and provide a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) following the universal format:

```markdown

# my-new-skill/SKILL.md

## Title

My New Skill – concise description

## Description

Explain the framework, when to use it, and any required inputs.

## Example Prompt

`What are the top three risks for launching a new SaaS product?`

```

Place the folder under the relevant plugin path, such as `pm-execution/skills/my-new-skill/`.

### 3. Add a Command (Optional)

If your skill should be accessible via a slash-command, add a markdown file under `pm-<area>/commands/` that lists the skill chain in execution order. Update the plugin's command count in the top-level README to reflect the addition.

### 4. Validate Your Changes

After committing your changes, run the validation script to ensure consistency:

```bash
python validate_plugins.py

```

This script checks that every plugin has a `README`, a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json), and that the skill/command counts in the main [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) match the actual directory contents. The CI pipeline runs this automatically on pull requests, and it will warn if counts diverge.

### 5. Submit a Pull Request

Submit a PR using the template in `.github/` (not shown in the source analysis but referenced in workflow documentation). Include a brief description, testing steps, and verification that the new skill or command works in Claude.

## Working with Skills and Commands

### Skill Structure (SKILL.md)

Skills are independent markdown assets. The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file must include a clear title, detailed description, and example prompts. For reference, examine [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), which demonstrates proper formatting for a resume review utility.

### Command Structure

Commands reference skills by name, allowing reuse across multiple plugins. A command file chains skills into end-to-end workflows. For example, the `/discover` command chains four skills (brainstorm-ideas, identify-assumptions, prioritize-assumptions, brainstorm-experiments) to run a complete discovery workflow.

## Cross-Assistant Compatibility

While the primary runtime is Claude, the same `skills/*/SKILL.md` files work with Gemini, OpenCode, Cursor, and Kiro. To use skills with a non-Claude assistant, copy them into the respective assistant's skills folder:

```bash
for plugin in pm-*/; do
  mkdir -p .opencode/skills/
  cp -r "$plugin/skills/"* .opencode/skills/ 2>/dev/null
done

```

This script gathers all skill markdown files into the OpenCode skills directory, maintaining compatibility across AI platforms.

## Summary

- **Fork and read**: Start with [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) and [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) to understand requirements.
- **Create skills**: Add [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files under `pm-<area>/skills/` following the standard format.
- **Add commands**: Place command definitions in `pm-<area>/commands/` and update README counts.
- **Validate**: Run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) to ensure README counts match actual plugin contents.
- **Submit**: Use the PR template and verify functionality in Claude before requesting review.

## Frequently Asked Questions

### What is the difference between a skill and a command in pm-skills?

A **skill** is a reusable knowledge module defined in a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file that provides a specific PM framework or analysis, while a **command** is a user-facing entry point (like `/discover`) that chains multiple skills together into an end-to-end workflow. Skills are the building blocks; commands are the workflows.

### How do I validate my contribution before submitting a PR?

Run `python validate_plugins.py` from the repository root. This script checks that every plugin directory contains a `README` and [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json), and verifies that the skill and command counts listed in the top-level [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) match the actual number of files in each plugin's `skills/` and `commands/` directories.

### Can I use pm-skills skills with assistants other than Claude?

Yes. While the primary runtime is Claude, the markdown-based skill files are compatible with Gemini, OpenCode, Cursor, and Kiro. Copy the skill files from `pm-*/skills/` into your assistant's specific skills directory (such as `.gemini/skills/` or `.opencode/skills/`) to use them across platforms.

### Where should I place new skills in the repository structure?

Place new skills under the appropriate plugin directory following the pattern `pm-<area>/skills/<skill-name>/SKILL.md`. Choose the plugin that best matches the domain (e.g., `pm-execution` for PRD-related skills, `pm-product-discovery` for ideation frameworks) to maintain logical organization.