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

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 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) 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).
• 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 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 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 following the universal format:

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

python validate_plugins.py

This script checks that every plugin has a README, a plugin.json, and that the skill/command counts in the 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 file must include a clear title, detailed description, and example prompts. For reference, examine 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:

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 and CLAUDE.md to understand requirements.
• Create skills: Add 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 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 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, and verifies that the skill and command counts listed in the top-level 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.

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