How to Add and Manage Skills in the PM Skills Marketplace

You add and manage skills in the PM Skills Marketplace by creating a kebab-case directory inside a plugin's skills/ folder, authoring a SKILL.md file with required front-matter and structured sections, and optionally validating with validate_plugins.py—no central registry or manifest updates required.

The PM Skills Marketplace is a Claude-compatible plugin collection in the phuryn/pm-skills repository that groups product-management workflows into nine top-level plugins such as pm-product-discovery, pm-product-strategy, and pm-execution. Each skill operates as a self-contained AI workflow defined by a markdown schema, and the marketplace automatically discovers new skills at runtime by scanning the skills/ directories. This guide explains how to add and manage skills in the PM Skills Marketplace using file-system based operations and the validation utilities provided in the repository.

Understanding the Skill Architecture

Before creating a skill, you need to understand how the marketplace organizes and discovers content. The system uses a hierarchical file-based architecture where each skill lives in its own directory within a plugin's skills/ folder.

Key Components

The repository relies on four primary components to manage skills:

• .claude-plugin/marketplace.json – The top-level manifest that registers the nine plugins (e.g., pm-product-discovery, pm-product-strategy). Skills are discovered automatically inside each plugin's skills/ folder; no per-skill entry is required here.
• pm-<area>/skills/<skill>/SKILL.md – The source of truth for each skill containing front-matter with name and description, followed by sections for purpose, inputs, process, output format, and checklists.
• pm-<area>/commands/*.md – Optional workflow files that chain multiple skills together into runnable commands.
• validate_plugins.py – A utility script that verifies every SKILL.md contains required fields and valid YAML syntax.

Step-by-Step: Adding a New Skill

Follow these steps to add a skill to any of the nine plugin directories.

1. Create the Skill Directory

Navigate to the appropriate plugin directory and create a new folder using kebab-case naming. For example, to create a "customer-journey-map" skill in the market-research plugin:

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

2. Author the SKILL.md File

Create a SKILL.md file inside the new directory. The file must include YAML front-matter with name and description keys, followed by markdown sections that define the workflow.

According to the source code in pm-toolkit/skills/grammar-check/SKILL.md, the required structure includes:

• Front-matter: name and description fields
• Purpose: What the skill accomplishes
• Input Arguments: Variables like $OBJECTIVE and $INTERVIEWS
• Process: Numbered steps describing the AI workflow
• Output Format: Structured specification of deliverables
• Checklist: Completion criteria

Here is a complete example for a customer journey mapping skill:

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

3. Optional: Create Command Workflows

If your skill should be part of a chained workflow, create a command file in the plugin's commands/ directory. As shown in pm-toolkit/commands/tailor-resume.md, command files follow a similar schema but invoke one or more skills sequentially.

Example command file at 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.

4. Validate the Skill

Run the validation script to ensure your SKILL.md follows the required schema and contains no YAML syntax errors:

python3 validate_plugins.py

The script checks for required front-matter fields and correct markdown structure, preventing malformed skills from breaking the marketplace.

5. Commit and Deploy

Once validation passes, commit the new files and push to the repository. The Claude plugin loader automatically scans the skills/ directories at runtime, making your new skill immediately available without modifying .claude-plugin/marketplace.json.

Summary

• You do not need to update .claude-plugin/marketplace.json when adding skills; the file only defines the nine top-level plugins, and skills are auto-discovered.
• Every skill requires a SKILL.md file with specific front-matter (name, description) and sections (Purpose, Inputs, Process, Output, Checklist).
• Use validate_plugins.py to verify schema compliance before committing.
• Optional command files in commands/ directories enable complex workflows that chain multiple skills.
• File-system based management means adding a skill is purely a matter of creating the correct directory structure and markdown files.

Frequently Asked Questions

Do I need to modify marketplace.json when adding a new skill?

No. The .claude-plugin/marketplace.json file only registers the nine top-level plugins such as pm-product-discovery and pm-product-strategy. Individual skills are discovered automatically when the Claude plugin loader scans the skills/ directories at runtime. You only need to create the skill folder and SKILL.md file.

What is the required format for SKILL.md files?

Each SKILL.md must begin with YAML front-matter containing name and description fields, followed by markdown sections for Purpose, Input Arguments, Process, Output Format, and Checklist. The validate_plugins.py script enforces this schema and checks for proper YAML syntax.

How do I chain multiple skills together into a workflow?

Create a command file in the appropriate plugin's commands/ directory with a .md extension. These files reference skills by name and define the sequence of execution, passing variables between steps. For example, you can run a segmentation skill first, then pass its output to a journey-mapping skill.

How does the validation script work?

validate_plugins.py recursively scans all skills/ directories across the nine plugins, parsing each SKILL.md file to verify it contains the required front-matter fields and markdown sections. It reports any schema violations or YAML syntax errors, ensuring that only well-formed skills are committed to the repository.

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