How to Add a Custom Command to an Existing pm-skills Plugin

Create a Markdown file in the plugin's commands/ directory with required YAML front-matter containing a description field, reference an existing skill in the workflow section, and run validate_plugins.py to verify compliance before updating the plugin's README.

The pm-skills repository is a collection of Claude Code plugins that expose product-management skills as slash commands. Each plugin follows a strict directory structure where custom commands are defined as Markdown files within a commands/ folder. Adding a custom command to an existing pm-skills plugin requires creating a properly formatted command file that references an existing skill and passes the automated validator checks.

Understanding the Plugin Structure

Before adding a command, familiarize yourself with the directory layout enforced by the pm-skills architecture:

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

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

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

└── README.md                # Documentation and command list

The validator at validate_plugins.py automatically checks that every command file contains the required YAML front-matter, references an existing skill, and meets style guidelines.

Step-by-Step Guide to Adding a Custom Command

1. Navigate to the Target Plugin Directory

Select the plugin you want to extend (for example, pm-toolkit) and navigate to its root directory. All subsequent files are created relative to this location.

2. Create the Command File

Inside the plugin's commands/ folder, create a new Markdown file named <your-command>.md. The filename becomes the command identifier that Claude Code recognizes.

3. Add Required YAML Front-Matter

The file must begin with YAML front-matter delimited by ---. At minimum, include the description field. Optionally add argument-hint to provide usage examples.

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

The validator enforces that this front-matter exists and that the description meets length requirements.

4. Write the Command Workflow

After the front-matter, structure the Markdown content with:

• A concise title (# /<command-name>)

• An invocation block showing usage examples

• A workflow section that references an existing skill using bold formatting: **skill-name** skill

For example, if your command uses a grammar-check skill, include: "Apply the grammar-check skill:". This pattern allows validate_plugins.py to verify that the command references a valid skill defined in the skills/ directory.

5. Run the Validator Locally

Execute the validation script to ensure your new command meets all structural requirements:

python validate_plugins.py <path-to-plugins>

The validator checks for:

• Required YAML front-matter (description, optional argument-hint)
• Valid skill references in the workflow
• Proper markdown structure and style guidelines

Address any errors or warnings before proceeding.

6. Update the Plugin Documentation

Add the new command to the "Commands" list in the plugin's README.md (located at pm-toolkit/README.md or equivalent). This ensures users can discover the command through the plugin's documentation.

7. Commit Your Changes

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

Complete Code Example

Below is a minimal implementation for a /summarize-text command added to the pm-toolkit plugin. Save this as pm-toolkit/commands/summarize-text.md:

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

The validator automatically detects the required front-matter, recognizes the reference to the summarize skill, and verifies that the file adheres to the established patterns.

Key Files and Validation Logic

Understanding these core files ensures you follow the architectural requirements when adding custom commands:

• validate_plugins.py: Located in the repository root, this script enforces all structural and style checks for plugins, skills, commands, and README files. It validates that command files contain the required YAML front-matter and reference existing skills.

• .claude-plugin/plugin.json: The manifest file required by Claude Code that contains the plugin identifier, version, description, author, and keywords.

• commands/<command-name>.md: Template for each command. Must contain YAML front-matter followed by markdown content describing the workflow. See pm-toolkit/commands/review-resume.md for a production example.

• skills/<skill-name>/SKILL.md: Defines the skill that your command will invoke. Commands must reference these skills in their workflow section using the bold pattern: **skill-name** skill.

• <plugin-name>/README.md: Lists available skills and commands. Update this file when adding new commands to maintain accurate documentation.

Summary

• Create a Markdown file in commands/<command-name>.md with required YAML front-matter including description and optional argument-hint.
• Reference existing skills using the **skill-name** skill pattern in the workflow section to ensure validator recognition.
• Validate your changes by running python validate_plugins.py <path-to-plugins> to check for structural errors and missing references.
• Document the new command in the plugin's README.md to make it discoverable to users.
• Commit the command file, updated README, and any related assets with a clear, descriptive message.

Frequently Asked Questions

What fields are required in the YAML front-matter?

The description field is mandatory. The argument-hint field is optional but recommended to provide users with usage examples. The validator in validate_plugins.py will reject any command file missing the description field in its YAML front-matter.

How do I link a command to an existing skill?

In the workflow section of your command Markdown file, reference the skill using bold formatting: **skill-name** skill. For example, "Apply the grammar-check skill:" creates a link that the validator recognizes and verifies against the contents of the skills/ directory.

Can I add a command without referencing a skill?

While technically possible to create the file, the validator and Claude Code architecture expect commands to delegate core logic to skills. Commands should reference existing skills in their workflow to maintain consistency with the pm-skills plugin architecture. If no appropriate skill exists, you must first create one in the skills/ directory.

What happens if I forget to update the README?

The validator will not fail if you omit the README update, but users will not see your new command in the plugin's documentation. The pm-toolkit/README.md and other plugin READMEs serve as the public entry point for users browsing available commands, so updating it ensures discoverability.

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