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

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 file serves as the plugin's identity card, containing required fields that validate_manifest() checks for completeness. According to 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) 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:

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

{
  "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

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

---
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 with required YAML frontmatter (name and description)
3. Reference it in commands using **skill-name** skill syntax
4. Update the plugin's README.md with the four required sections (overview, install, skill, command)

The 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 manifest, skills/ directory containing markdown assets with YAML frontmatter, and commands/ directory housing workflow definitions.
• Validation logic in 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 manifest file that defines the plugin's identity, version, and author information. According to the main() function in 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) 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.

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