How to Contribute a New Skill to the PM‑Skills Marketplace

To contribute a new skill to the marketplace, create a dedicated folder containing a SKILL.md file with valid YAML front-matter inside the appropriate plugin's skills/ directory, then validate your changes locally using validate_plugins.py before opening a pull request.

The PM‑Skills repository is an open-source collection of plugins that encapsulate domain-specific knowledge for product managers. If you want to contribute a new skill to the marketplace, you must follow the repository's strict validation rules enforced by the CI pipeline and the validate_plugins.py script.

Understanding the Plugin Architecture

The repository organizes functionality into plugins (such as pm-toolkit, pm-product-discovery, and pm-market-research), each grouping related skills (nouns representing domain knowledge) and commands (verbs that execute workflows). The available plugins are defined in .claude-plugin/marketplace.json, which serves as the central manifest listing all nine plugin directories. Before contributing, you must identify which existing plugin best matches your skill's domain, as all skills must reside within one of these nine official plugin directories.

Step-by-Step Contribution Process

Select the Correct Plugin

Navigate to .claude-plugin/marketplace.json to review the available plugin directories. Choose the plugin that aligns with your skill's domain area. For example, a market-research skill belongs in pm-market-research, while general productivity tools belong in pm-toolkit. You cannot create top-level skills; they must be nested within a plugin's skills/ subdirectory.

Create the Skill Directory

Inside your chosen plugin's skills/ directory, create a new folder named exactly as your skill identifier (e.g., product-positioning). According to validate_plugins.py (lines 86-89), this folder name must identically match the name field you will specify in the skill's front-matter. Use kebab-case (lowercase with hyphens) for consistency with existing conventions.

Write the SKILL.md File

Every skill requires a SKILL.md file containing YAML front-matter followed by markdown content. The validator (validate_plugins.py, lines 95-104) enforces that this front-matter includes at minimum the name and description fields. Additionally, lines 215-219 recommend including trigger phrases such as "use when" or "use for" in the description to improve discoverability.

Create the file using this template structure:

cd pm-toolkit/skills
mkdir product-positioning
cat > product-positioning/SKILL.md <<'EOF'
---
name: product-positioning
description: "Generate positioning statements for a new product. Use when you need to define target customers, primary needs, and unique value propositions based on market data."
---

# Product Positioning

You are a product manager tasked with crafting a concise positioning statement.

## Input Arguments

- $TARGET_CUSTOMER: Who benefits most?
- $PRIMARY_NEED: Core problem being solved
- $UNIQUE_VALUE: What makes the solution stand out

## Output

Return a one-sentence positioning statement.
EOF

Validate Locally

Before submitting, run the validator from the repository root to ensure your skill passes all checks:

python3 validate_plugins.py

The script scans every plugin directory and reports errors, warnings, and notes for each skill and command. A clean run (zero errors) is required for CI to pass. If validation fails, you will see specific error messages indicating which front-matter fields are missing or malformed. For example:

 Plugin Collection Validator — Report
 ┌─ pm-toolkit  [4 skills, 4 commands]  ✓ PASS
   Skills with issues:
     product-positioning:
       ✗ ERROR: Missing required frontmatter field: description

Fix any reported errors before proceeding.

Submit Your Contribution

As outlined in CONTRIBUTING.md (lines 7-9), open an issue first if your skill adds significant new functionality or changes existing behavior. For straightforward additions, fork the repository, commit your new skill folder, and open a pull request focused on this single change. The PR should include a link to the new skill folder and a brief usage description. The maintainer will run validate_plugins.py and either request adjustments or merge your contribution.

Validation Requirements and Best Practices

To ensure your contribution is accepted, adhere to these constraints enforced by the validator:

• Front-matter fields: Must include name and description keys with proper YAML formatting
• Directory naming: The folder name must exactly match the name value in front-matter (case-sensitive)
• Trigger phrases: Include "use when" or "use for" in descriptions to indicate activation contexts
• No extra keys: Do not add custom front-matter fields beyond the standard set
• Single focus: Keep each pull request limited to one skill or logical change

Summary

• Skills in the PM‑Skills repository reside within plugin-specific skills/ directories, not at the repository root
• You must create a folder named exactly as the skill identifier, containing a SKILL.md file with valid YAML front-matter including name and description
• The validator (validate_plugins.py) enforces folder-to-front-matter naming consistency (lines 86-89) and required field presence (lines 95-104)
• Run python3 validate_plugins.py locally to catch errors before submitting your pull request
• For significant changes, open an issue first per CONTRIBUTING.md (lines 7-9)

Frequently Asked Questions

What file naming convention should I follow for new skills?

Create a directory using kebab-case (lowercase words separated by hyphens) that matches exactly the name field in your SKILL.md front-matter. For example, if your skill name is customer-interview-guide, the folder must be named customer-interview-guide. The validator checks this correspondence at lines 86-89 of validate_plugins.py and will fail if they differ.

Why does my skill fail validation even with correct front-matter?

Common failures include improper YAML syntax (such as unquoted descriptions containing colons), missing required fields, or extra custom keys in the front-matter. The validator at lines 95-104 checks for the exact schema. Ensure your description is properly quoted and includes recommended trigger phrases like "use when" (lines 215-219) to avoid warnings.

Can I create a new plugin instead of adding to an existing one?

The marketplace manifest in .claude-plugin/marketplace.json defines the nine official plugin directories. You cannot create new top-level plugins without modifying this manifest, which requires maintainer approval. For most contributors, selecting the existing plugin that best fits your skill's domain is the correct approach.

How do I test my skill before submitting a PR?

Run python3 validate_plugins.py from the repository root. This script performs the same checks as the CI pipeline, verifying that your skill's directory structure, front-matter fields, and naming conventions meet repository standards. A successful run with zero errors indicates your skill is ready for submission.

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