How to Define Commands Within a PM Skills Plugin: A Complete Guide

Define commands within a PM Skills plugin by creating Markdown files in the commands/ directory with YAML front matter containing at least a description field, optionally including an argument-hint field, and referencing skills using bold syntax.

The phuryn/pm-skills repository implements a Claude Code plugin specification that enables product managers to create reusable command tools. Defining commands within a PM Skills plugin requires specific file placement, metadata formatting, and validation against the built-in validate_plugins.py script. This guide explains the exact structure and metadata requirements based on the reference implementation.

Understanding the PM Skills Plugin Structure

A PM Skills plugin is a self-contained directory that follows strict conventions enforced by the validator. The repository structure separates concerns into three distinct areas: the plugin manifest, skill definitions, and command definitions.

The validator processes these components in a specific order: first the manifest (.claude-plugin/plugin.json), then each skill (skills/*/SKILL.md), and finally each command (commands/*.md). According to the source code in validate_plugins.py, the validator reports errors or warnings if a command references a non-existent skill or lacks required front-matter fields.

Required Command File Structure

Command files must reside in the commands/ subdirectory of your plugin root and use the .md extension. Each file requires a YAML front-matter block that begins and ends with triple dashes (---).

YAML Front Matter Requirements

The front-matter block must include specific metadata fields validated by validate_plugins.py:

• description (required): A short, human-readable summary of the command's purpose
• argument-hint (recommended): Provides users with guidance on expected argument format (e.g., "<resume as text or file>")

The validator checks that the front matter begins with --- and ends with another ---, parsing the content between these delimiters for required fields.

File Location Constraints

Commands must live in plugin_root/commands/ with the .md extension. The validator scans this directory specifically, as seen in the reference implementation where commands like review-resume.md reside in pm-toolkit/commands/.

Referencing Skills in Commands

Commands can invoke skills defined within the same plugin using a specific markdown pattern. When you write **skill-name** skill in the command body, the validator's validate_cross_references function automatically detects this reference.

If the referenced skill does not exist in the skills/ directory, the validator reports an error. This ensures type safety between your command interface and skill implementations. For example, the review-resume.md command references the **review-resume** skill, which must exist at skills/review-resume/SKILL.md.

Plugin Validation Workflow

Before commands are usable within Claude, you must run the validation script to ensure compliance:

1. Validate the manifest – Checks name, version, and description fields in .claude-plugin/plugin.json
2. Validate skills – Verifies each SKILL.md contains required name and description front matter
3. Validate commands – Confirms description field exists and skill references are valid

Run the validator using:

python validate_plugins.py

The validator enforces these rules strictly, reporting errors for missing required fields or invalid skill references.

Complete Plugin Directory Structure

Organize your plugin following this structure to ensure the validator processes all components correctly:

my-plugin/
├─ .claude-plugin/
│   └─ plugin.json
├─ skills/
│   └─ my-skill/
│       └─ SKILL.md
└─ commands/
    └─ my-command.md

Code Examples

Minimal Command Definition

Create a basic command file with required front matter:

---
description: Summarize a product discovery interview
argument-hint: "<interview transcript>"
---

# /my-command – Interview Summary

Provide a concise bullet-point summary of the interview transcript, highlighting key insights, pain points, and validation results.

## Invocation

/my-command [paste transcript]

Key implementation details:

• Front matter starts with --- and ends with ---
• The description field is mandatory for validator compliance
• argument-hint tells users what input format to provide

Command with Skill Reference

Define a command that invokes a specific skill:

---
description: Run the "summarize-interview" skill on the supplied transcript
---

# /summarize-interview -- Interview Summary

**summarize-interview** skill

Provide the interview transcript below, and the skill will extract key insights.

The line **summarize-interview** skill triggers validate_cross_references to verify that skills/summarize-interview/SKILL.md exists.

Plugin Manifest

Define your plugin metadata in .claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A demo PM-Skills plugin",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "keywords": ["pm", "product", "demo"]
}

The validator requires name, version, and description, while flagging missing recommended fields such as author.url.

Summary

• Place commands in the commands/ directory with .md extensions
• Include required YAML front matter with at least a description field between --- delimiters
• Add argument-hint to guide users on expected input format
• Reference skills using the **skill-name** skill pattern for automatic validation
• Run validate_plugins.py to ensure compliance with the Claude Code plugin specification
• Structure your plugin with .claude-plugin/plugin.json, skills/*/SKILL.md, and commands/*.md

Frequently Asked Questions

What fields are required in the command YAML front matter?

The description field is strictly required in the front-matter block, as enforced by the validate_plugins.py script. The validator parses the YAML between the --- delimiters and reports an error if this field is missing. While optional, the argument-hint field is recommended to help users understand what arguments your command accepts.

How do I reference a skill within a command file?

Reference a skill by including the skill name in bold followed by the word "skill" on its own line or within the command body. For example, write **review-resume** skill to indicate that this command utilizes the review-resume skill. The validator automatically detects this pattern and verifies that the corresponding skill exists in the skills/ directory.

Where must command files be located in a PM Skills plugin?

Command files must reside in the commands/ subdirectory of your plugin root. The validate_plugins.py script specifically scans this directory for .md files during the validation phase. According to the source code analysis, files placed outside this directory or without the .md extension will not be recognized as valid commands.

Can a command exist without referencing a skill?

Yes, commands can function independently without referencing skills. However, if you do include a skill reference using the **skill-name** skill syntax, the validator requires that the referenced skill actually exists in the skills/ directory. Commands without skill references only need valid front matter to pass validation.

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