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

> Learn how to define commands in a PM Skills plugin. This guide covers creating command files, YAML front matter, and referencing skills for your phuryn/pm-skills project.

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

---

**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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/review-resume.md) command references the `**review-resume** skill`, which must exist at [`skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json)
2. **Validate skills** – Verifies each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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:

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

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

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

```markdown
---
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`](https://github.com/phuryn/pm-skills/blob/main/skills/summarize-interview/SKILL.md) exists.

### Plugin Manifest

Define your plugin metadata in [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json):

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A demo PM-Skills plugin",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** to ensure compliance with the Claude Code plugin specification
- **Structure your plugin** with [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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.