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

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 files within plugin subdirectories (e.g., 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 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>").

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

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

Pricing

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 manifest file at .claude-plugin/plugin.json within your plugin root. This file registers the plugin with the marketplace.

{
  "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, 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:

/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. This file demonstrates the proper structure of front-matter, invocation examples, and skill chaining.

The top-level README.md explains the overall architecture and how commands chain skills, while the plugin manifest at 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 files within the repository.
• New plugins require a plugin.json manifest at .claude-plugin/plugin.json to be recognized by the system.
• The 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 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 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 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. Once committed and the marketplace refreshes, the command becomes active and can be invoked via the slash command interface.

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