# How to Contribute New Skills to the PM-Skills Marketplace: A Step-by-Step Guide > Learn how to contribute new skills to the pm-skills marketplace with our step-by-step guide. Follow our process to add your expertise. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-07-01 --- **To contribute a new skill to the pm-skills marketplace, you must open a GitHub issue for discussion first, create a dedicated skill folder with a properly formatted [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file containing YAML front-matter, validate your changes using the repository validator, and submit a focused pull request against the `main` branch.** The pm-skills repository (phuryn/pm-skills) provides a structured marketplace for product management skills and commands organized as plugins. The contribution process is governed by [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) and requires strict adherence to naming conventions, file structures, and validation rules to maintain consistency across the ecosystem. ## Start with a GitHub Issue Before writing any code, open a GitHub issue to discuss your proposed skill. This step allows maintainers to review the skill's scope, naming convention, and alignment with the marketplace architecture. According to [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md), new skills, commands, or larger changes always require an issue first. This prevents duplicate efforts and ensures the skill fits within the appropriate plugin category (such as `pm-product-discovery` or `pm-toolkit`). ## Create the Skill Files Once the maintainers approve your idea, create a new folder under the appropriate plugin directory. ### Folder Structure and Naming Place your skill in a folder path like `pm-product-discovery/skills//` or `pm-toolkit/skills//`. The folder name must match exactly the value you provide in the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter. ### SKILL.md Format Requirements Create a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file inside your skill folder with the following structure: ```markdown --- name: my-new-skill description: "Brief description of what the skill does and when to use it." --- # My New Skill ``` - The `name` field **must** match the directory name. - The `description` must be at least 30 characters; include trigger phrases like "Use when..." for better discoverability. - 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 layout conventions. ## Validate Your Changes Locally Run the repository validator before submitting to catch formatting errors early. ```bash python3 validate_plugins.py ``` This script, located in the repository root, performs automated checks on: - YAML front-matter integrity (`name` and `description` fields) - Skill name and folder name consistency - Word count requirements - Cross-references between the manifest and skill files Successful validation displays a green "✓ PASS" summary. Errors or warnings specific to your new skill will appear in the output if the front-matter is malformed or naming conventions are violated. ## Submit a Pull Request After validation passes and the original issue receives approval, push your new folder to a feature branch and open a pull request against `main`. - Keep the PR focused on a **single** change (the new skill). - Link the PR description back to the original issue for traceability. - Ensure the plugin manifest at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) remains synchronized if you modified plugin-level metadata. ## Maintainer Review and Merge Maintainers will run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) against your branch, review the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter, and verify adherence to repository conventions. The review process ensures the skill follows the architectural patterns described in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) before merging into the marketplace. ## Summary - **Open an issue first** to discuss new skills with maintainers and confirm scope. - **Create a skill folder** under the correct plugin directory with a matching name (e.g., `pm-product-discovery/skills/my-skill/`). - **Write SKILL.md** with required YAML front-matter including `name` (matching folder) and `description` (≥30 characters). - **Validate locally** using `python3 validate_plugins.py` to check front-matter, naming, and content rules. - **Submit a focused PR** linking back to the approved issue for final review and merge. ## Frequently Asked Questions ### Do I need to open an issue before submitting a new skill? Yes, [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) explicitly requires opening a GitHub issue first for new skills, commands, or larger changes. This allows maintainers to review the proposal, suggest appropriate plugin placement, and ensure the naming convention aligns with existing marketplace entries before you invest time in implementation. ### What is the minimum required content for a SKILL.md file? Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) must contain YAML front-matter with at least two fields: `name` (which must exactly match the folder name) and `description` (minimum 30 characters). The body content should follow the structure of 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), including practical usage guidance and trigger phrases. ### How do I validate my skill locally before submitting? Run `python3 validate_plugins.py` from the repository root. This script checks for valid YAML front-matter, name/folder consistency, description length, and cross-references. A successful run produces a "✓ PASS" message, while errors list specific violations requiring correction before the PR can be accepted. ### Can I submit multiple skills in a single pull request? No, maintainers require each pull request to focus on a single change. When adding a new skill, submit exactly one skill per PR and link it back to the specific issue discussing that skill. This keeps the review process focused and allows individual skills to be reverted independently if necessary.