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

To create a custom skill in pm-skills, create a new folder under a plugin's skills/ directory containing a 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 and 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 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 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.

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

Step 2: Write the SKILL.md File

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

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

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. The CI pipeline will automatically run validate_plugins.py again.

Custom Skill Template Example

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

---
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 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 when opening your PR.

Frequently Asked Questions

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

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

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