Adding Custom Commands to the PM Skills Marketplace: A Complete Guide

Adding a custom command to the PM Skills Marketplace requires creating a markdown definition file in your plugin's commands/ directory, registering the command in manifest.yaml, and passing the repository's validation suite.

The PM Skills Marketplace is an open-source collection of plugins that extend Claude's capabilities with structured product management workflows. Each plugin contains skills (markdown-based knowledge modules) and commands (slash-commands that chain skills into end-to-end workflows). According to the phuryn/pm-skills source code, contributing a new command follows a strict three-step validation pipeline that ensures cross-reference integrity and structural consistency across the marketplace.

Step 1: Create the Command Definition

Commands in the PM Skills Marketplace are pure markdown files stored in your plugin's commands/ directory. The file must follow the pattern pm-<plugin-name>/commands/<your-command>.md (for example, pm-execution/commands/ship-check.md).

The validator (validate_plugins.validate_command()) enforces the following structure:

• The first line must be an ATX heading starting with the slash command name (e.g., # /ship-check)

• The body contains a short description

• A ## Steps section lists the skill calls in order

The validation logic in validate_plugins.py checks that the command name starts with a /, that all referenced skills exist in the plugin's skills/ directory, and that required fields (title, description, steps) are present.

Create your command file:

# /ship-check

**Description**  
Turn a vibe‑coded repository into a reviewer‑ready shipping packet: generate documentation, run static security & performance audits, map test coverage, and compile results.

## Steps

1. `document-app` – Reverse‑engineer system documentation.
2. `security-audit-static` – Run a static security audit.
3. `performance-audit-static` – Run a static performance audit.
4. `derive-tests` – Produce a test‑coverage map.
5. `ship-check` – Assemble the final shipping packet.

Save this as pm-ai-shipping/commands/ship-check.md.

Step 2: Update the Plugin Manifest

After creating the markdown file, you must register the command in your plugin's manifest. The validator loads this file to build the marketplace index and verify file consistency.

Update pm-<plugin-name>/manifest.yaml (or plugin.yaml) to include the new command under the commands: key:

# pm-ai-shipping/manifest.yaml

name: pm-ai-shipping
description: AI Shipping Kit – docs, audits, test maps, and shipping packets.
skills:
  - shipping-artifacts
  - intended-vs-implemented
commands:
  - ship-check          # ← new entry

  - document-app
  - derive-tests
  - security-audit-static
  - performance-audit-static

The validate_plugins.validate_plugin() function ensures every command listed has a matching markdown file on disk and that there are no duplicate command names across the plugin.

Step 3: Run the Validation Suite

Before submitting your contribution, run the repository's validation pipeline to verify that your command meets all consistency rules.

Execute the validator from the repository root:

python -m validate_plugins    # runs the validator and prints a summary

pytest                         # runs unit & consistency tests (CI does this automatically)

The validation suite consists of two main test components:

• tests/test_validator.py – Unit tests for YAML front-matter parsing and individual validation functions (validate_skill, validate_command)
• tests/test_consistency.py – Integration tests that ensure marketplace listings, README headings, and cross-references stay in sync

If any error appears (e.g., "Command /ship-check references undefined skill document-app"), fix the skill name or add the missing skill file, then re-run until the suite passes.

Understanding the Validation Pipeline

The PM Skills Marketplace architecture guarantees that a new command cannot be merged unless it passes three layers of verification.

Plugin Layout and File Structure

Each plugin lives under a top-level folder named pm-<domain> (e.g., pm-product-discovery, pm-execution). Inside each plugin, the validate_plugins.py script expects three sub-folders: skills/, commands/, and a manifest.yaml file. The marketplace index (marketplace.yaml in the repo root) enumerates all plugin directories, and the validator cross-checks that each listed plugin has a matching folder on disk.

Command File Parsing

The validate_plugins.parse_yaml_frontmatter() function extracts optional YAML front-matter from command files, while validate_plugins.validate_command() enforces that headings must be unique and dated. The parser specifically checks that the first line is a heading starting with the slash name and that the ## Steps section contains valid skill references.

Cross-Reference Validation

The consistency tests in tests/test_consistency.py validate that command references in the root README resolve to actual files, that markdown headings follow the required style, and that the command appears in the marketplace index. This ensures that the python -m validate_plugins report consumed by the CI workflow (.github/workflows/tests.yml) contains no errors before merge.

Summary

• Create a markdown file in pm-<plugin-name>/commands/ with a heading starting with / and a ## Steps section listing skill calls.

• Register the command in pm-<plugin-name>/manifest.yaml under the commands: key to ensure the validator can locate the file.

• Validate your changes by running python -m validate_plugins and pytest to check for undefined skill references, duplicate names, and markdown formatting errors.

• Verify that validate_plugins.validate_command() and validate_plugins.validate_plugin() pass successfully before submitting your pull request.

Frequently Asked Questions

What happens if I reference a skill that doesn't exist in my command file?

The validate_plugins.validate_command() function will raise a validation error indicating that the command references an undefined skill. You must either create the missing skill file in the skills/ directory or correct the skill name in your ## Steps section before the CI pipeline will pass.

Can I include YAML front-matter in my command markdown files?

Yes. The validate_plugins.parse_yaml_frontmatter() function extracts optional YAML front-matter from command files. While the validator checks for required fields like title, description, and steps, you can include additional metadata in the front-matter as long as it follows valid YAML syntax.

How does the repository prevent duplicate command names?

The validate_plugins.validate_plugin() function loads the plugin manifest and checks that every command listed has a matching file while ensuring there are no duplicate names within that plugin. Additionally, tests/test_consistency.py runs integration tests that verify command references across the entire marketplace index to prevent naming collisions between different plugins.

Where should I run the validation commands?

Run both python -m validate_plugins and pytest from the repository root directory. The validator walks every plugin directory (pm-<domain>/) automatically, so you do not need to specify individual file paths. The test suite will pick up your new command files as long as they are properly registered in the plugin's manifest.yaml.

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