Adding a New Command to a pm-skills Plugin: Complete Developer Guide

To add a new command to a pm-skills plugin, create a Markdown file in the plugin's commands/ directory with required YAML front-matter including description and optional argument-hint, reference an existing skill using bold formatting in the workflow section, and validate your changes using validate_plugins.py before updating the README.

The pm-skills repository by phuryn provides a structured framework for building Claude Code plugins that expose product-management capabilities as slash commands. Adding a new command requires understanding the strict directory layout and validation rules enforced by the automated validator. This guide walks through the exact file structure, required metadata, and validation steps needed to extend any plugin in the collection.

Understanding the Plugin Architecture

Each plugin in the pm-skills repository follows a mandatory directory structure that Claude Code uses to discover and load functionality.

Directory Structure

Every plugin root must contain:

plugin-root/
├── .claude-plugin/
│   └── plugin.json          # Manifest with name, version, description

├── skills/
│   └── <skill-name>/        # Skill definition (SKILL.md with YAML front-matter)

├── commands/
│   └── <command-name>.md    # Command definition (YAML front-matter + Markdown)

└── README.md                # Human-readable documentation

The commands directory holds individual Markdown files that define slash commands available to users. The skills directory contains reusable logic units that commands invoke. The validator (validate_plugins.py) automatically checks that every command file meets structural requirements and references valid skills.

The Validation System

The validate_plugins.py script enforces compliance across the repository. It verifies that command files contain required YAML front-matter, properly reference existing skills, and follow style guidelines including description length and markdown structure. Always run this validator before committing changes to ensure the new command will be accepted by the plugin system.

Step-by-Step Guide to Adding a New Command

Step 1: Select the Target Plugin

Navigate to the specific plugin directory you want to extend. For example, if extending the pm-toolkit plugin, work within the pm-toolkit/ directory.

Step 2: Create the Command File

Inside the plugin's commands/ folder, create a new Markdown file named <command-name>.md. Use kebab-case for filenames (e.g., summarize-text.md).

Step 3: Add Required YAML Front-Matter

The file must begin with YAML front-matter delimited by triple dashes. Include at least the description field. Optionally add argument-hint to provide usage examples.

---
description: Brief description of what the command does
argument-hint: "<example-argument>"
---

Step 4: Write the Command Markdown

After the front-matter, structure the content with:

• A title following the format # /<command-name> — Human Readable Name

• An Invocation section showing usage examples

• A Workflow section detailing the execution steps

• Optional Notes section for additional context

Step 5: Reference the Associated Skill

Within the workflow section, reference the skill that implements core logic using bold formatting: **skill-name** skill. For example: "Apply the grammar-check skill:". This creates a link that the validator recognizes when checking command definitions against the skills directory.

Step 6: Run the Validator Locally

Execute the validation script to verify compliance:

python validate_plugins.py <path-to-plugins>

The validator reports errors, warnings, or notes for the command file. Fix any structural issues before proceeding.

Step 7: Update the Plugin Documentation

Add the new command to the "Commands" list in the plugin's README.md. Follow the existing format used in pm-toolkit/README.md to ensure consistency.

Step 8: Commit the Changes

Stage the new command file, updated README, and any related documentation. Commit with a clear message such as "Add /my-command to pm-toolkit".

Complete Command File Example

Below is a minimal implementation for a /summarize-text command:

---
description: Summarize a block of text into a concise paragraph
argument-hint: "<text to summarize>"
---

# /summarize-text — Text Summarizer

Generate a brief, high-level summary of the supplied text, preserving key ideas while trimming detail.

## Invocation

/summarize-text [paste text] /summarize-text [upload a document]

## Workflow

### Step 1: Accept the Text

The command accepts plain text, a PDF, DOCX, or markdown document.

### Step 2: Apply the **summarize** skill

The heavy-lifting is performed by the `summarize` skill located in `skills/summarize/`.

### Step 3: Return the Summary

Summary

[generated summary here]

### Step 4: Offer Follow-up

- "Would you like me to **expand** any part of the summary?"
- "Do you need a **bullet-point version**?"

## Notes

- Keep the summary under 150 words.
- Preserve the original tone and intent.

Place this file at pm-toolkit/commands/summarize-text.md. The validator automatically detects the required front-matter, validates the reference to the summarize skill, and checks for missing sections.

Validation and Troubleshooting

When validate_plugins.py processes your new command, it checks that:

• The description field exists in the YAML front-matter
• The argument-hint (if provided) follows proper formatting
• The markdown body contains a workflow section
• Referenced skills exist in the skills/ directory
• Description length meets style guidelines

If validation fails, the script outputs specific line numbers and error types. Common issues include missing front-matter delimiters, referencing non-existent skills, or malformed markdown headers.

Summary

• Create a Markdown file in commands/<command-name>.md with required YAML front-matter
• Include at minimum a description field; add argument-hint for user guidance
• Reference existing skills using the **skill-name** skill format in workflow sections
• Validate using python validate_plugins.py <path> to ensure compliance
• Update the plugin's README.md to document the new command
• Commit with descriptive messages referencing the command name

Following this pattern ensures the validator passes, maintains consistency with the pm-skills collection, and makes commands instantly discoverable by Claude Code users.

Frequently Asked Questions

What YAML front-matter is required for a new command?

The command file must start with --- and include at least a description field that explains what the command does. You can optionally include argument-hint to show users example inputs. The validator in validate_plugins.py checks for these fields and rejects commands missing required front-matter.

How do I reference a skill within a command file?

Reference skills using bold markdown syntax: **skill-name** skill. For example, write "Apply the grammar-check skill:" in your workflow section. The validator recognizes this pattern and verifies that the referenced skill exists in the plugin's skills/ directory, ensuring commands only call implemented functionality.

What checks does validate_plugins.py perform?

The validator checks that command files contain required YAML front-matter (description), meet style guidelines (description length, proper markdown structure), and reference existing skills. It also validates the overall plugin structure including plugin.json manifests and README documentation. Run it locally before committing to catch structural errors.

Where should I document the new command?

Add the command to the "Commands" section of the plugin's README.md file, following the existing list format found in pm-toolkit/README.md. This documentation serves as the public entry point for users discovering available slash commands and their functionality.

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