# How the PM Skills Marketplace Plugin Architecture Works: A Deep Dive into the Claude Code Marketplace Model

> Explore the PM Skills marketplace plugin architecture. Discover how Claude Code agents dynamically load skills and workflows from a central manifest.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: deep-dive
- Published: 2026-06-24

---

**The PM Skills marketplace plugin architecture implements a three-layer JSON and Markdown-based system where a central marketplace manifest enumerates plugins, each containing structured skill definitions and command workflows that Claude Code agents auto-discover and load dynamically.**

The phuryn/pm-skills repository demonstrates a production-ready implementation of the Anthropic Claude Code "marketplace" model for AI agent extensibility. This architecture enables modular, versioned distribution of product management capabilities through standardized manifests that any compatible agent—including Claude Code, Claude Cowork, or Gemini CLI—can parse and execute.

## Understanding the Three-Layer Architecture

The PM Skills marketplace plugin architecture organizes functionality into three distinct layers: the marketplace manifest, per-plugin manifests, and individual skill and command definitions. This hierarchy ensures that agents can discover available capabilities at the repository level, validate plugin metadata at the directory level, and execute specific workflows at the file level.

## The Marketplace Manifest

At the root of the repository, [`/.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main//.claude-plugin/marketplace.json) serves as the single entry point for the entire collection. This file contains a JSON schema with a `plugins` array, where each entry points to a plugin directory via the `source` field.

```json
{
  "name": "pm-skills",
  "version": "2.0.0",
  "description": "Structured AI workflows … 9 PM plugins — from discovery to strategy, execution, launch, growth, and shipping AI‑built software.",
  "plugins": [
    {
      "name": "pm-product-discovery",
      "description": "Product discovery skills …",
      "source": "./pm-product-discovery",
      "category": "product-management"
    }
  ]
}

```

When Claude Code starts, it reads this file to determine which plugins exist and to expose high-level descriptions in the marketplace browser.

## Per-Plugin Manifests

Every plugin directory (such as `pm-product-discovery/` or `pm-product-strategy/`) contains a hidden folder `.claude-plugin/` with a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) file. This manifest mirrors the top-level entry while adding **author information**, **keywords**, and **license metadata**.

```json
{
  "name": "pm-product-discovery",
  "version": "2.0.0",
  "description": "Product discovery skills for PMs …",
  "author": { 
    "name": "Paweł Huryn", 
    "email": "pawel@productcompass.pm", 
    "url": "https://www.productcompass.pm" 
  },
  "keywords": ["product-management","discovery","ideation","experiments","assumptions"],
  "homepage": "https://www.productcompass.pm",
  "license": "MIT"
}

```

The validator checks that the `name` field matches the folder name, that required fields exist, and that the manifest follows the JSON schema defined by Anthropic.

## Skills and Command Definitions

Inside each plugin, capabilities divide into **skills** (noun-oriented capabilities) and **commands** (verb-oriented workflows).

### Skill Structure

A skill represents a discrete capability such as `lean-canvas` or `swot-analysis`. Each skill lives in `skills/<skill>/SKILL.md` and must begin with YAML front-matter containing `name` and `description` fields.

```markdown
---
name: lean-canvas
description: |
  Generates a Lean Canvas for a product idea. Triggers when the user asks
  for a "lean canvas" or "business model canvas".
---
<rest of the skill documentation…>

```

The `name` must exactly match the folder name, enabling the agent to auto-load the skill when the user's prompt mentions the noun or configured trigger phrases. The validator's `validate_skill` function parses the front-matter, verifies required fields, and checks name consistency.

### Command Structure

Commands represent executable workflows that chain one or more skills. They reside in `commands/<command>.md` and use YAML front-matter requiring `description` and optionally `argument-hint`.

```markdown
---
description: Prioritize features using the MoSCoW method.
argument-hint: |
  List of features (comma‑separated)
---
**Feature‑Prioritization** skill
1️⃣ Identify Must‑have, Should‑have, Could‑have, Won’t‑have
2️⃣ Return a ranked list

```

Commands can reference skills inside the same plugin using the `**Feature‑Prioritization** skill` syntax. The validator ensures every referenced skill exists via the `validate_cross_references` function.

## Discovery and Loading Flow

The PM Skills marketplace plugin architecture follows a five-step discovery process:

1. **Startup** – The agent loads [`/.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main//.claude-plugin/marketplace.json)
2. **Plugin registration** – For each entry, the agent reads the referenced [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)
3. **Skill indexing** – All [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter is indexed by `name`; the agent auto-loads a skill when its name or trigger phrase appears in the conversation
4. **Command registration** – Command front-matter is indexed; the agent presents them as slash-commands (e.g., `/prioritize-features`)
5. **Execution** – When invoked, the command's Markdown template renders, substituting the `$ARGUMENTS` placeholder with user input

## Validation and Cross-Referencing

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script enforces schema compliance and guarantees that any agent can reliably discover and load components. Run the validator after any change:

```bash
python3 validate_plugins.py

```

The validator performs three critical checks:
- **Schema validation** – Ensures [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) and [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) files match the Anthropic specification
- **Name consistency** – Verifies that plugin folder names match their manifest `name` fields
- **Cross-reference integrity** – Confirms that commands reference only existing skills via `validate_cross_references`

## Versioning and Synchronization

All plugins in the repository share a single version (`2.0.0`). Changing any [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) version requires bumping the marketplace version in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) simultaneously. Additionally, the `description` fields in [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) and the marketplace manifest must stay identical; the repository's [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) mirrors these descriptions for human readers.

## Summary

- **Three-layer architecture**: Marketplace manifest ([`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json)) → Plugin manifests ([`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)) → Skills and commands (Markdown files)
- **Auto-discovery**: Agents load capabilities dynamically by parsing JSON manifests and Markdown front-matter
- **Strict validation**: The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script ensures schema compliance and cross-reference integrity
- **Unified versioning**: All components maintain synchronized version `2.0.0` across the repository
- **Skill vs. command distinction**: Skills are noun-oriented capabilities; commands are verb-oriented workflows that chain skills

## Frequently Asked Questions

### What is the entry point for the PM Skills marketplace plugin architecture?

The entry point is [`/.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main//.claude-plugin/marketplace.json). This JSON file contains a `plugins` array that enumerates every available plugin with its `source` directory, enabling agents to discover the entire capability set upon startup.

### How does the validator ensure plugin integrity?

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script enforces integrity through three mechanisms: it validates JSON schemas against Anthropic's specification, checks that folder names match manifest `name` fields, and verifies that commands reference only existing skills via `validate_cross_references`.

### What distinguishes a skill from a command in this architecture?

**Skills** are noun-oriented capabilities (like `lean-canvas` or `swot-analysis`) defined in `skills/<skill>/SKILL.md` that auto-load when mentioned. **Commands** are verb-oriented workflows defined in `commands/<command>.md` that execute when invoked via slash-commands (e.g., `/prioritize-features`) and can chain multiple skills together.

### How does auto-loading work for skills?

When a user's prompt contains a skill's `name` or configured trigger phrases from the YAML front-matter, the agent automatically loads that skill's Markdown documentation into the context. This enables contextual assistance without explicit command invocation.