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

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 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.

{
  "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 file. This manifest mirrors the top-level entry while adding author information, keywords, and license metadata.

{
  "name": "pm-product-discovery",
  "version": "2.0.0",
  "description": "Product discovery skills for PMs …",
  "author": { 
    "name": "Paweł Huryn", 
    "email": "[email protected]", 
    "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.

---
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.

---
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
2. Plugin registration – For each entry, the agent reads the referenced plugin.json
3. Skill indexing – All 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 script enforces schema compliance and guarantees that any agent can reliably discover and load components. Run the validator after any change:

python3 validate_plugins.py

The validator performs three critical checks:

• Schema validation – Ensures marketplace.json and 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 version requires bumping the marketplace version in marketplace.json simultaneously. Additionally, the description fields in plugin.json and the marketplace manifest must stay identical; the repository's README.md mirrors these descriptions for human readers.

Summary

• Three-layer architecture: Marketplace manifest (marketplace.json) → Plugin manifests (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 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. 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 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.

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