PM Skills Command Markdown File Structure: The Complete Schema

Command markdown files in the PM Skills Marketplace follow a standardized five-part schema comprising YAML front-matter with description and argument-hint fields, a slash-prefixed H1 command header, fenced invocation examples, numbered workflow steps that delegate to reusable skill files, and an optional Notes section with best-practice guidance.

The phuryn/pm-skills repository organizes product management automation through a strict command markdown file structure that enables both machine parsing and human readability. Each command file acts as an executable specification, defining inputs, execution logic, and output formats through a consistent schema recognized across the toolkit.

YAML Front-Matter Schema

Every command file begins with YAML front-matter containing two required fields that enable discovery and argument parsing:

• description – A concise, one-sentence summary of the command’s purpose
• argument-hint – A placeholder string indicating the expected input format

In pm-toolkit/commands/tailor-resume.md, the front-matter appears as:

---
description: Tailor a PM resume to a specific job description — keyword alignment, experience reframing, and strategic optimization
argument-hint: "<resume> + <job description>"
---

The argument-hint value typically uses angle brackets to denote placeholders, such as "<resume> + <job description>" or "<upload file>", signaling to the execution environment what inputs to expect.

Command Header and Invocation Pattern

Following the front-matter, the file uses an ATX-style H1 heading prefixed with a slash (/) to declare the command name and human-readable title. A brief prose paragraph explains the command’s purpose.

The Invocation section provides fenced code blocks containing one-line usage examples. These demonstrate valid syntax for the command parser, including variations for text input versus file uploads.

From pm-toolkit/commands/tailor-resume.md:

# /tailor-resume -- Resume-to-JD Optimization

Take your resume and a target job description, then strategically align your experience to maximize interview chances. Keyword optimization, bullet point rewriting, and gap analysis.

## Invocation

/tailor-resume [upload resume] Here’s the JD: [paste job description] /tailor-resume [upload both resume and JD as files]

Workflow Section and Skill Integration

The Workflow section contains numbered steps under H3 headings that describe the command’s execution logic. Each step details a discrete operation, such as accepting inputs, analyzing documents, or generating outputs.

Crucially, workflow steps reference reusable skill files stored in parallel skills/ directories. For example, pm-toolkit/commands/tailor-resume.md delegates bullet-point rewriting to the review-resume skill:

## Workflow

### Step 1: Accept Both Documents

Need two inputs: the resume (text, PDF, or DOCX) and the target job description (text, URL, or file).

### Step 2: Analyze the Job Description

Extract required qualifications, preferred qualifications, key responsibilities, etc.

### Step 3: Tailor the Resume

Apply the **review-resume** skill → keyword alignment, bullet-point rewriting, section reordering, etc.

### Step 4: Generate Tailored Resume + Analysis

Resume Tailoring: …

Alignment Score: …

Keyword Gap Analysis …

This delegation pattern appears consistently across the repository. In pm-marketing-growth/commands/north-star.md, the workflow invokes the north-star-metric skill, while pm-market-research/commands/research-users.md branches into multiple skill calls depending on input parameters.

Optional Notes and Best Practices

The final section contains bullet-pointed guidance, edge-case handling, and “next-step” prompts. These follow the pattern "Want me to **<next-action>**?" to suggest follow-up commands or skills.

From pm-toolkit/commands/tailor-resume.md:

## Notes

- Never fabricate experience — reframe truthfully.
- Match the JD’s language exactly where possible.
- "Want me to **analyze the gap** between your profile and this role?" – links to another command.

Real-World Implementation Examples

The repository implements this schema across multiple functional domains:

1. pm-toolkit/commands/tailor-resume.md – Demonstrates multi-input handling (resume + job description) and skill delegation to pm-toolkit/skills/review-resume/SKILL.md
2. pm-toolkit/commands/review-resume.md – Shows scoring rubrics and structured output formats within workflow steps
3. pm-marketing-growth/commands/north-star.md – Illustrates single-input commands that invoke metric-definition skills
4. pm-market-research/commands/research-users.md – Exhibits branching workflows that conditionally call different research skills based on input type

All files maintain identical structural alignment, allowing the PM Skills Marketplace to parse metadata automatically while presenting consistent documentation to users.

Summary

• YAML front-matter with description and argument-hint fields enables machine discovery and user guidance

• Slash-prefixed H1 headers (# /command-name) define the command identifier and human-readable title

• Invocation blocks provide fenced code examples showing valid input syntax

• Numbered workflow steps describe execution logic and delegate to reusable skills via references like skill-name

• Optional Notes sections contain best-practice bullet points and next-step prompts following the "Want me to..." pattern

Frequently Asked Questions

What are the required YAML front-matter fields in a PM Skills command file?

Every command markdown file must include description and argument-hint keys in its YAML front-matter. The description provides a one-sentence summary of the command’s purpose, while argument-hint uses placeholder syntax (e.g., "<resume> + <job description>") to indicate expected inputs to the execution environment.

How do command files invoke reusable skills in the PM Skills Marketplace?

Commands reference skills within numbered workflow steps by bolding the skill name, such as review-resume or north-star-metric. These references correspond to markdown files stored in skills/ subdirectories (e.g., pm-toolkit/skills/review-resume/SKILL.md), allowing the toolkit to inject reusable logic while maintaining separation between command orchestration and skill implementation.

Can PM Skills commands accept multiple input formats?

Yes. As implemented in pm-toolkit/commands/tailor-resume.md, commands accept varied input types including raw text, URLs, PDFs, and DOCX files. The invocation block typically shows multiple syntax variations, such as /command [upload file] versus /command [paste text], with workflow steps handling format normalization in Step 1.

What distinguishes a command from a skill in the PM Skills file structure?

Commands are user-facing entry points stored in commands/ directories that define complete workflows, YAML metadata, and invocation patterns. Skills are reusable logic modules stored in skills/ directories that commands delegate to during execution. While commands contain front-matter and invocation blocks, skills focus purely on implementation logic without the command-line interface scaffolding.

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