# How to Create a Custom Skill in pm-skills: A Complete Guide

> Learn how to create a custom skill in pm-skills. Follow this guide to add your own skills, define them with YAML and markdown, and validate your plugin.

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

---

**To create a custom skill in pm-skills, create a new folder under a plugin's `skills/` directory containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with YAML front-matter (name and description) followed by markdown instructions, then validate with `python3 validate_plugins.py`.**

The **phuryn/pm-skills** repository provides a marketplace of product management skills for AI assistants like Claude. When you create a custom skill in pm-skills, you are building a self-contained Markdown file that the system automatically loads when matching user requests.

## Understanding the pm-skills Architecture

Before writing code, understand how the repository structures its components. According to the source code, each skill resides within a plugin's `skills/` folder and must follow strict validation rules defined in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) and [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md).

### Plugin Directory Structure

Each **plugin** groups related skills into a top-level folder. Inside each plugin, the `skills/` sub-folder holds one folder per skill. For example, `pm-toolkit/skills/review-resume/` represents a complete skill package as implemented in the repository.

### The SKILL.md File

The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file is the only source file a skill requires. It contains YAML front-matter followed by the full prompt instructions. The front-matter must include `name` and `description` keys, and critically, the folder name must match the `name` field exactly.

### Validation Requirements

The repository includes [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) which lints every skill against the required schema. This script checks front-matter completeness, naming consistency between folders and the `name` field, and markdown limits. You must run this before submitting a pull request.

## Step-by-Step Guide to Creating a Custom Skill

Follow these steps to add your skill to the marketplace.

### Step 1: Create the Skill Folder

Create a new directory under an existing plugin's `skills/` folder. The folder name must exactly match the skill name you will define in the front-matter.

```bash
mkdir -p pm-execution/skills/product-roadmap

```

### Step 2: Write the SKILL.md File

Create [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) inside your new folder with the required YAML front-matter and your custom prompt logic. The file must start with the front-matter delimiter `---` and include both `name` and `description` fields.

```yaml
---
name: product-roadmap
description: "Guided creation of a product roadmap, aligning initiatives with outcomes, timelines, and metrics."
---

# Product Roadmap Builder

You are a senior product manager helping the user design a clear, outcome-driven roadmap.

## Input Arguments

- `$VISION`: High-level product vision or goal.
- `$INITIATIVES`: List of initiatives or features the user wants to include.
- `$TIMEFRAME`: Desired planning horizon (e.g., 12 months).

## Prompt Flow

1. **Clarify Vision** – Ask the user to confirm or refine `$VISION`.
2. **Prioritize Initiatives** – Rank `$INITIATIVES` by impact, effort, and strategic fit.
3. **Allocate Time** – Distribute initiatives across quarters within `$TIMEFRAME`.
4. **Define Success Metrics** – Suggest measurable outcomes per quarter.

### Example Output

| Quarter | Initiative | Owner | Metric | Milestone |
|--------|------------|-------|--------|-----------|
| Q1 | Launch onboarding flow | Alice | 20% activation ↑ | MVP released |

```

### Step 3: Validate Your Skill

Run the validator script from the repository root to ensure compliance with the [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) standards.

```bash
python3 validate_plugins.py

```

Fix any reported errors, such as missing front-matter or mismatched folder names. The validator ensures no cross-plugin references exist in commands and that all skills are fully self-describing.

### Step 4: Test Locally

Load your plugin in a compatible AI assistant and invoke the skill by name (e.g., `/product-roadmap` or `product-roadmap`) to verify functionality.

### Step 5: Submit Your Contribution

Open a pull request following the single-purpose PR guidelines in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md). The CI pipeline will automatically run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) again.

## Custom Skill Template Example

Here is a complete template based on the `review-resume` skill structure:

```yaml
---
name: your-skill-name
description: "Clear description of what this skill does for the user."
---

# Skill Title

You are a [role] helping the user [objective].

## Input Arguments

- `$ARG1`: Description of first argument.
- `$ARG2`: Description of second argument.

## Instructions

1. **Step One** – Description of first action.
2. **Step Two** – Description of second action.

## Output Format

Provide the response in [format].

```

## Summary

- **Create a folder** under `plugin-name/skills/` that matches your skill's `name` front-matter field exactly.
- **Write [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)** with required YAML front-matter (`name` and `description`) and your prompt instructions.
- **Validate locally** using `python3 validate_plugins.py` before submitting.
- **Keep skills self-contained**; no cross-plugin references are allowed in commands.
- **Follow contribution guidelines** in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) when opening your PR.

## Frequently Asked Questions

### What front-matter fields are required for a custom skill?

Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file must include the `name` and `description` keys in its YAML front-matter. The `name` field must exactly match the parent folder name, and the `description` should briefly explain the skill's purpose to users browsing the marketplace.

### How do I validate my skill before submitting?

Run the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script from the repository root. This linter checks that your skill follows the mandatory schema, verifies that folder names match the `name` field, and ensures all required front-matter is present. The CI pipeline runs this same validator automatically on every pull request.

### Can I create a new plugin or must I use an existing one?

You can create a new plugin directory if your skill belongs to a different domain unrelated to existing plugins. Each plugin is a top-level folder containing a `skills/` sub-directory. However, if your skill fits within an existing category (like `pm-execution` or `pm-toolkit`), place it there to maintain logical organization.

### Where does the skill logic actually execute?

The logic executes within the AI assistant (such as Claude Code or Claude Cowork) that loads the plugin. The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file serves as instructions that guide the AI's response; there is no separate execution environment or runtime engine within the pm-skills repository itself.