# How to Contribute a New Skill to the PM‑Skills Marketplace

> Learn how to contribute a new skill to the PM-Skills Marketplace. Create a skill folder validate changes locally and submit a pull request to the phuryn/pm-skills repository.

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

---

**To contribute a new skill to the marketplace, create a dedicated folder containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with valid YAML front-matter inside the appropriate plugin's `skills/` directory, then validate your changes locally using [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) before opening a pull request.**

The PM‑Skills repository is an open-source collection of plugins that encapsulate domain-specific knowledge for product managers. If you want to contribute a new skill to the marketplace, you must follow the repository's strict validation rules enforced by the CI pipeline and the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script.

## Understanding the Plugin Architecture

The repository organizes functionality into **plugins** (such as `pm-toolkit`, `pm-product-discovery`, and `pm-market-research`), each grouping related **skills** (nouns representing domain knowledge) and **commands** (verbs that execute workflows). The available plugins are defined in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json), which serves as the central manifest listing all nine plugin directories. Before contributing, you must identify which existing plugin best matches your skill's domain, as all skills must reside within one of these nine official plugin directories.

## Step-by-Step Contribution Process

### Select the Correct Plugin

Navigate to [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) to review the available plugin directories. Choose the plugin that aligns with your skill's domain area. For example, a market-research skill belongs in `pm-market-research`, while general productivity tools belong in `pm-toolkit`. You cannot create top-level skills; they must be nested within a plugin's `skills/` subdirectory.

### Create the Skill Directory

Inside your chosen plugin's `skills/` directory, create a new folder named exactly as your skill identifier (e.g., `product-positioning`). According to [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 86-89), this folder name must identically match the `name` field you will specify in the skill's front-matter. Use kebab-case (lowercase with hyphens) for consistency with existing conventions.

### Write the SKILL.md File

Every skill requires a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file containing YAML front-matter followed by markdown content. The validator ([`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), lines 95-104) enforces that this front-matter includes at minimum the `name` and `description` fields. Additionally, lines 215-219 recommend including trigger phrases such as "use when" or "use for" in the description to improve discoverability.

Create the file using this template structure:

```bash
cd pm-toolkit/skills
mkdir product-positioning
cat > product-positioning/SKILL.md <<'EOF'
---
name: product-positioning
description: "Generate positioning statements for a new product. Use when you need to define target customers, primary needs, and unique value propositions based on market data."
---

# Product Positioning

You are a product manager tasked with crafting a concise positioning statement.

## Input Arguments

- $TARGET_CUSTOMER: Who benefits most?
- $PRIMARY_NEED: Core problem being solved
- $UNIQUE_VALUE: What makes the solution stand out

## Output

Return a one-sentence positioning statement.
EOF

```

### Validate Locally

Before submitting, run the validator from the repository root to ensure your skill passes all checks:

```bash
python3 validate_plugins.py

```

The script scans every plugin directory and reports errors, warnings, and notes for each skill and command. A clean run (zero errors) is required for CI to pass. If validation fails, you will see specific error messages indicating which front-matter fields are missing or malformed. For example:

```

 Plugin Collection Validator — Report
 ┌─ pm-toolkit  [4 skills, 4 commands]  ✓ PASS
   Skills with issues:
     product-positioning:
       ✗ ERROR: Missing required frontmatter field: description

```

Fix any reported errors before proceeding.

### Submit Your Contribution

As outlined in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) (lines 7-9), open an issue first if your skill adds significant new functionality or changes existing behavior. For straightforward additions, fork the repository, commit your new skill folder, and open a pull request focused on this single change. The PR should include a link to the new skill folder and a brief usage description. The maintainer will run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) and either request adjustments or merge your contribution.

## Validation Requirements and Best Practices

To ensure your contribution is accepted, adhere to these constraints enforced by the validator:

- **Front-matter fields**: Must include `name` and `description` keys with proper YAML formatting
- **Directory naming**: The folder name must exactly match the `name` value in front-matter (case-sensitive)
- **Trigger phrases**: Include "use when" or "use for" in descriptions to indicate activation contexts
- **No extra keys**: Do not add custom front-matter fields beyond the standard set
- **Single focus**: Keep each pull request limited to one skill or logical change

## Summary

- Skills in the PM‑Skills repository reside within plugin-specific `skills/` directories, not at the repository root
- You must create a folder named exactly as the skill identifier, containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with valid YAML front-matter including `name` and `description`
- The validator ([`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)) enforces folder-to-front-matter naming consistency (lines 86-89) and required field presence (lines 95-104)
- Run `python3 validate_plugins.py` locally to catch errors before submitting your pull request
- For significant changes, open an issue first per [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) (lines 7-9)

## Frequently Asked Questions

### What file naming convention should I follow for new skills?

Create a directory using kebab-case (lowercase words separated by hyphens) that matches exactly the `name` field in your [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter. For example, if your skill name is `customer-interview-guide`, the folder must be named `customer-interview-guide`. The validator checks this correspondence at lines 86-89 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) and will fail if they differ.

### Why does my skill fail validation even with correct front-matter?

Common failures include improper YAML syntax (such as unquoted descriptions containing colons), missing required fields, or extra custom keys in the front-matter. The validator at lines 95-104 checks for the exact schema. Ensure your description is properly quoted and includes recommended trigger phrases like "use when" (lines 215-219) to avoid warnings.

### Can I create a new plugin instead of adding to an existing one?

The marketplace manifest in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) defines the nine official plugin directories. You cannot create new top-level plugins without modifying this manifest, which requires maintainer approval. For most contributors, selecting the existing plugin that best fits your skill's domain is the correct approach.

### How do I test my skill before submitting a PR?

Run `python3 validate_plugins.py` from the repository root. This script performs the same checks as the CI pipeline, verifying that your skill's directory structure, front-matter fields, and naming conventions meet repository standards. A successful run with zero errors indicates your skill is ready for submission.