How to Contribute a New Skill to phuryn/pm-skills: A Complete Guide

To contribute a new skill to phuryn/pm-skills, open an issue to discuss the scope, create a kebab-case directory with a SKILL.md file containing required YAML front-matter, validate locally with validate_plugins.py, and submit a focused pull request.

The pm-skills repository organizes product management expertise into modular skills and commands. If you want to expand this open-source marketplace with new domain knowledge, following the canonical contribution workflow ensures your submission passes automated validation and review. This guide walks through the exact steps required to add a skill, from initial issue creation to final merge.

Understanding the Repository Structure

Before writing content, you must understand how the repository organizes its components.

Skills vs. Commands

The repository maintains a strict separation between two content types:

• Skills – Static knowledge modules stored as markdown files with YAML front-matter. These live in category directories like pm-toolkit/skills/, pm-product-strategy/skills/, or pm-market-research/skills/. Each skill occupies its own subdirectory containing a single SKILL.md file.
• Commands – Reusable CLI-style workflow scripts stored in pm-toolkit/commands/. These represent actions rather than knowledge.

Skills are nouns representing domain expertise (e.g., grammar-check, market-sizing), while commands are verbs describing actions (e.g., privacy-policy). This naming convention keeps the marketplace discoverable and intuitive.

The Validator Script

The validate_plugins.py script enforces structural rules across the repository. According to the source code, this validator checks:

• Front-matter field presence and validity
• Naming conventions and directory alignment
• Markdown formatting standards

All contributions must pass this validation before maintainers can merge your pull request.

Step-by-Step Contribution Process

1. Open an Issue First

Because a new skill constitutes a larger architectural change, start by opening a GitHub issue to discuss scope and design. The CONTRIBUTING.md file explicitly requires this step for "new skills, commands, or larger changes" to ensure alignment with project goals before you invest development time.

2. Create the Skill Directory

Choose the appropriate category folder (e.g., pm-toolkit/skills/). Create a new subdirectory using kebab-case naming that matches your skill's intended name. For example, a market sizing skill would live at pm-market-research/skills/market-sizing/.

This directory must contain exactly one file: SKILL.md.

3. Add Required Front-Matter

Every SKILL.md must begin with a YAML block containing two mandatory fields:

---
name: market-sizing
description: Guidance on estimating market size for a product.
---

Critical: The name field must exactly match the directory name. The validator enforces this rule to ensure the marketplace UI can correctly index and display your skill.

4. Write Skill Content

After the front-matter, add instructional text, examples, and tables using standard markdown. Reference existing skills like pm-toolkit/skills/grammar-check/SKILL.md for style consistency. Remember that commands cannot directly reference other plugins; any coordination should be expressed in natural language within the skill description.

5. Validate Locally

Before committing, run the validation script from the repository root:

python3 validate_plugins.py

The script outputs conformance status for all skill files. If you see errors like missing front-matter fields or naming mismatches, correct them before proceeding.

6. Submit a Pull Request

Push your branch to GitHub and open a pull request. Follow the project's PR guidelines: one logical change per request, clear descriptive title, and concise explanation of the expertise your skill adds. Maintainers will run the CI validator, review content accuracy, and merge after any necessary feedback.

Anatomy of a SKILL.md File

Here is a complete, valid example for a new skill. Save this as pm-market-research/skills/market-sizing/SKILL.md:

---
name: market-sizing
description: Guidance on estimating market size for a product.
---

# Market Sizing

This skill walks you through a structured approach to calculate TAM, SAM, and SOM.

## Steps

1. **Define the total addressable market (TAM)** – Identify the overall revenue potential.
2. **Segment the serviceable market (SAM)** – Narrow down to the portion you can realistically serve.
3. **Calculate the share of market (SOM)** – Estimate the percentage you expect to capture.

### Example Calculation

| Segment | Revenue (USD) |
|---------|---------------|
| TAM     | $10 B         |
| SAM     | $2 B          |
| SOM     | $200 M        |

> Use the above numbers as a starting point and refine based on your product specifics.

Running the Validator Locally

Execute the validator to ensure your contribution meets schema requirements:

$ python3 validate_plugins.py
✔ All skill files conform to the required schema.

If the validator reports errors, adjust your front-matter or file placement accordingly. Common failures include mismatched name fields or missing description values.

Key Files and References

• CONTRIBUTING.md – The official contribution guide detailing naming rules and validator usage.
• validate_plugins.py – The Python script enforcing front-matter and naming conventions.
• pm-toolkit/skills/grammar-check/SKILL.md – A reference implementation showing correct skill structure.

Summary

• Open an issue first for new skills to align on scope and design.
• Create a kebab-case directory matching your skill name and add a SKILL.md file with required YAML front-matter.
• Ensure the name field in front-matter matches the directory name exactly.
• Run python3 validate_plugins.py locally before submitting your pull request.
• Submit focused PRs with clear descriptions to streamline the review process.

Frequently Asked Questions

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

Skills are noun-based knowledge modules (like market-sizing or grammar-check) stored in skills/ directories, while commands are verb-based action scripts stored in commands/ directories. This distinction maintains clear separation between domain knowledge and executable workflows.

Why must I open an issue before contributing a new skill?

The CONTRIBUTING.md requires issues for substantial changes like new skills to prevent wasted effort and ensure architectural alignment. Discussing scope upfront allows maintainers to suggest category placement and validate that the proposed skill fits the project's coverage goals.

What happens if the validator fails when I run validate_plugins.py?

The script will output specific error messages indicating which files violate the schema—commonly missing front-matter fields, naming mismatches between directory and YAML name values, or malformed markdown. Fix these issues locally and re-run the validator until you see the success message.

Can I reference other skills within my skill content?

No. The architecture prohibits direct cross-plugin references. Instead, express relationships or workflows in natural language within your skill's descriptive text, describing how your knowledge module relates to other product management concepts without technical linking.

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