# How to Create Custom Skills for PM Skills Marketplace

> Learn to create custom skills for the PM Skills Marketplace. Add a SKILL.md file to your plugin's skills directory and validate with validate_plugins.py for seamless integration.

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

---

**Create custom skills for PM Skills Marketplace by adding a YAML-fronted SKILL.md file to a plugin's `skills/` directory and validating it with [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py).**

The PM Skills Marketplace is an open-source plugin ecosystem hosted in the `phuryn/pm-skills` repository that enables product managers to extend AI assistants with specialized capabilities. Because the marketplace organizes functionality as markdown-based plugins rather than compiled code, you can create custom skills for PM Skills Marketplace using only text files and front-matter metadata. This guide walks through the exact file structure, validation rules, and cross-reference requirements defined in the source code.

## Understanding the PM Skills Marketplace Structure

The repository organizes functionality into **plugins**, which are top-level directories containing standardized subdirectories. According to the source code in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), each plugin must contain:
- A `skills/` directory housing individual skill folders
- An optional `commands/` directory containing workflow definitions
- A [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest file

The validator enforces strict naming conventions. When you create custom skills for PM Skills Marketplace, the folder name must exactly match the skill name defined in the front-matter, as checked at lines 86-90 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py).

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

### Choose a Plugin

First, decide whether to add your skill to an existing plugin (such as `pm-toolkit`) or create a new plugin directory. For most use cases, extending an existing plugin keeps the marketplace organized. Ensure the target plugin contains a `skills/` subdirectory.

### Create the Skill Folder

Create a new folder inside the `skills/` directory. The folder name must be the exact skill identifier you will reference in commands. For example, if your skill is `my-awesome-skill`, the path becomes:

```markdown
pm-toolkit/
└── skills/
    └── my-awesome-skill/
        └── SKILL.md

```

The validator at lines 96-100 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) confirms that the folder name matches the `name` field in the front-matter.

### Add the SKILL.md File

Inside your skill folder, create [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) with YAML front-matter. The `validate_skill` function at lines 62-70 enforces that both `name` and `description` are present. Include trigger phrases like "use when" or "use for" in the description to help AI assistants surface the skill automatically.

```yaml
---
name: my-awesome-skill
description: "Generate a concise product brief from a high-level idea. Use when you need a quick one-page overview for stakeholders."
---

```

### Write the Skill Content

After the front-matter, provide markdown content defining the skill's purpose, input arguments, response structure, and examples. The parser uses `parse_yaml_frontmatter` to extract metadata, then validates the remaining content structure.

```markdown

# Product Brief Generator

## Input Arguments

- `$IDEA`: The high-level product idea or concept.
- `$TARGET_AUDIENCE` (optional): Who the product is for.

## Response Structure

1. **Problem Statement** – one sentence summarizing the pain point.
2. **Solution Overview** – a short description of the product.
3. **Key Benefits** – 3-5 bullet points.
4. **Target Audience** – who will benefit most.
5. **Metrics for Success** – suggested KPIs.

## Example Prompt

Generate a brief for: an AI-powered meeting note taker for remote teams.

```

### Optional: Add a Command

To create a slash-command that invokes your skill, add a markdown file in the plugin's `commands/` directory. The front-matter requires `description` and accepts `argument-hint`. Reference the skill using the `**skill-name** skill` pattern, which the cross-reference validator checks at lines 60-68 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py).

```markdown
---
description: Generate a product brief from an idea.
argument-hint: "$IDEA"
---
**my-awesome-skill** skill

Run `/brief "AI meeting notes"` to get a one-page product brief.

```

### Validate Your Changes

Run the validator to ensure your custom skill meets all requirements:

```bash
python3 validate_plugins.py

```

If the script reports no errors, your skill is ready for use. The validator checks:
- Required fields in [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifests
- YAML front-matter parsing via `parse_yaml_frontmatter`
- Name-to-folder matching
- Cross-references between commands and skills

## Validation and Cross-Reference Checks

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script serves as the gatekeeper for the marketplace. When you create custom skills for PM Skills Marketplace, understanding these validation layers ensures immediate compatibility:

- **Front-matter validation**: Lines 62-70 enforce `name` and `description` fields in every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)
- **Folder consistency**: Lines 86-90 and 96-100 verify that the filesystem path matches the declared skill name
- **Cross-reference integrity**: Lines 60-68 validate that commands referencing `**skill-name** skill` point to existing skills

Because the marketplace reads these markdown files directly without compilation, passing validation means the skill is instantly available to Claude Code, Claude Cowork, or any assistant loading the plugin.

## Summary

- **Create custom skills for PM Skills Marketplace** by adding a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with YAML front-matter to a plugin's `skills/` directory
- The folder name must exactly match the `name` field in the front-matter, enforced by [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) lines 86-90
- Required fields include `name` and `description` (validated at lines 62-70)
- Optional commands go in the `commands/` directory and reference skills via the `**skill-name** skill` pattern
- Always run `python3 validate_plugins.py` to check syntax, naming consistency, and cross-references before committing

## Frequently Asked Questions

### What are the required fields for a SKILL.md file?

The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file must start with YAML front-matter containing at least two fields: `name` and `description`. The `validate_skill` function at lines 62-70 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) explicitly checks for these fields and will throw a validation error if either is missing.

### Can I organize skills into subdirectories within the skills folder?

No. The validator expects each skill to reside in its own folder directly under `skills/`, where the folder name matches the skill name. The naming validation at lines 96-100 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) enforces this flat structure to ensure cross-references resolve correctly.

### How do I test a custom skill before submitting it?

Run `python3 validate_plugins.py` from the repository root. This script checks the plugin manifest, parses YAML front-matter, validates name-to-folder matching, and verifies command-to-skill references. If the script exits silently with no errors, your skill is valid and ready for use.

### Do I need to publish or compile the skill for it to become available?

No. The PM Skills Marketplace uses a file-based architecture where assistants read markdown directly from the repository. Once you commit and push valid skill files to the plugin directory, they are immediately available to any AI assistant configured to load that plugin, including Claude Code and Claude Cowork.