# Understanding the PM Skills Plugin Architecture: A Deep Dive into Claude Code's Marketplace System

> Explore the PM Skills plugin architecture, a modular Claude Code marketplace. Discover how plugins bundle skills and commands validated by a Python pipeline for manifest integrity.

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

---

**The PM Skills plugin architecture is a modular marketplace system for Claude Code where plugins bundle reusable skills and slash commands using markdown files with YAML frontmatter, enforced by a Python validation pipeline that ensures manifest integrity and cross-reference accuracy.**

The **phuryn/pm-skills** repository implements a file-based plugin architecture designed for Claude Code's extensible ecosystem. This system organizes product management workflows into discrete, reusable components—grouping together **68 skills** and **42 chained workflows** across nine specialized plugins. Understanding the PM Skills plugin architecture reveals how domain-specific knowledge is packaged, validated, and invoked through simple markdown conventions.

## Directory Structure and Plugin Layout

Each plugin in the marketplace follows a strict directory convention required by Claude Code's plugin specification. The architecture mandates a specific hierarchy where content and metadata are separated into predictable locations:

```

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Manifest with name, version, description

├── skills/                  # One subfolder per skill

│   └── <skill-name>/
│       └── SKILL.md         # Markdown with YAML frontmatter

├── commands/                # One file per slash command

│   └── <command-name>.md
└── README.md                # Human-readable documentation

```

This structure allows Claude Code to automatically discover and register plugin contents without explicit imports or configuration files beyond the manifest.

## Core Components of the PM Skills Plugin Architecture

### The Plugin Manifest (.claude-plugin/plugin.json)

