# How to Add New Skills to the PM Skills Marketplace: A Complete Guide > Learn how to add new skills to the PM Skills Marketplace with this complete guide. Follow simple steps to create skill directories, add markdown files, and validate your contributions. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-07-02 --- **To add new skills to the PM Skills Marketplace, create a kebab-case directory inside the appropriate plugin's `skills/` folder, populate it with a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file containing the required frontmatter and structured sections, optionally add command workflows under `commands/`, and validate your changes using [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py).** The PM Skills Marketplace is a Claude-compatible plugin collection hosted in the `phuryn/pm-skills` repository that organizes product management workflows into self-contained AI skills. Adding new skills to the PM Skills Marketplace requires no core code changes or central registry updates—Claude's plugin loader discovers skills automatically by scanning the `skills/` directories at runtime. ## Understanding the Marketplace Architecture The marketplace organizes capabilities into nine top-level plugins such as **pm-product-discovery**, **pm-product-strategy**, and **pm-execution**. Each skill exists as a standalone folder inside its parent plugin's `skills/` directory, described by a single **SKILL.md** file that defines inputs, process, and output format. The file **[`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)** serves as the top-level manifest, registering only the nine plugin directories. Individual skills require no entries in this file; management is purely filesystem-based. When Claude loads, it recursively scans each plugin's `skills/` folder to build the available capability set. ## Step-by-Step Guide to Adding a Skill ### Create the Skill Directory Navigate to the appropriate plugin and create a new folder using kebab-case naming. For example, to add a customer journey mapping skill to the market research plugin: ```bash mkdir -p pm-market-research/skills/customer-journey-map ``` ### Write the SKILL.md Schema Create a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file in your new directory with YAML frontmatter followed by standardized sections. The frontmatter must include `name` and `description` keys. The body requires `Purpose`, `Input Arguments`, `Process`, `Output Format`, and `Checklist` sections. ```bash cat > pm-market-research/skills/customer-journey-map/SKILL.md <<'EOF' --- name: customer-journey-map description: "Generate a visual customer‑journey map from interview notes and identify pain points." --- # Customer Journey Mapping ## Purpose Turn raw interview notes into a structured journey map that highlights stages, touchpoints, emotions, and friction. ## Input Arguments - `$OBJECTIVE`: What you want to learn from the journey (e.g., "discover onboarding friction"). - `$INTERVIEWS`: Raw interview excerpts or transcripts. ## Process 1. **Chunk** the interview text and extract stage‑specific quotes. 2. **Group** quotes by identified stages (awareness, consideration, onboarding, …). 3. **Synthesize** key emotions and pain points for each stage. 4. **Output** a markdown‑friendly table that can be turned into a diagram. ## Output Format - **[JOURNEY TABLE]** – Markdown table with columns: Stage | Touchpoint | Emotion | Pain Point - **[INSIGHTS]** – Bullet list of top‑level insights and recommended actions. ## Checklist - [ ] All interview excerpts parsed - [ ] Stages identified - [ ] Pain points highlighted - [ ] Output formatted as markdown table EOF ``` ### Add Optional Command Workflows If your skill should participate in chained workflows, create a command file in the plugin's `commands/` directory. Command files reference skills by name and define execution sequences. ```markdown --- name: journey-from-segmentation description: "Generate a journey map after creating user segments." --- # Journey from Segmentation 1. Run `user-segmentation` skill to produce `$SEGMENTS`. 2. Pass `$SEGMENTS` to `customer-journey-map` skill. 3. Return the journey table and insights. ``` ### Validate with validate_plugins.py Before committing, run the validation script to ensure your [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) contains all required fields and valid YAML syntax: ```bash python3 validate_plugins.py ``` This script checks every skill directory for schema compliance, preventing malformed definitions from breaking the marketplace loader. ### Commit and Deploy Once validation passes, commit your new files: ```bash git add pm-market-research/skills/customer-journey-map/ git add pm-market-research/commands/journey-from-segmentation.md # if applicable git commit -m "Add customer-journey-map skill to market-research plugin" ``` The marketplace exposes the new skill immediately upon the next Claude plugin load—no restart or registry update required. ## Key Files and Components | Path | Purpose | |------|---------| | `pm-/skills//SKILL.md` | Source of truth defining skill name, description, inputs, process, and output format | | `pm-/commands/*.md` | Optional workflow definitions that chain multiple skills | | [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) | Top-level manifest listing the nine plugins; skills are discovered automatically | | [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) | Utility script verifying schema compliance across all skill definitions | ## Summary - **Adding skills is filesystem-based**: Create a directory under `skills/` and add a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file—no registration in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) needed. - **Follow the schema**: Include required frontmatter (`name`, `description`) and body sections (Purpose, Input Arguments, Process, Output Format, Checklist). - **Validate before committing**: Run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) to catch YAML syntax errors or missing fields. - **Optional chaining**: Use `commands/` files to create multi-skill workflows that invoke your new skill. - **Immediate availability**: Claude discovers skills at runtime by scanning the `skills/` directories. ## Frequently Asked Questions ### Do I need to modify marketplace.json to add a new skill? No. The **[`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)** file only registers the nine top-level plugins. Individual skills are discovered automatically when Claude scans the `skills/` subdirectories at load time. You should never edit [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) when adding new skills. ### What happens if I skip running validate_plugins.py? Your skill may contain malformed YAML or missing required sections, causing Claude to ignore it or throw errors during plugin initialization. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script ensures every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) follows the expected schema before you commit, preventing runtime failures. ### Can I create a new top-level plugin for my skills? The marketplace architecture expects skills to reside within the existing nine plugins (such as `pm-product-discovery` or `pm-toolkit`). You should organize your skill into the most appropriate existing category rather than creating new top-level plugin directories, as the plugin list in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) defines the supported structure. ### How does Claude discover the new skills immediately? According to the `phuryn/pm-skills` source code, Claude's plugin loader recursively scans the `skills/` directories at runtime, reading each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file to build the capability catalog. Since skills are file-based rather than registered in a central database, new files become available as soon as they exist in the filesystem and the plugin reloads.