# How to Contribute a New Skill to phuryn/pm-skills: A Complete Guide > Learn how to contribute a new skill to phuryn/pm-skills. Follow our guide to create a directory, SKILL.md file, validate locally, and submit a pull request. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-28 --- **To contribute a new skill to phuryn/pm-skills, open an issue to discuss the scope, create a kebab-case directory with a SKILL.md file containing required YAML front-matter, validate locally with validate_plugins.py, and submit a focused pull request.** The **pm-skills** repository organizes product management expertise into modular skills and commands. If you want to expand this open-source marketplace with new domain knowledge, following the canonical contribution workflow ensures your submission passes automated validation and review. This guide walks through the exact steps required to add a skill, from initial issue creation to final merge. ## Understanding the Repository Structure Before writing content, you must understand how the repository organizes its components. ### Skills vs. Commands The repository maintains a strict separation between two content types: - **Skills** – Static knowledge modules stored as markdown files with YAML front-matter. These live in category directories like `pm-toolkit/skills/`, `pm-product-strategy/skills/`, or `pm-market-research/skills/`. Each skill occupies its own subdirectory containing a single [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. - **Commands** – Reusable CLI-style workflow scripts stored in `pm-toolkit/commands/`. These represent actions rather than knowledge. Skills are **nouns** representing domain expertise (e.g., `grammar-check`, `market-sizing`), while commands are **verbs** describing actions (e.g., `privacy-policy`). This naming convention keeps the marketplace discoverable and intuitive. ### The Validator Script The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script enforces structural rules across the repository. According to the source code, this validator checks: - Front-matter field presence and validity - Naming conventions and directory alignment - Markdown formatting standards All contributions must pass this validation before maintainers can merge your pull request. ## Step-by-Step Contribution Process ### 1. Open an Issue First Because a new skill constitutes a larger architectural change, start by opening a GitHub issue to discuss scope and design. The [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) file explicitly requires this step for "new skills, commands, or larger changes" to ensure alignment with project goals before you invest development time. ### 2. Create the Skill Directory Choose the appropriate category folder (e.g., `pm-toolkit/skills/`). Create a new subdirectory using **kebab-case** naming that matches your skill's intended name. For example, a market sizing skill would live at `pm-market-research/skills/market-sizing/`. This directory must contain exactly one file: [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). ### 3. Add Required Front-Matter Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) must begin with a YAML block containing two mandatory fields: ```yaml --- name: market-sizing description: Guidance on estimating market size for a product. --- ``` **Critical:** The `name` field must exactly match the directory name. The validator enforces this rule to ensure the marketplace UI can correctly index and display your skill. ### 4. Write Skill Content After the front-matter, add instructional text, examples, and tables using standard markdown. Reference existing skills like [`pm-toolkit/skills/grammar-check/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/grammar-check/SKILL.md) for style consistency. Remember that commands cannot directly reference other plugins; any coordination should be expressed in natural language within the skill description. ### 5. Validate Locally Before committing, run the validation script from the repository root: ```bash python3 validate_plugins.py ``` The script outputs conformance status for all skill files. If you see errors like missing front-matter fields or naming mismatches, correct them before proceeding. ### 6. Submit a Pull Request Push your branch to GitHub and open a pull request. Follow the project's PR guidelines: one logical change per request, clear descriptive title, and concise explanation of the expertise your skill adds. Maintainers will run the CI validator, review content accuracy, and merge after any necessary feedback. ## Anatomy of a SKILL.md File Here is a complete, valid example for a new skill. Save this as [`pm-market-research/skills/market-sizing/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-market-research/skills/market-sizing/SKILL.md): ```markdown --- name: market-sizing description: Guidance on estimating market size for a product. --- # Market Sizing This skill walks you through a structured approach to calculate TAM, SAM, and SOM. ## Steps 1. **Define the total addressable market (TAM)** – Identify the overall revenue potential. 2. **Segment the serviceable market (SAM)** – Narrow down to the portion you can realistically serve. 3. **Calculate the share of market (SOM)** – Estimate the percentage you expect to capture. ### Example Calculation | Segment | Revenue (USD) | |---------|---------------| | TAM | $10 B | | SAM | $2 B | | SOM | $200 M | > Use the above numbers as a starting point and refine based on your product specifics. ``` ## Running the Validator Locally Execute the validator to ensure your contribution meets schema requirements: ```bash $ python3 validate_plugins.py ✔ All skill files conform to the required schema. ``` If the validator reports errors, adjust your front-matter or file placement accordingly. Common failures include mismatched `name` fields or missing `description` values. ## Key Files and References - **[`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md)** – The official contribution guide detailing naming rules and validator usage. - **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** – The Python script enforcing front-matter and naming conventions. - **[`pm-toolkit/skills/grammar-check/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/grammar-check/SKILL.md)** – A reference implementation showing correct skill structure. ## Summary - Open an issue first for new skills to align on scope and design. - Create a kebab-case directory matching your skill name and add a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with required YAML front-matter. - Ensure the `name` field in front-matter matches the directory name exactly. - Run `python3 validate_plugins.py` locally before submitting your pull request. - Submit focused PRs with clear descriptions to streamline the review process. ## Frequently Asked Questions ### What is the difference between a skill and a command in pm-skills? **Skills** are noun-based knowledge modules (like `market-sizing` or `grammar-check`) stored in `skills/` directories, while **commands** are verb-based action scripts stored in `commands/` directories. This distinction maintains clear separation between domain knowledge and executable workflows. ### Why must I open an issue before contributing a new skill? The [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) requires issues for substantial changes like new skills to prevent wasted effort and ensure architectural alignment. Discussing scope upfront allows maintainers to suggest category placement and validate that the proposed skill fits the project's coverage goals. ### What happens if the validator fails when I run validate_plugins.py? The script will output specific error messages indicating which files violate the schema—commonly missing front-matter fields, naming mismatches between directory and YAML `name` values, or malformed markdown. Fix these issues locally and re-run the validator until you see the success message. ### Can I reference other skills within my skill content? No. The architecture prohibits direct cross-plugin references. Instead, express relationships or workflows in natural language within your skill's descriptive text, describing how your knowledge module relates to other product management concepts without technical linking.