How to Create Custom Skills for phuryn/pm-skills: A Complete Developer’s Guide

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 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 manifest file that identifies the plugin to Claude Code. According to the validation logic in 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 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 manifest and a 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 <plugin>/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 file with required front-matter fields name and description enclosed in triple dashes:

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

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 (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:

# 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 for the complete structure.

(Optional) Create a Command Wrapper

To expose your skill via a slash-command, create a markdown file under <plugin>/commands/<command-name>.md with front-matter containing description (required) and optionally argument-hint:

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

**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 (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:

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 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 <plugin>/skills/<skill-name>/SKILL.md.
• Strict naming required: The directory name must match the name field in the front-matter exactly, as validated by validate_plugins.py.
• Optional command exposure: Create wrapper commands in <plugin>/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 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 (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 (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 manifest at its root. The validator specifically checks this file (lines 16-40 in 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.

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