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

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

The repository ships with a 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, 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 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:

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

# 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 in pm-<domain>/.claude-plugin/, while .claude-plugin/marketplace.json only lists plugins without cross-references.
• Zero cross-plugin commands: CONTRIBUTING.md and 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 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, 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 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. 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 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.

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