# How to Create a New Custom Command in PM Skills: A Step-by-Step Guide

> Learn how to create a new custom command in PM Skills. Follow our step-by-step guide to define slash commands arguments and build workflows by referencing existing skills.

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

---

**Create a new markdown file in a plugin's `commands/` directory with YAML front-matter defining the slash command, description, and argument hint, then write a workflow that chains existing skills by referencing their names.**

The **pm-skills** repository operates as a Claude Marketplace where product management workflows are organized into modular plugins. Creating a new custom command in PM Skills involves authoring a markdown file that defines a slash command (e.g., `/my-insight`) and orchestrates one or more reusable skills. The system automatically parses these files on refresh, making your custom command instantly available to Claude or any compatible AI assistant.

## Understanding the PM Skills Architecture

Before creating a command, you must understand the three core components of the plugin system as implemented in the `phuryn/pm-skills` repository:

- **Skills** – Reusable knowledge modules stored as [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files within plugin subdirectories (e.g., [`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md)). These encapsulate specific expertise like **product-vision** or **pricing-strategy**.
- **Commands** – User-triggered workflows defined in markdown files under a plugin's `commands/` folder. Each file contains a YAML front-matter header and a step-by-step workflow that references skills by name.
- **Plugin Manifest** – A JSON configuration file located at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) that registers the plugin's metadata, including name, version, and author information.

When the marketplace loads, Claude automatically discovers every `commands/*.md` file and parses the front-matter to determine the command name, arguments, and description.

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

### Step 1: Choose or Create a Plugin

First, determine where your command logically belongs. You can add it to an existing plugin (such as `pm-toolkit` or `pm-product-discovery`) or create a new plugin directory. If creating a new plugin, you must also create a `commands/` subdirectory to house your command files.

### Step 2: Create the Command Markdown File

Create a new markdown file in the `commands/` directory. The filename does not determine the command name; the front-matter does.

At the top of the file, include a YAML front-matter block with two required fields:

- `description` – A human-readable explanation of what the command does.
- `argument-hint` – A template showing users how to invoke the command (e.g., `"<product idea>"`).

```markdown
---
description: Generate a concise product vision and pricing brief for a new idea
argument-hint: "<product idea>"
---

# /my-insight -- Vision & Pricing Quick Brief

```

### Step 3: Write the Workflow Body

Below the front-matter, write the workflow that describes how Claude should execute the command. Explicitly reference existing skills by their names (e.g., `product-vision`, `pricing-strategy`). The AI automatically loads these skills on-demand.

For example, to create a command that combines two skills:

```markdown
Provide a short product idea and receive:

1. A polished product vision statement (via the `product-vision` skill)
2. A pricing strategy outline (via the `pricing-strategy` skill)

## Invocation

```

/my-insight Launch an AI-powered note-taking app for remote teams

```

## Workflow

### Step 1 – Vision

Ask Claude to run the **product-vision** skill with the supplied idea.

### Step 2 – Pricing

Feed the same idea into the **pricing-strategy** skill.

### Step 3 – Assemble Brief

Combine the two outputs into a single markdown section:

```

## Vision

<output-from-product-vision>

## Pricing

<output-from-pricing-strategy>

```

The command returns the assembled brief ready for sharing with stakeholders.

```

### Step 4: Register the Plugin (If New)

If you created a brand-new plugin, you must add a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest file at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) within your plugin root. This file registers the plugin with the marketplace.

```json
{
  "name": "pm-custom",
  "version": "0.1.0",
  "description": "User-defined commands and skills for ad-hoc product work",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://your-site.example"
  },
  "keywords": ["custom", "commands", "product-management"],
  "homepage": "https://github.com/your-org/pm-custom",
  "license": "MIT"
}

```

Existing plugins like `pm-toolkit` already contain this file at [`pm-toolkit/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json), so you only need to add your markdown command file to extend them.

### Step 5: Commit and Refresh

Commit your new command file to the repository. After the next marketplace refresh, the command becomes instantly available. Invoke it using the slash command defined in the workflow header:

```bash
/my-insight Build a collaborative whiteboard for design teams

```

## Reference Implementation: Examining an Existing Command

The repository provides a complete reference implementation at [`pm-toolkit/commands/tailor-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md). This file demonstrates the proper structure of front-matter, invocation examples, and skill chaining.

The top-level [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) explains the overall architecture and how commands chain skills, while the plugin manifest at [`pm-toolkit/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json) shows how the system discovers available commands.

## Summary

- **Custom commands** are markdown files stored in a plugin's `commands/` directory that define slash-command workflows.
- Each command requires **YAML front-matter** with `description` and `argument-hint` fields to register with the marketplace.
- Commands **reference skills by name** (e.g., `product-vision`, `pricing-strategy`), which are automatically loaded from [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files within the repository.
- New plugins require a **[`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)** manifest at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) to be recognized by the system.
- The **[`tailor-resume.md`](https://github.com/phuryn/pm-skills/blob/main/tailor-resume.md)** file in `pm-toolkit` serves as the canonical example for command structure and workflow documentation.

## Frequently Asked Questions

### Do I need to modify the plugin.json to add a command to an existing plugin?

No. You only need to create a new markdown file in the existing plugin's `commands/` directory. The [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) file only needs to be modified when you are creating a brand-new plugin or updating version metadata. The system automatically discovers new command files by scanning the `commands/` folder.

### Can I reference skills from other plugins in my custom command?

Yes. Commands can reference any skill loaded in the marketplace by using the skill name in the workflow body. For example, a command in `pm-toolkit` can reference the `product-vision` skill from `pm-product-strategy` because skills are loaded on-demand and are globally accessible within the marketplace ecosystem.

### What is the difference between a skill and a command in PM Skills?

A **skill** is a reusable knowledge module defined in a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file that encapsulates expertise for a specific task (e.g., reviewing resumes or defining product vision). A **command** is a user-triggered workflow defined in a markdown file under `commands/` that orchestrates one or more skills to accomplish a broader goal. Commands provide the interface; skills provide the functionality.

### How do I test my custom command before committing?

Test your command by validating the markdown syntax and ensuring all referenced skill names match exactly with existing [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files in the repository. Since the system parses the markdown at runtime, you can verify the front-matter structure by comparing it against working examples like [`pm-toolkit/commands/tailor-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md). Once committed and the marketplace refreshes, the command becomes active and can be invoked via the slash command interface.