# Adding a New Command to a pm-skills Plugin: Complete Developer Guide > Learn how to add a new command to a pm-skills plugin. Follow this developer guide to create command files, reference skills, and validate your work for seamless integration. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-30 --- **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`](https://github.com/phuryn/pm-skills/blob/main/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 definition (SKILL.md with YAML front-matter) ├── commands/ │ └── .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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)) automatically checks that every command file meets structural requirements and references valid skills. ### The Validation System The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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 `.md`. Use kebab-case for filenames (e.g., [`summarize-text.md`](https://github.com/phuryn/pm-skills/blob/main/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. ```yaml --- description: Brief description of what the command does argument-hint: "" --- ``` ### Step 4: Write the Command Markdown After the front-matter, structure the content with: - A title following the format `# / — 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: ```bash python validate_plugins.py ``` 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`](https://github.com/phuryn/pm-skills/blob/main/README.md). Follow the existing format used in [`pm-toolkit/README.md`](https://github.com/phuryn/pm-skills/blob/main/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: ```markdown --- description: Summarize a block of text into a concise paragraph argument-hint: "" --- # /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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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/.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 ` to ensure compliance - **Update** the plugin's [`README.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/README.md) file, following the existing list format found in [`pm-toolkit/README.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/README.md). This documentation serves as the public entry point for users discovering available slash commands and their functionality.