# How to Add a Custom Command to an Existing pm-skills Plugin > Easily add a custom command to your pm-skills plugin. Learn how to create a command file, reference skills, validate your changes, and update the README for seamless integration. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-07-01 --- **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`](https://github.com/phuryn/pm-skills/blob/main/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 definitions (SKILL.md with YAML front-matter) ├── commands/ │ └── .md # Command definitions (YAML front-matter + Markdown) └── README.md # Documentation and command list ``` The validator at [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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 `.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. ```markdown --- description: Brief description of what the command does argument-hint: "" --- ``` 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 (`# /`) - 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`](https://github.com/phuryn/pm-skills/blob/main/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: ```bash python validate_plugins.py ``` 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`](https://github.com/phuryn/pm-skills/blob/main/README.md) (located at [`pm-toolkit/README.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/summarize-text.md): ```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. ``` 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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json)**: The manifest file required by Claude Code that contains the plugin identifier, version, description, author, and keywords. - **`commands/.md`**: Template for each command. Must contain YAML front-matter followed by markdown content describing the workflow. See [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) for a production example. - **`skills//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`. - **`/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/.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 ` to check for structural errors and missing references. - **Document** the new command in the plugin's [`README.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/README.md) and other plugin READMEs serve as the public entry point for users browsing available commands, so updating it ensures discoverability.