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

> Easily test custom PM skills before marketplace submission using a Python script. Validate manifest compliance, front-matter, command syntax, and cross-references.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-07-05

---

**Use the built-in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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:
   ```bash
   git clone https://github.com/phuryn/pm-skills.git
   cd pm-skills
   ```

2. Create your skill with proper front-matter:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) will report an error indicating that the required field is missing. Each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) exists at [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) with `name`, `version`, and `description`; at least one skill in `skills/` with proper front-matter; and a [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) containing the overview, install, skill, and command sections. While optional, commands in `commands/` require the `description` front-matter field if present.