# SKILL.md File Structure and Format in the pm-skills Repository > Understand the SKILL.md file structure and format within the phuryn pm-skills repository. Learn how its three-part layout enables easy skill discovery and parsing. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-06-09 --- **[`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files in the `phuryn/pm-skills` repository follow a strict three-part layout—YAML front matter, a human-readable markdown header, and a structured body—to make skills easy to discover, parse, and execute.** The `phuryn/pm-skills` repository organizes product-management knowledge as discrete, reusable skills. Understanding the **SKILL.md structure and format** is essential for contributors adding new capabilities and for developers building tooling that consumes these files. Every skill file follows the same canonical pattern, enabling automated parsing by utilities such as the pm-toolkit CLI. ## The Three Core Sections of a SKILL.md File Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) is divided into three sequential parts. | Section | Purpose | Typical Content | |---|---|---| | **YAML Front Matter** | Provides machine-readable metadata for indexing and lookup. | `name`, `description`, and optional keys inside `---` delimiters. | | **Human-Readable Header** | Offers a clear title and optional introduction. | A level-1 markdown heading (`# …`) plus a short descriptive paragraph. | | **Structured Body** | Details instructions, arguments, workflow, and examples. | Sub-headings (`##`, `###`), lists, code fences, tables, and external links. | This predictable layout means the toolkit can traverse the folder hierarchy, extract metadata, and render instructions without bespoke logic for individual skills. ## YAML Front Matter: Required Metadata The file must open with a YAML block wrapped in triple dashes. ```markdown --- name: description: "" --- ``` The `name` field serves as the canonical identifier. For example, `review-resume` or `value-proposition`. The `description` string appears in skill pickers and search results. Because this block is required for every skill, the parser can rely on its presence to index the repository. ## Human-Readable Header Immediately after the front matter, the file provides a top-level markdown heading that mirrors the skill’s purpose. ```markdown # Resume Review for Product Managers ``` This heading improves readability for humans browsing the repository and gives the rendered skill a clear title in any UI. ## Structured Body: Instructions, Arguments, and Templates The remainder of the file uses standard markdown sub-headings to organize content into logical blocks. ### Instructions and Persona The **Instructions** section sets the LLM context or persona. For example, "You are an expert resume reviewer…" establishes the role the model should adopt before executing the skill. ### Input Arguments Skills declare reusable variables so callers can pass context at runtime. ```markdown ## Input Arguments - `$RESUME`: The resume text or content to review - `$JOB_POSTING`: (Optional) The job posting or target role description ``` Variables such as `$PRODUCT_NAME` or `$PRODUCT_URL` make a single skill adaptable across different products or scenarios. ### Process and Steps The workflow is broken into discrete chunks under headings such as `## Process / Steps` or `### Step 1: …`. Each step is a logical unit that can be documented independently, which helps both the LLM and human readers follow the sequence. ### Template and Example Blocks Concrete output formats are wrapped in fenced code blocks so the model can copy the structure verbatim. These blocks often appear under a `## Template / Example` heading. ### Metadata Sub-Section and Triggers Some skills repeat the front-matter values in a `## Metadata` section and add **Triggers**—keywords that help surface the skill via keyword matching beyond the canonical name. ### Further Reading An optional list of external links, tutorials, or legal notes can close the body. ## Real-World SKILL.md Examples in pm-skills Three representative files demonstrate how the format adapts to different domains. ### review-resume Skill In [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), the skill opens with: ```markdown --- name: review-resume description: "Comprehensive PM resume review and tailoring against 10 best practices..." --- # Resume Review for Product Managers ``` It then defines input arguments `$RESUME` and `$JOB_POSTING`, followed by a detailed checklist under `## 10 Best Practices for PM Resumes` with sub-sections such as `### Best Practice 1: Professional Summary`. ### value-proposition Skill The file [`pm-product-strategy/skills/value-proposition/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/value-proposition/SKILL.md) shows a template-driven approach. ```markdown --- name: value-proposition description: "Design a detailed value proposition using a 6‑part JTBD template..." --- # Value Proposition ## Metadata - **Name**: value-proposition - **Description**: Generate a detailed value proposition using a 6‑part template… ``` Its body includes a `## Value Proposition Template` with a numbered `### 6‑Part Structure` covering **Who**, **Why (Problem)**, and **What Before**. ### privacy-policy Skill Located at [`pm-toolkit/skills/privacy-policy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/privacy-policy/SKILL.md), this legal-oriented skill uses: ```markdown --- name: privacy-policy description: "Draft a detailed privacy policy covering data types, jurisdiction, GDPR..." --- # Privacy Policy Generator ``` It declares arguments such as `$PRODUCT_NAME` and `$PRODUCT_URL`, then provides a `## Privacy Policy Template Structure` with marked sections like `### Preamble` and `### 1. Information We Collect`. ## Summary - **[`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files follow a rigid three-part sequence**: YAML front matter, a level-1 heading, and a structured markdown body. - **Front matter is mandatory** and must include `name` and `description` inside `---` delimiters. - **Input arguments use `$VARIABLE` syntax** to keep skills reusable across contexts. - **Real files** such as [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), [`pm-product-strategy/skills/value-proposition/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/value-proposition/SKILL.md), and [`pm-toolkit/skills/privacy-policy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/privacy-policy/SKILL.md) demonstrate the format across resume review, strategy, and legal domains. - **Consistent structure enables automation**; the pm-toolkit CLI can parse, index, and execute skills without custom per-file logic. ## Frequently Asked Questions ### What are the required parts of a SKILL.md file? Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) must contain YAML front matter with `name` and `description` fields, followed by a level-1 markdown heading and a structured body. While sections such as `## Metadata`, `## Instructions`, and `## Input Arguments` are strongly recommended, the parser primarily enforces the presence of the front matter block and the top-level heading. ### How do input arguments work in SKILL.md files? Input arguments are declared as bullet list items prefixed with a dollar sign, such as `$RESUME` or `$PRODUCT_NAME`. Callers pass values for these variables at runtime, which allows a single skill file to handle many different contexts without modification. ### Where are SKILL.md files located in the pm-skills repository? They reside under domain-specific folders inside the repository, such as `pm-toolkit/skills//SKILL.md` and `pm-product-strategy/skills//SKILL.md`. The root [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) provides an overview of this hierarchy and points consumers to the correct directories. ### Can a SKILL.md include external links and legal disclaimers? Yes. The format explicitly supports optional `## Further Reading` sections and external markdown links. Legal skills such as [`pm-toolkit/skills/privacy-policy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/privacy-policy/SKILL.md) routinely include disclaimer notes and links to regulatory resources alongside the standard template structure.