# How to Add and Manage Skills in the PM Skills Marketplace

> Learn to add and manage skills in the PM Skills Marketplace by creating directories and SKILL.md files. Validate your skills easily with our guide.

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

---

**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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with required front-matter and structured sections, and optionally validating with [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** – A utility script that verifies every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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:

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

```

### 2. Author the SKILL.md File

Create a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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:

```markdown
---
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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-market-research/commands/journey-from-segmentation.md):

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

```

### 4. Validate the Skill

Run the validation script to ensure your [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) follows the required schema and contains no YAML syntax errors:

```bash
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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json).

## Summary

- **You do not need to update [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)** file with specific front-matter (`name`, `description`) and sections (Purpose, Inputs, Process, Output, Checklist).
- **Use [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file.

### What is the required format for SKILL.md files?

Each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) recursively scans all `skills/` directories across the nine plugins, parsing each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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.