How to Submit a Pull Request for pm-skills: Step-by-Step Contributor Guide

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.

Contributing new skills or commands to the pm-skills project involves a structured workflow defined in CONTRIBUTING.md and enforced by the 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.

git clone https://github.com/<your-username>/pm-skills.git
cd pm-skills
git checkout -b add-<descriptive-branch-name>

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 around lines 38-40, each plugin contains a skills/ subdirectory with Markdown-formatted 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 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 script checks every skill and command file for required YAML front-matter, naming consistency, and folder placement, as documented in CONTRIBUTING.md at lines 18-19.

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.

git add .
git commit -m "Add <skill-or-command-name>"
git push origin <branch-name>

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 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 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 around lines 38-41.

Front-Matter Enforcement

Every 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 script parses these blocks and fails if they are missing or malformed, which is why CONTRIBUTING.md lines 14-16 stress strict front-matter compliance.

---
name: example-skill
description: Concise explanation of what the skill does.
---

Single-Change PR Policy

The maintainers enforce a focused contribution model. 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.

Add Required Front-Matter

Every skill must start with YAML front-matter declaring name and description.

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

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

Why does my PR fail CI even though my Markdown looks correct?

The project's CI runs validate_plugins.py on every pull request, and that script checks for required YAML front-matter fields like name and description in 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 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 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. Both files demonstrate the conventions enforced by validate_plugins.py and expected by maintainers.

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