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

> Explore typical command files in the phuryn/pm-skills repository. Learn about their Markdown structure, YAML front-matter metadata, and validation with validate_plugins.py.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md) demonstrates the canonical structure:

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

```

```markdown

# /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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md) — Complete example with front-matter and workflow documentation.
- [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) — Reinforces the same structural patterns for resume review functionality.
- [`pm-toolkit/commands/proofread.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/tailor-resume.md), [`review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/review-resume.md), or [`proofread.md`](https://github.com/phuryn/pm-skills/blob/main/proofread.md)) and follows the standardized three-part structure enforced by the repository's validation tooling.