How to Create Custom Skills for PM Skills Marketplace

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.

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, each plugin must contain:

• A skills/ directory housing individual skill folders
• An optional commands/ directory containing workflow definitions
• A .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.

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:

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

The validator at lines 96-100 of 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 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.

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

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

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

python3 validate_plugins.py

If the script reports no errors, your skill is ready for use. The validator checks:

• Required fields in 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 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
• 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 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 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 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 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 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.

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