# How to Submit a Pull Request for pm-skills: Step-by-Step Contributor Guide > Learn how to submit a pull request for pm-skills with this step-by-step guide. Fork the repo, create a branch, make your changes, validate, and submit your contribution. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-30 --- **TLDR: To submit a pull request for pm-skills, fork the repository, create a descriptive branch, modify plugin files inside the relevant folder, run `python3 validate_plugins.py` to enforce front-matter compliance, and open a PR that follows the single-change policy in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md).** Contributing new skills or commands to the **pm-skills** project involves a structured workflow defined in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) and enforced by the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script. Because the repository uses a modular plugin architecture, every contribution must conform to folder conventions and YAML front-matter rules before CI will pass. If you want to submit a pull request for pm-skills successfully, follow the exact sequence below and reference the repository's core files. ## Fork, Clone, and Branch the Repository Start by forking `phuryn/pm-skills` through the GitHub web interface. Then clone your fork and create a dedicated branch so your changes remain isolated from `main`. ```bash git clone https://github.com//pm-skills.git cd pm-skills git checkout -b add- ``` Descriptive branch names help reviewers understand the scope at a glance. ## Add or Edit Plugin Files All contributions live inside plugin-specific directories such as `pm-toolkit/`, `pm-product-strategy/`, or `pm-marketing-growth/`. As noted in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) around lines 38-40, each plugin contains a `skills/` subdirectory with Markdown-formatted [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files and a `commands/` subdirectory with `*.md` command definitions. When you add a new skill, create the appropriate folder structure and include a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. When you add a command, create a `*.md` file in the plugin's `commands/` folder. The repository automatically surfaces new skills in the marketplace catalog once the PR merges. ## Validate Your Changes Locally Before committing, run the project's validation script to catch structural errors early. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script checks every skill and command file for required YAML front-matter, naming consistency, and folder placement, as documented in [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) at lines 18-19. ```bash python3 validate_plugins.py ``` The script must exit with code `0`. If it reports missing `name` or `description` fields in your front-matter, or malformed paths, fix those errors before proceeding. This local step mirrors the CI check that runs automatically when you open the pull request on GitHub. ## Commit, Push, and Open the Pull Request Stage your validated changes, write a concise commit message, and push the branch to your fork. ```bash git add . git commit -m "Add " git push origin ``` Navigate to your fork on GitHub and click **Compare & pull request**. Fill in the PR template with a clear description of the single logical change. Per [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) at lines 12-13, the project requires **one logical change per PR** to keep reviews focused and minimize merge conflicts. Avoid bundling unrelated skills or commands. Once opened, GitHub Actions automatically executes [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) in CI. Reviewers will approve the PR after both automated checks and manual review pass, then a maintainer merges it. ## Understanding the Plugin Architecture Knowing why the validation rules exist will help you diagnose CI failures and structure contributions correctly. ### Plugin-Based Layout Each domain is isolated in its own plugin folder and contains modular `skills/` and `commands/` subdirectories. The marketplace loads skills automatically, and users can invoke them explicitly via `/plugin-name:skill-name` syntax, as noted in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) around lines 38-41. ### Front-Matter Enforcement Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file must begin with a YAML front-matter block declaring `name` and `description`. Command files require `description` and `argument-hint`. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script parses these blocks and fails if they are missing or malformed, which is why [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) lines 14-16 stress strict front-matter compliance. ```yaml --- name: example-skill description: Concise explanation of what the skill does. --- ``` ### Single-Change PR Policy The maintainers enforce a focused contribution model. [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) lines 12-13 explicitly state that each pull request should contain only one logical change. This policy reduces cognitive load for reviewers and prevents cross-skill merge conflicts in the distributed plugin folders. ## Example: Adding a New Skill Suppose you want to add a **Product Launch Checklist** skill to the `pm-marketing-growth` plugin. ### Create the Skill File Create the file [`pm-marketing-growth/skills/launch-checklist/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-marketing-growth/skills/launch-checklist/SKILL.md). ### Add Required Front-Matter Every skill must start with YAML front-matter declaring `name` and `description`. ```yaml --- name: launch-checklist description: Generate a checklist for a product launch covering marketing, ops, and metrics. --- ``` ### Validate and Submit Run the validator to confirm a zero exit code. ```bash python3 validate_plugins.py ``` Commit your changes with a focused message and open a PR on GitHub. Title it `Add launch-checklist skill` and keep the scope limited to this single addition. Once merged, the skill appears in the marketplace README because the catalog enumerates skills per plugin directory, as shown in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) around lines 39-43. ## Summary - Fork `phuryn/pm-skills`, create a descriptive branch, and clone locally before making any edits. - Place new skills in `skills/` and new commands in `commands/` inside the correct plugin directory. - Run `python3 validate_plugins.py` before pushing to ensure YAML front-matter and naming rules pass. - Follow the single-change policy from [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) and keep each pull request focused on one logical addition. - Expect GitHub Actions to re-run the validator automatically once you open the PR. ## Frequently Asked Questions ### What files should I modify when submitting a PR to pm-skills? You should add or edit Markdown files inside the `skills/` or `commands/` subdirectories of the relevant plugin folder, such as `pm-toolkit/` or `pm-product-strategy/`. Never modify the root-level automation scripts unless you are fixing a bug in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) itself. ### Why does my PR fail CI even though my Markdown looks correct? The project's CI runs [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) on every pull request, and that script checks for required YAML front-matter fields like `name` and `description` in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files, plus `description` and `argument-hint` in command files. Aesthetic Markdown formatting does not guarantee structural compliance, so always run the validator locally before you submit a pull request for pm-skills. ### Can I submit multiple new skills in one pull request? No. [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) lines 12-13 explicitly require one logical change per PR. Bundling multiple skills or unrelated commands forces reviewers to evaluate disparate scope in a single thread and increases merge-conflict risk across plugin directories. ### Where can I find an example of a properly formatted skill file? Reference [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) for a fully-formed skill with correct front-matter and content style. For command syntax and argument hints, see [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md). Both files demonstrate the conventions enforced by [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) and expected by maintainers.