How Commands Are Structured in the phuryn/pm-skills Repository

Commands in the phuryn/pm-skills repository are declarative Markdown files with YAML frontmatter that reside in each plugin's commands/ directory, defining slash-command workflows that orchestrate underlying skills through a self-describing schema.

The phuryn/pm-skills repository implements a declarative architecture where commands are pure data files rather than executable code. Each command is a standalone Markdown document that serves as a contract between the user and Claude's execution engine, enabling product managers to invoke complex workflows through simple slash-commands like /review-resume or /discover.

Core Command File Components

YAML Frontmatter Metadata

Every command file begins with YAML frontmatter containing metadata fields. The description field provides a human-readable explanation of the command's purpose, while the optional argument-hint field specifies the expected input format using angle brackets (e.g., "<resume as text or file>"). This metadata allows the assistant to surface command descriptions and validate user inputs before execution.

Command Title and Invocation Syntax

The title line follows the format # /command-name -- Human Readable Description. This line defines the literal string users type to trigger the command. Immediately following, an invocation block contains fenced code demonstrating the exact syntax, including placeholders for arguments.

Workflow Sections

Structured workflow steps guide the assistant through processing inputs, calling associated skills, and formatting outputs. These appear as ### Step 1, ### Step 2, etc., providing explicit instructions for the AI execution engine.

Output Templates

Commands include Markdown skeletons that define how results are presented to users. These templates often contain scorecard tables, structured sections for feedback, and placeholders for dynamic content that the assistant fills during execution.

Repository Organization and File Paths

Commands are organized hierarchically by plugin. Each top-level plugin directory contains a commands/ subdirectory containing all relevant .md files.

The repository follows this structure:

pm-toolkit/
├── commands/
│   ├── review-resume.md
│   ├── tailor-resume.md
│   └── draft-nda.md
pm-product-discovery/
├── commands/
│   ├── discover.md
│   └── brainstorm.md
pm-go-to-market/
├── commands/
│   └── plan-launch.md

Key command files in the repository include:

• pm-toolkit/commands/review-resume.md – Defines the resume review workflow
• pm-product-discovery/commands/discover.md – Implements the full product discovery cycle
• pm-go-to-market/commands/plan-launch.md – Orchestrates go-to-market strategy creation

Commands vs Skills Architecture

Commands serve as thin wrappers that orchestrate skills, which contain the actual domain logic. While commands reside in commands/ directories and define user-facing interfaces, skills are stored in parallel skills/ directories and contain reusable functions and knowledge bases.

For example, the /review-resume command defined in pm-toolkit/commands/review-resume.md triggers the review-resume skill implemented in pm-toolkit/skills/review-resume/SKILL.md. This separation allows the same skill to be reused across multiple commands while maintaining clean separation between interface and logic.

Command Execution Flow

When a user types a slash-command, Claude executes the following sequence:

1. Parses the command name from the user input (e.g., /review-resume)
2. Locates the corresponding Markdown file in the appropriate plugin's commands/ directory
3. Reads the YAML frontmatter to surface the description and expected arguments
4. Executes the workflow steps, internally invoking the matching skill(s)
5. Renders the output template back to the user with populated results

According to the repository's README.md, commands are designed to flow into each other, matching the PM workflow lifecycle.

Practical Command Examples

Review Resume Command

Located at pm-toolkit/commands/review-resume.md:

---
description: Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback
argument-hint: "<resume as text or file>"
---

# /review-resume -- PM Resume Review

## Invocation

/review-resume [paste resume text] /review-resume [upload resume PDF or DOCX]

## Workflow

### Step 1: Accept the Resume

Prompt the user to share their resume text or file...

### Step 2: Evaluate Against 10 Best Practices

Check for structure, metrics, keywords, and formatting...

Product Discovery Command

Located at pm-product-discovery/commands/discover.md:

---
description: Full discovery cycle – ideation → assumption mapping → prioritization → experiment design
argument-hint: "<product idea>"
---

# /discover -- Product Discovery

## Invocation

/discover

## Workflow

### Step 1: Brainstorm ideas

Generate potential solutions and features...

### Step 2: Identify assumptions

Map critical assumptions requiring validation...

Go-to-Market Planning Command

Located at pm-go-to-market/commands/plan-launch.md:

---
description: Full GTM strategy from beachhead to launch plan
argument-hint: "<product or launch brief>"
---

# /plan-launch -- GTM Launch Planning

## Invocation

/plan-launch

## Workflow

### Step 1: Identify beachhead segment

Define the initial target market segment...

### Step 2: Craft GTM messaging

Develop positioning and messaging frameworks...

Summary

• Commands are Markdown files with YAML frontmatter stored in plugin-specific commands/ directories
• Each file defines a slash-command workflow that orchestrates one or more underlying skills
• The structure includes metadata headers, invocation syntax, numbered workflow steps, and output templates
• Commands are pure data declarations; execution logic resides in Claude's engine, making the system entirely declarative
• Adding new commands requires only creating a new .md file in the appropriate commands/ folder without code changes

Frequently Asked Questions

What file format do commands use in the phuryn/pm-skills repository?

Commands are written as Markdown files (.md) with YAML frontmatter at the top. This format allows the system to parse machine-readable metadata while maintaining human-readable documentation and workflow instructions that both users and the AI assistant can understand.

How do commands differ from skills in the repository structure?

Commands reside in commands/ folders and define user-facing slash-command interfaces, invocation patterns, and workflow steps. Skills reside in skills/ folders and contain the underlying domain logic, reusable functions, and knowledge bases. A command acts as an orchestration layer that invokes one or more skills to complete a task.

Where should new commands be added when extending the repository?

New commands should be placed in the commands/ subdirectory of the relevant plugin folder (e.g., pm-toolkit/commands/ or pm-product-discovery/commands/). The file should follow the naming convention command-name.md and include the standard YAML frontmatter with description and argument-hint fields.

What is the purpose of the argument-hint field in command frontmatter?

The argument-hint field provides guidance about the expected input format (e.g., "<resume as text or file>" or "<product idea>"). This appears in UI tooltips and helps Claude understand what parameters to request from the user when invoking the command, ensuring the assistant captures the correct context before executing the workflow.

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