Architectural Distinction Between pm-skills Skills and Commands Explained

In the pm-skills framework, skills are reusable, modular knowledge blocks that encode product-management frameworks, while commands are user-triggered workflows that orchestrate those skills into complete end-to-end processes.

The phuryn/pm-skills repository implements a strict two-layer architecture that cleanly separates domain knowledge from execution flow. This architectural distinction between pm-skills skills and commands enables the marketplace to grow organically, allowing contributors to add new capabilities without disrupting existing workflows.

What Are Skills in pm-skills?

Skills represent the foundational knowledge layer of the architecture. Each skill is a standalone module encoded as a Markdown file that describes a specific product-management framework, analysis technique, or guided workflow.

Skill Definition and Structure

Skills reside in organized directory structures following the pattern pm-*/skills/.../SKILL.md. According to the source code, these files contain the actual domain intelligence that powers the framework.

For example, the brainstorm-ideas-new skill is defined in pm-product-discovery/skills/brainstorm-ideas-new/SKILL.md:

# Brainstorm Ideas (New Products)

You are an expert product strategist.  
Generate 5 distinct ideas for a brand‑new SaaS product that solves a common pain point.

This skill encapsulates the specific knowledge required to generate new product ideas, independent of any specific workflow or execution context.

Auto-Loading and Explicit Invocation

Skills support two loading mechanisms. They are auto-loaded on demand when the model detects their domain knowledge is relevant to the conversation. Alternatively, users can force a skill to load explicitly using slash-prefixed syntax: /skill-name or /plugin-name:skill-name. For instance, typing /product-vision forces the product-vision skill to load immediately without wrapping it in a command workflow.

What Are Commands in pm-skills?

Commands represent the orchestration layer of the architecture. Unlike skills, commands do not contain domain knowledge themselves; instead, they define end-to-end workflows by chaining multiple skills together in sequence.

Command Definition and Execution

Commands are defined in Markdown files under pm-*/commands/...md and specify slash-command syntax that users invoke explicitly. When executed, a command triggers its constituent skills in order, passing the output of one skill as the input to the next.

The /discover command, defined in pm-product-discovery/commands/discover.md, demonstrates this chaining behavior:

# /discover

Chains four skills to run a full discovery cycle:

1. brainstorm-ideas-new
2. identify-assumptions-new
3. prioritize-assumptions
4. brainstorm-experiments-new

When a user runs /discover AI-powered meeting summarizer for remote teams, the command executes each skill sequentially, ultimately returning a complete discovery output that no single skill could produce independently.

Key Architectural Differences

The separation between these two layers creates distinct characteristics for each component:

• Skills are standalone and reusable. They encode single capabilities (like brainstorm-ideas-new or review-resume) that any command can invoke without modification.

• Commands are process-oriented and sequential. They exist to chain skills into multi-step workflows (like discovery, strategy, or execution cycles) and suggest the next logical command upon completion.

• Loading semantics differ fundamentally. Skills load automatically based on context or via /skill-name forcing, while commands require explicit invocation via /command-name syntax.

• Portability varies by layer. Skills are language-agnostic and work across Claude, Gemini, OpenCode, and other agents. Commands use Claude-specific slash syntax, meaning other agents must translate command files into their own workflow languages.

How Skills and Commands Interact

The interaction model follows a producer-consumer pattern where skills generate outputs that commands route between processing steps. When a command like /discover runs, it does not implement the brainstorming logic itself; instead, it invokes the brainstorm-ideas-new skill, captures its output, and feeds that into the identify-assumptions-new skill.

This architecture appears throughout the repository. For example, pm-toolkit/commands/review-resume.md creates a /review-resume command that simply forwards to the review-resume skill defined in pm-toolkit/skills/review-resume/SKILL.md. This demonstrates how even simple one-to-one mappings benefit from the separation, as the skill remains available for auto-loading while the command provides explicit workflow access.

File Structure and Organization

The repository enforces this architectural distinction through strict file organization:

Component	Path Pattern	Example
Skill	pm-*/skills/.../SKILL.md	pm-product-discovery/skills/brainstorm-ideas-new/SKILL.md
Command	pm-*/commands/...md	pm-product-discovery/commands/discover.md
Core Documentation	README.md	README.md (section "How It Works (Skills, Commands, Plugins)")

This directory structure ensures that skills remain decoupled from workflow logic, allowing the brainstorm-ideas-new skill to serve the /discover command while remaining available for direct invocation or inclusion in other custom commands.

Summary

• Skills are modular knowledge blocks stored in SKILL.md files that encode specific product-management frameworks and can be auto-loaded or forced via /skill-name.
• Commands are orchestration scripts stored in commands/*.md that chain skills into complete workflows using /command-name invocation.
• Architecture separates domain intelligence (skills) from process logic (commands), enabling reusable components across multiple workflows.
• Portability differs by layer: skills work across AI agents, while commands require translation for non-Claude environments.
• Extension is organic: new skills can be added without changing commands, and new commands can compose existing skills to address novel use cases.

Frequently Asked Questions

Can a skill exist without a command?

Yes. Skills are standalone entities that function independently. You can force-load any skill using its /skill-name syntax without invoking a command, which is useful when you need a specific framework (like /product-vision) without running a full multi-step workflow.

How does skill auto-loading work in pm-skills?

The model automatically detects when the conversation context requires specific domain knowledge and loads the relevant skill files from the pm-*/skills/ directories. This behavior is described in the README's "How It Works (Skills, Commands, Plugins)" section, allowing skills to inject their expertise into general conversations without explicit user invocation.

Are pm-skills commands portable across different AI agents?

No. Commands use Claude-specific slash-command syntax (/discover, /strategy) that other agents cannot execute directly. While agents like Gemini or OpenCode can read the command Markdown files to understand the workflow logic, they must translate these into their own native workflow languages. Skills, however, remain portable across all agents.

How do I create a custom command that uses existing skills?

Create a new Markdown file in the appropriate pm-*/commands/ directory. Define the command name with a leading slash in the header (e.g., # /my-custom-command), then list the skills you want to chain in execution order. The command will automatically pass outputs between skills, creating a seamless workflow without requiring you to implement any of the domain logic yourself.

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