# How to Create Custom Skills for phuryn/pm-skills: A Complete Developer’s Guide > Learn to create custom skills for phuryn/pm-skills. This guide details adding new skills via SKILL.md files, command wrappers, and validation steps for developers. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-28 --- **Yes, you can create custom skills for phuryn/pm-skills by adding a new directory under any plugin’s `skills` folder containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with YAML front-matter, optionally exposing it via a command wrapper in the `commands` folder, and running `python -m validate_plugins` to verify the structure.** The phuryn/pm-skills repository is organized as a modular plugin system where each skill is defined as a markdown file with structured front-matter. By following the repository’s naming conventions and directory structure, you can extend the toolkit with custom product management utilities that integrate seamlessly with the existing validation pipeline. ## Understanding the Plugin Architecture The phuryn/pm-skills project implements a strict plugin-based architecture. Each plugin resides in its own directory (such as `pm-toolkit`) and must contain a [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest file that identifies the plugin to Claude Code. According to the validation logic in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 16-40), this manifest must contain a name value that exactly matches the plugin directory name. Inside each plugin, the `skills` directory houses subdirectories named after the skill’s slug, each containing a mandatory [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. The repository also supports an optional `commands` directory containing markdown files that define slash-commands capable of invoking specific skills. ## Step-by-Step Guide to Creating a Custom Skill ### Choose or Create a Plugin First, select an existing plugin (such as `pm-toolkit`) or create a new plugin directory. Ensure the plugin root contains a valid [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest and a [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) describing the plugin’s purpose. The validator enforces that the plugin name declared in the manifest matches the directory name exactly. ### Define the Skill Structure Create a new subdirectory under `/skills` using the skill’s slug as the directory name (for example, `pm-toolkit/skills/my-new-skill/`). Inside this directory, create a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with required front-matter fields `name` and `description` enclosed in triple dashes: ```yaml --- name: my-new-skill description: "A quick utility that formats a list of product ideas into a one-sentence pitch." --- ``` **Critical constraint:** The `name` value must exactly match the directory name (e.g., `my-new-skill`), as enforced by the directory-name validation logic in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py). ### Write the SKILL.md Content After the front-matter, document the skill’s purpose, inputs, and behavior. The `validate_skill` function in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 182-229) checks that the content length is appropriate (warning if significantly shorter than 300 words or longer than 3,000 words). A valid skill definition includes input arguments, response structure, and best-practice guidance: ```markdown # My New Skill You are an AI assistant that helps product managers craft concise pitch sentences. ## Input Arguments - `$IDEAS`: A newline-separated list of product ideas. ## Response Structure - **Pitch**: A single sentence that captures the core value proposition. ## Guidance - Use the "problem-solution-benefit" pattern. ``` Reference the canonical example at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) for the complete structure. ### (Optional) Create a Command Wrapper To expose your skill via a slash-command, create a markdown file under `/commands/.md` with front-matter containing `description` (required) and optionally `argument-hint`: ```yaml --- description: "Generate a one-sentence pitch from a list of ideas." argument-hint: "$IDEAS" --- ``` Inside the command file, reference the skill using the exact pattern `**skill-name** skill` so the cross-reference checker can validate the link: ```markdown **my-new-skill** skill Use the skill to turn the provided ideas into a concise pitch. ``` The `validate_cross_references` function in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 289-308) verifies that every command file references an existing skill defined in the `skills` directory. ## Validating Your Custom Skill Before committing changes, execute the repository’s validation script to catch naming mismatches, missing front-matter fields, or broken cross-references: ```bash python -m validate_plugins ``` The script performs several enforcement checks: - **Directory-name alignment**: Validates that each skill’s directory name matches its `name` front-matter field - **Front-matter completeness**: Confirms [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files contain valid YAML with required `name` and `description` fields - **Cross-reference integrity**: Ensures command files in the `commands` directory point to real skills using the `**skill-name** skill` pattern - **Content length**: Issues warnings if skill documentation falls outside the recommended word count range (approximately 300–3,000 words) ## Summary - **phuryn/pm-skills** uses a plugin architecture where custom skills are markdown files with YAML front-matter stored in `/skills//SKILL.md`. - **Strict naming required**: The directory name must match the `name` field in the front-matter exactly, as validated by [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py). - **Optional command exposure**: Create wrapper commands in `/commands/` to make skills callable via slash-commands, referencing them with the pattern `**skill-name** skill`. - **Mandatory validation**: Always run `python -m validate_plugins` to verify your skill meets the specification and passes cross-reference checks. ## Frequently Asked Questions ### Do I need to modify the core validation script to add a custom skill? No. Place your skill in the correct directory structure under an existing or new plugin, then run the existing `python -m validate_plugins` command. The script in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) automatically discovers and validates all plugins and skills without requiring modifications to the validation logic itself. ### Can a single skill be referenced by multiple commands? Yes. You can create multiple command files in the `commands` directory that all reference the same skill using the `**skill-name** skill` pattern. The cross-reference validator in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 289-308) confirms that the skill exists, regardless of how many commands point to it. ### What happens if my SKILL.md file exceeds the word count limit? The validator defined in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 182-229) issues a warning if your skill documentation exceeds approximately 3,000 words. While the skill will still function, excessive length may impact parsing performance and maintainability. ### Is the .claude-plugin/plugin.json file required for custom skills? Yes. Every plugin must include a [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest at its root. The validator specifically checks this file (lines 16-40 in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)) to ensure the plugin name matches the directory name, which is required for the skill to be discovered by the Claude Code plugin system.