What Does a Typical Command File Look Like in the pm-skills Repository?

A typical command file in the phuryn/pm-skills repository is a Markdown document with YAML front-matter containing required metadata (description and optional argument-hint), followed by structured documentation sections including Invocation and Workflow, strictly validated by validate_plugins.py.

Command files power the CLI interactions in the pm-skills toolkit, residing in the pm-toolkit/commands/ directory. These files follow a rigid Markdown convention enforced by the Commands validator in validate_plugins.py, ensuring every command definition maintains consistent metadata and user documentation standards across the repository.

The Three-Part Structure of a Command File

Each command file consists of three logical sections that the validator checks during the build process.

1. YAML Front-Matter Metadata

Every file must begin with YAML front-matter containing metadata fields that validate_plugins.py parses:

• description — Required. A concise, human-readable sentence explaining the command's purpose.
• argument-hint — Optional. A placeholder string showing expected command arguments (e.g., "<resume> + <job description>").

The validator rejects files with empty or missing description fields and warns when argument-hint is absent.

2. Human-Oriented Documentation

Following the front-matter, the Markdown body provides user-facing documentation structured as:

• Top-level heading — Matches the command name (format: # /command-name).

• Overview paragraph — Explains what the command accomplishes.

• Invocation block — Triple backticks containing exact CLI syntax examples.

• Workflow section — Step-by-step breakdown of how the command processes inputs and generates outputs.

3. Ancillary Notes

The final section contains best-practice recommendations, warnings about edge cases, or links to additional resources that help users maximize command effectiveness.

Validation Rules in validate_plugins.py

The validate_plugins.py script enforces command file integrity through automated checks that:

• Verify YAML front-matter presence and parse validity.
• Ensure the description field exists and contains non-empty content.
• Flag missing argument-hint entries as warnings.
• Parse Markdown content to validate cross-references to skills, ensuring referenced skills exist within the same plugin directory.

Complete Command File Example

The file pm-toolkit/commands/tailor-resume.md demonstrates the canonical structure:

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

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

### Step 1: Accept Both Documents

- The resume (text, PDF, or DOCX)  
- The target job description (text, URL, or file)

### Step 2: Analyze the Job Description

- Extract required qualifications, preferred skills, responsibilities, etc.

### Step 3: Tailor the Resume

- **Keyword alignment** – map JD keywords to resume content  
- **Bullet point rewriting** – use the XYZ+S formula  
- **Section reordering**, **summary/objective** rewrite, and **skills** alignment

### Step 4: Generate Tailored Resume + Analysis

Resume Tailoring: [Job Title] at [Company]

Alignment Score: [X/10]

Keyword Gap Analysis

JD Keyword	In Resume?	Recommendation
...

## Notes

- Never fabricate experience—reframe truthfully.  
- Match the JD's language exactly where possible.  
- Emphasize scale for senior roles, hands-on execution for IC roles.

Reference Command Files in the Repository

The phuryn/pm-skills repository maintains several exemplar files that demonstrate this structure:

• pm-toolkit/commands/tailor-resume.md — Complete example with front-matter and workflow documentation.
• pm-toolkit/commands/review-resume.md — Reinforces the same structural patterns for resume review functionality.
• pm-toolkit/commands/proofread.md — Demonstrates optional argument-hint usage patterns.

Summary

• Command files are Markdown documents with strict YAML front-matter requirements enforced by the Commands validator in validate_plugins.py.
• Required metadata includes a non-empty description field, while argument-hint is optional but triggers a warning when missing.
• Documentation structure mandates a top-level command heading, Invocation block with CLI syntax, and detailed Workflow steps.
• Cross-reference validation ensures that any skills mentioned in the documentation exist within the same plugin directory.

Frequently Asked Questions

What file extension do command files use?

Command files use the .md extension to indicate Markdown format. The validate_plugins.py validator specifically processes these files to extract YAML front-matter and validate Markdown structure against repository standards.

Is the argument-hint field required in command files?

No, argument-hint is optional. According to the validation logic in validate_plugins.py, missing argument-hint fields generate a warning rather than a failure, while the description field is strictly required and must contain non-empty content.

How does the validator check command file correctness?

The validate_plugins.py script parses each command file's YAML front-matter to verify required fields, validates that the Markdown body contains properly formatted documentation, and performs cross-reference checks to ensure any referenced skills exist within the same plugin directory.

Where are command files stored in the repository?

Command files are located in the pm-toolkit/commands/ directory. Each file corresponds to a specific CLI command (such as tailor-resume.md, review-resume.md, or proofread.md) and follows the standardized three-part structure enforced by the repository's validation tooling.

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