# PM Skills Command Markdown File Structure: The Complete Schema > Explore the five-part schema of PM Skills command markdown files. Understand YAML front-matter, H1 headers, invocation examples, workflow steps, and optional notes for effective PM skill management. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-06-21 --- **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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md), the front-matter appears as: ```markdown --- description: Tailor a PM resume to a specific job description — keyword alignment, experience reframing, and strategic optimization argument-hint: " + " --- ``` The `argument-hint` value typically uses angle brackets to denote placeholders, such as `" + "` or `""`, 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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md): ```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 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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md) delegates bullet-point rewriting to the `review-resume` skill: ```markdown ## 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`](https://github.com/phuryn/pm-skills/blob/main/pm-marketing-growth/commands/north-star.md), the workflow invokes the `north-star-metric` skill, while [`pm-market-research/commands/research-users.md`](https://github.com/phuryn/pm-skills/blob/main/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 ****?"` to suggest follow-up commands or skills. From [`pm-toolkit/commands/tailor-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md): ```markdown ## 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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/tailor-resume.md)** – Demonstrates multi-input handling (resume + job description) and skill delegation to [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) 2. **[`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md)** – Shows scoring rubrics and structured output formats within workflow steps 3. **[`pm-marketing-growth/commands/north-star.md`](https://github.com/phuryn/pm-skills/blob/main/pm-marketing-growth/commands/north-star.md)** – Illustrates single-input commands that invoke metric-definition skills 4. **[`pm-market-research/commands/research-users.md`](https://github.com/phuryn/pm-skills/blob/main/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., `" + "`) 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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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.