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

> Learn how to add custom commands to the PM Skills Marketplace. This guide covers creating definition files, registering commands, and passing validation for your plugins.

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

---

**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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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:

```markdown

# /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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/plugin.yaml)) to include the new command under the `commands:` key:

```yaml

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

```bash
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`](https://github.com/phuryn/pm-skills/blob/main/tests/test_validator.py)** – Unit tests for YAML front-matter parsing and individual validation functions (`validate_skill`, `validate_command`)
- **[`tests/test_consistency.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script expects three sub-folders: `skills/`, `commands/`, and a [`manifest.yaml`](https://github.com/phuryn/pm-skills/blob/main/manifest.yaml) file. The marketplace index ([`marketplace.yaml`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/manifest.yaml).