# How the PM Skills Marketplace Ensures Cross-Plugin Decoupling: 5 Architectural Strategies

> Learn how the PM Skills Marketplace ensures cross plugin decoupling with 5 architectural strategies. Discover self-contained directories, manifest isolation, and automated validation.

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

---

**The PM Skills Marketplace achieves cross-plugin decoupling through self-contained plugin directories, manifest-based isolation, a strict "no cross-plugin references" policy, automated validation via [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), and unified versioning that prevents runtime mismatches.**

The `phuryn/pm-skills` repository implements a modular architecture where nine independent plugins coexist without hard dependencies. This design ensures that product management teams can install, upgrade, or remove specific skill sets without risking cascading failures across the ecosystem. The repository enforces **cross-plugin decoupling** through a combination of directory isolation, manifest-based configuration, and automated validation rules.

## Self-Contained Plugin Architecture with Isolated Manifests

Each plugin resides in its own `pm-<domain>/` directory (such as `pm-execution/`) and ships a dedicated `pm-<domain>/.claude-plugin/plugin.json` manifest. This file describes the plugin’s name, version, author, and the specific skills and commands it provides. The central [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) acts solely as a registry that lists available plugins without hard-coding any command-to-command or skill-to-skill cross-references. This manifest separation ensures that the marketplace remains agnostic to the internal implementation details of individual plugins.

## Strict Command Isolation: No Cross-Plugin References

According to [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md), the architecture explicitly forbids commands in one plugin from invoking commands in another. Commands may only reference skills that reside within the same plugin, preventing breaking dependencies when plugins are added, removed, or version-bumped. The [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) architecture guide reinforces this rule, stating that "No cross-plugin references" are permitted in command implementations. This policy creates hard boundaries that prevent implicit coupling between distinct product management domains.

## Explicit Skill Loading With Force-Load Syntax

While skills are intra-plugin by default, the repository supports explicit cross-plugin skill invocation through a force-load syntax. Users can load a skill from another plugin using the `/plugin-name:skill-name` pattern (for example, `/pm-execution:brainstorm-okrs`). As documented in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md), this approach maintains static decoupling while allowing runtime flexibility. The explicit nature of this syntax ensures that any cross-plugin interaction is intentional and visible rather than hidden in implicit dependencies.

## Automated Decoupling Validation in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)

The repository ships with a [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script that automatically enforces decoupling constraints during continuous integration. This validator checks for manifest consistency, semantic-version alignment, and—critically—intra-plugin command-to-skill reference validation. Any detected cross-plugin reference triggers a validation error, preventing accidentally coupled code from merging into the main branch. The validation workflow is detailed in [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md), ensuring that architectural standards are maintained programmatically rather than relying solely on human review.

## Unified Versioning to Prevent Runtime Coupling

All nine plugins share a single version number (for example, `2.0.0`), synchronized across the entire marketplace. When any plugin’s manifest is updated, the [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) is bumped simultaneously, guaranteeing that the installed set of plugins remains compatible. This unified versioning policy eliminates hidden runtime mismatches that could otherwise create subtle coupling issues between different plugin versions, ensuring that the ecosystem operates as a coherent but decoupled whole.

## Practical Examples: Installing and Using Decoupled Plugins

The decoupled architecture allows fine-grained control over plugin installation and usage. You can install individual plugins without dragging in dependencies, or force-load specific skills when needed.

Install the complete marketplace or selective components:

```bash

# Install all 9 plugins as a marketplace

claude plugin marketplace add phuryn/pm-skills

# Install only the execution toolkit—no other plugins are touched

claude plugin install pm-execution@pm-skills

```

Use commands that respect plugin boundaries, or explicitly bridge gaps:

```markdown

# Command from pm-product-discovery using only its own skills

/discover

# Explicitly load a skill from pm-execution without creating a dependency

/pm-execution:brainstorm-okrs

```

These examples demonstrate how the architecture supports both isolation and intentional interoperability.

## Summary

- **Self-contained manifests**: Each plugin maintains its own [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) in `pm-<domain>/.claude-plugin/`, while [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) only lists plugins without cross-references.
- **Zero cross-plugin commands**: [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md) and [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) strictly forbid commands from invoking other plugins' commands.
- **Explicit skill loading**: The `/plugin-name:skill-name` syntax allows intentional cross-plugin skill usage without static coupling.
- **Automated validation**: [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) rejects any pull request containing cross-plugin references.
- **Unified versioning**: All plugins share a single version to prevent runtime mismatches that could create hidden dependencies.

## Frequently Asked Questions

### Can commands in one plugin call commands from another?

No. The architecture explicitly prohibits commands from invoking commands defined in other plugins. According to [`CONTRIBUTING.md`](https://github.com/phuryn/pm-skills/blob/main/CONTRIBUTING.md), commands may only reference skills within the same plugin. This rule ensures that removing or updating one plugin cannot break the functionality of another, maintaining strict **cross-plugin decoupling** across the ecosystem.

### How does the marketplace prevent accidental coupling during development?

The repository includes a [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script that runs automated checks on every contribution. This validator inspects command-to-skill references and ensures they remain intra-plugin. Any cross-plugin reference triggers a validation error that blocks the merge, catching architectural violations before they reach the main branch.

### What happens if I need a skill from a different plugin?

You can explicitly force-load skills using the `/plugin-name:skill-name` syntax documented in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md). For example, typing `/pm-execution:brainstorm-okrs` loads the `brainstorm-okrs` skill from the execution plugin without creating a static dependency. This approach preserves decoupling while allowing runtime flexibility when multiple plugins are present.

### Are all plugins versioned independently?

No. All plugins in the `phuryn/pm-skills` marketplace share a single unified version number (such as `2.0.0`). When any plugin updates, the version in [`.claude-plugin/marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json) is bumped for all plugins simultaneously. This policy ensures compatibility across the ecosystem and prevents version mismatch issues that could otherwise introduce subtle runtime coupling.