How to Add New Skills to the PM Skills Marketplace: A Complete Guide

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 file containing the required frontmatter and structured sections, optionally add command workflows under commands/, and validate your changes using 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 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:

mkdir -p pm-market-research/skills/customer-journey-map

Write the SKILL.md Schema

Create a 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.

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.

<!-- File: pm-market-research/commands/journey-from-segmentation.md -->
---
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 contains all required fields and valid YAML syntax:

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:

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-<area>/skills/<skill>/SKILL.md	Source of truth defining skill name, description, inputs, process, and output format
pm-<area>/commands/*.md	Optional workflow definitions that chain multiple skills
.claude-plugin/marketplace.json	Top-level manifest listing the nine plugins; skills are discovered automatically
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 file—no registration in 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 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 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 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 script ensures every 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 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 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.

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