The **[`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)** file serves as the plugin's identity card, containing required fields that `validate_manifest()` checks for completeness. According to [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 16-44), the validator ensures three critical constraints:

1. **Required fields**: `name`, `version`, and `description` must be present (lines 33-36)
2. **Directory matching**: The `name` field must exactly match the parent directory name (lines 38-41)
3. **Schema compliance**: Additional metadata like `author`, `email`, and `keywords` are validated for type correctness

A valid manifest enables Claude Code to index the plugin correctly within the marketplace.

### Skill Definitions (skills/*/SKILL.md)

**Skills** are standalone knowledge artifacts encapsulated in markdown files with YAML frontmatter. Each skill resides in its own subdirectory under `skills/`, with the folder name matching the skill's internal identifier.

The `validate_skill()` function (lines 82-108 in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)) enforces:

- **Frontmatter parsing**: Uses `parse_yaml_frontmatter` to extract metadata
- **Required fields**: Both `name` and `description` must exist in the YAML block (lines 102-108)
- **Name consistency**: The frontmatter `name` must match the containing folder name (line 107)

This design makes skills completely portable and self-describing.

### Command Workflows (commands/*.md)

**Commands** represent user-triggered workflows invoked via slash commands (e.g., `/discover`). Unlike skills, commands are single markdown files stored directly in `commands/` that orchestrate multiple skills into sequential workflows.

The architecture allows commands to reference skills using a specific markdown pattern:

```markdown
**brainstorm-ideas-new** skill
**identify-assumptions-new** skill

```

The `validate_command()` function (lines 32-53) parses these references and `validate_cross_references()` (lines 89-100) verifies that every referenced skill actually exists within the same plugin using the regex pattern `\*\*(\w[\w-]+)\*\*\s+skill`.

### The Validation Pipeline

The **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** script serves as the architectural gatekeeper, orchestrating all validation through a central `validate_plugin()` function (lines 15-55). This pipeline executes four critical checks:

- **`validate_manifest()`**: Ensures plugin identity and versioning
- **`validate_skill()`**: Verifies skill frontmatter and directory naming
- **`validate_command()`**: Confirms command files contain proper frontmatter
- **`validate_cross_references()`**: Guarantees command-to-skill links resolve correctly
- **`validate_readme()`**: Checks for four expected documentation sections (lines 68-84)

The entry-point `main()` function discovers all plugin directories containing `.claude-plugin/` subfolders (lines 81-88), making the validation process fully automated for CI/CD integration.

## How the Pieces Fit Together

When a user interacts with the PM Skills marketplace, the architecture executes a three-phase workflow:

1. **Discovery**: Claude Code auto-registers plugins by scanning for [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) files. No manual import statements are required because the filesystem structure itself defines the plugin boundaries.

2. **Invocation**: When a user types a slash command like `/discover`, Claude Code loads the corresponding markdown file from `commands/`, parses its frontmatter, and executes the workflow. The command file acts as a manifest that sequences skill invocations.

3. **Skill Reuse**: Commands chain skills by name reference. Because skills are standalone assets with standardized frontmatter, any command can invoke any skill within the same plugin, enabling composable workflows like ideation → assumption mapping → prioritization → experiment design.

## Implementation Examples from the Source Code

### Minimal Plugin Manifest

```json
{
  "name": "pm-product-discovery",
  "version": "1.3.0",
  "description": "Discovery workflows – brainstorming, assumption mapping, prioritisation, and experiments.",
  "author": {
    "name": "Paweł Huryn",
    "email": "pawel@example.com"
  },
  "keywords": ["discovery", "ideation", "assumptions"]
}

```

*The validator checks this against the directory name and ensures all required fields are present (validate_plugins.py#L33-41).*

### Skill Definition with Frontmatter

```markdown
---
name: brainstorm-ideas-new
description: Ideation for new products in the early discovery phase.
---

# Brainstorm Ideas – New

Facilitate structured ideation sessions for zero-to-one products...

```

*The `name` field must match the folder name `brainstorm-ideas-new/` (validate_plugins.py#L107).*

### Command Chaining Multiple Skills

```markdown
---
description: Full discovery cycle – ideation → assumption mapping → prioritisation → experiment design
argument-hint: <product-idea>
---

**brainstorm-ideas-new** skill
**identify-assumptions-new** skill
**prioritize-assumptions** skill
**brainstorm-experiments-new** skill

```

*The validator extracts skill references using regex `\*\*(\w[\w-]+)\*\*\s+skill` (validate_plugins.py#L104-106) and verifies they exist in the `skills/` directory.*

### User Invocation

Users trigger workflows through Claude Code's chat interface:

```

/discover AI-powered meeting summarizer for remote teams

```

Claude Code executes the `/discover` command, which internally runs the four referenced skills in sequence, yielding a complete product discovery workflow.

## Extending the PM Skills Architecture

Adding capabilities requires no code changes—only markdown files. To introduce a new skill:

1. Create a folder under `plugin-name/skills/<skill-name>/`
2. Add [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) with required YAML frontmatter (`name` and `description`)
3. Reference it in commands using `**skill-name** skill` syntax
4. Update the plugin's [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) with the four required sections (overview, install, skill, command)

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script automatically detects new content during CI runs, ensuring that frontmatter is complete and cross-references are valid before publication.

## Summary

- **Plugin structure** consists of a [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest, `skills/` directory containing markdown assets with YAML frontmatter, and `commands/` directory housing workflow definitions.
- **Validation logic** in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) enforces architectural constraints through specialized functions: `validate_manifest()` checks identity fields, `validate_skill()` verifies frontmatter completeness, and `validate_cross_references()` ensures command-to-skill links resolve correctly.
- **Skill referencing** uses the markdown pattern `**skill-name** skill`, parsed by regex to build dependency graphs between commands and their constituent skills.
- **Extensibility** is file-based: adding capabilities requires only new markdown files in the correct directories, validated automatically by the Python pipeline.

## Frequently Asked Questions

### What is the purpose of the .claude-plugin directory?

The **`.claude-plugin`** directory serves as the plugin discovery marker and metadata container. It houses the mandatory [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest file that defines the plugin's identity, version, and author information. According to the `main()` function in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) (lines 81-88), the validator identifies valid plugins by scanning for directories containing this specific hidden folder.

### How does the validator check for broken skill references?

The `validate_cross_references()` function (lines 89-100 in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)) prevents broken links by scanning command files for the pattern `**skill-name** skill` using the regex `\*\*(\w[\w-]+)\*\*\s+skill`. It extracts all referenced skill names and verifies that matching directories exist within the plugin's `skills/` folder. If a command references a non-existent skill, the validator logs a warning before the plugin can be published.

### What fields are required in a skill's YAML frontmatter?

Every **SKILL.md** file must include two mandatory fields in its YAML frontmatter: `name` and `description`. The `validate_skill()` function (lines 82-108) explicitly checks for these fields using `parse_yaml_frontmatter`, and further validates that the `name` value exactly matches the containing folder name. This ensures consistency between filesystem structure and metadata declarations.

### Can I create custom commands that chain multiple skills?

Yes, commands are designed specifically for chaining skills into workflows. Simply create a markdown file in `commands/` with a `description` field in the frontmatter, then list skills using the `**skill-name** skill` syntax. The validator will confirm that all referenced skills exist. This architecture allows complex workflows—such as the `/discover` command that chains four distinct skills—without writing any executable code.