Testing Custom PM Skills Before Marketplace Submission: A Complete Validation Guide

Use the built-in validate_plugins.py script to check manifest compliance, skill front-matter, command syntax, and cross-references before submitting your Claude Code plugins to the marketplace.

The phuryn/pm-skills repository provides a comprehensive framework for packaging Product Management knowledge as reusable Claude Code plugins. Before submitting your custom skills to the marketplace, you must verify that your plugin structure, metadata, and internal references conform to the Claude Code specification. The repository includes a standalone validator that automates this compliance checking.

Understanding the Plugin Architecture

Each PM skill plugin in the repository follows a standardized directory structure. A valid plugin directory contains a .claude-plugin/ folder containing a plugin.json manifest, a skills/ directory with markdown knowledge files, and optionally a commands/ directory for slash-command definitions.

According to the phuryn/pm-skills source code, the validator recognizes plugins by detecting the .claude-plugin/plugin.json file. This manifest declares the plugin's name, version, description, author, and keywords required by Claude Code. Each skill resides in skills/<skill-name>/SKILL.md with YAML front-matter specifying the skill's name and description. Commands live in commands/<command-name>.md and can reference skills using the pattern **skill-name** skill.

The Validation Framework

The validate_plugins.py script serves as the gatekeeper for marketplace quality. Located in the repository root, this validator performs six distinct compliance checks to ensure your custom PM skills meet submission standards.

Plugin Discovery

The validator's main() function walks the repository root and identifies any directory containing a .claude-plugin/ folder as a Claude Code plugin. This mechanism ensures the script only processes intentional plugin structures while ignoring documentation or configuration files.

Manifest Validation

The validate_manifest() function loads each plugin's plugin.json and enforces required fields: name, version, and description. It verifies that the manifest name matches the directory name and validates author sub-fields for completeness. Missing required fields trigger immediate errors that block submission readiness.

Skill Validation

For each SKILL.md file found in skills/*/, the validate_skill() function extracts YAML front-matter and verifies that the skill name matches its containing folder name. The validator enforces minimum description length and word-count limits to ensure skills provide sufficient context for AI activation.

Command Validation

The validate_command() function parses markdown files in the commands/ directory, checking for required front-matter fields including description and optional argument-hint specifications. It records skill references embedded as **skill-name** skill patterns for subsequent cross-reference validation.

Cross-Reference Verification

The validate_cross_references() function scans every command for skill references and validates that each referenced skill actually exists within the same plugin. This prevents broken workflows where commands attempt to invoke non-existent skills, ensuring end-to-end functionality.

README Requirements

Finally, validate_readme() confirms that each plugin contains a README.md with mandatory sections: overview, install, skill, and command. These sections provide human-readable documentation essential for marketplace discoverability.

Step-by-Step Testing Workflow

Follow this workflow to validate your custom PM skills before marketplace submission:

1. Clone the repository and navigate to your plugin directory:

   git clone https://github.com/phuryn/pm-skills.git
   cd pm-skills

2. Create your skill with proper front-matter:

   mkdir -p pm-product-discovery/skills/my-new-skill
   cat > pm-product-discovery/skills/my-new-skill/SKILL.md <<'EOF'
   ---
   name: my-new-skill
   description: |
     A comprehensive description explaining when to trigger this skill
     and what PM framework it implements.
   ---
   # My New Skill
   
   … markdown content …
   EOF

3. Optionally add a command that invokes your skill:

   mkdir -p pm-product-discovery/commands
   cat > pm-product-discovery/commands/my-new-command.md <<'EOF'
   ---
   description: Run my-new-skill as part of a custom discovery flow
   argument-hint: "<idea>"
   ---
   **my-new-skill** skill
   EOF

4. Run the validator from the repository root:

   python3 validate_plugins.py .

5. Address any reported errors or warnings, then repeat step 4 until the validator reports a clean pass.

Interpreting Validation Results

The validator outputs a color-coded report indicating compliance status for each plugin. A successful validation shows:

┌─ pm-product-discovery  [13 skills, 5 commands]  ✓ PASS
  Manifest:
    ✔ … (no errors)
  Skills with issues:
    (none)
  Commands with issues:
    (none)

Warnings appear for non-critical issues like short descriptions, while errors indicate blocking problems such as missing required front-matter fields or broken cross-references. The script exits with a non-zero status if any plugin fails validation, making it suitable for CI/CD pipelines.

Summary

• Validate early and often using python3 validate_plugins.py . to catch compliance issues during development.
• Maintain manifest integrity by ensuring .claude-plugin/plugin.json contains all required fields and matches your directory name.
• Follow front-matter conventions for skills (name, description) and commands (description, optional argument-hint).
• Verify cross-references using the **skill-name** skill pattern to ensure commands can locate their dependencies.
• Include comprehensive READMEs with the four required sections: overview, install, skill, and command.

Frequently Asked Questions

What happens if I forget to add the description field to my skill's front-matter?

The validate_skill() function in validate_plugins.py will report an error indicating that the required field is missing. Each SKILL.md file must include both name and description in its YAML front-matter to pass validation.

Can I reference skills from other plugins in my commands?

No. The validate_cross_references() function only validates skill references within the same plugin directory. If your command references a skill using the **skill-name** skill pattern, that skill must exist in your plugin's skills/ directory.

How do I know if my plugin has been detected by the validator?

The validator's main() function specifically looks for directories containing a .claude-plugin/ folder. If your plugin appears in the validation report with a checkmark or error list, it has been detected. If it doesn't appear, verify that your plugin.json exists at .claude-plugin/plugin.json relative to your plugin root.

What is the minimum content required for a marketplace-ready plugin?

According to the validation logic, you need: a valid .claude-plugin/plugin.json with name, version, and description; at least one skill in skills/ with proper front-matter; and a README.md containing the overview, install, skill, and command sections. While optional, commands in commands/ require the description front-matter field if present.

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