# SKILL.md File Format and Structure: A Complete Guide for the pm-skills Repository > Learn the SKILL.md file format and structure for the pm-skills repository Understand required YAML front-matter markdown headings sections input output and instructions for seamless integration - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-07-01 --- **A SKILL.md file requires YAML front-matter with `name` and `description` fields, followed by a markdown title, purpose section, input requirements prefixed with `$`, output specification, and step-by-step instructions, all separated by standard markdown headings.** The `phuryn/pm-skills` repository organizes product management expertise into modular, reusable skills. Each skill is defined in a **SKILL.md file** that serves as the canonical blueprint for LLM interactions. Understanding the precise SKILL.md format ensures your contributions are discoverable by the CLI toolkit and produce consistent, predictable outputs. ## Required Sections in a SKILL.md File Every SKILL.md file in the repository follows a strict structure to ensure compatibility with the skill catalog and CLI auto-completion. ### YAML Front-Matter The file must begin with YAML front-matter containing exactly two fields: `name` (a URL-friendly slug) and `description` (a concise tagline). This metadata must occupy the first three lines of the file, enclosed by triple dashes. ```markdown --- name: review-resume description: "Comprehensive PM resume review and feedback" --- ``` As seen in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), this front-matter enables the toolkit to index and display skills in auto-completion menus. ### Title Header Immediately following the front-matter, include a single level-one heading that provides a human-readable name for the skill. This typically matches the `name` field converted to Title Case. ```markdown # Resume Review for Product Managers ``` This heading appears when users browse the repository on GitHub or open the file in an editor. ### Purpose or Overview Include a brief section—labeled **Purpose**, **Overview**, or **When to Use**—that explains the specific scenario for invoking this skill. This helps users quickly determine if the skill matches their needs. In [`pm-go-to-market/skills/gtm-strategy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-go-to-market/skills/gtm-strategy/SKILL.md), this section appears as `## Overview` and describes when to create a comprehensive go-to-market strategy. ### Input Requirements Explicitly define all arguments that must be supplied to the skill, typically under a heading like **Input Arguments**, **Input Requirements**, or **Input Format**. Each parameter should be prefixed with a dollar sign (`$`) to denote variable substitution. ```markdown ## Input Arguments - `$RESUME`: The full text of the resume to review - `$JOB_DESCRIPTION`: The target role description (optional) ``` The `review-resume` skill uses this format to guarantee the model receives all necessary context before processing. ### Output Specification Describe the expected structure of the LLM response under **Output**, **Response Structure**, or **Output Format**. This section defines sections, bullet lists, tables, or other formatting that makes results machine-parseable and consistent. The `review-resume` skill defines this under `## Response Structure`, specifying exactly how feedback should be organized. ### Instructions or How It Works Provide step-by-step guidance that drives the LLM through a predictable workflow. Use numbered steps (`### Step 1: ...`) or logical phases (Research, Channel Definition, Messaging) to structure complex skills. In [`pm-go-to-market/skills/gtm-strategy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-go-to-market/skills/gtm-strategy/SKILL.md), this appears as `## How It Works` with explicit steps like `### Step 1: Gather Research Data` and `### Step 4: Define Success Metrics`. ### Footer Separator Terminate the core skill definition with a horizontal rule (`---`) before any auxiliary sections. This visual separator distinguishes mandatory content from optional reference material. ```markdown --- ## Further Reading ``` ## Optional Sections for Enhanced Skills While the core structure is mandatory, these sections add discoverability and usability. ### Metadata Some skills include a `## Metadata` section listing structured tags, triggers, or aliases. The `value-proposition` skill in [`pm-product-strategy/skills/value-proposition/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/value-proposition/SKILL.md) uses this to define search triggers like "value prop" and "JTBD value". ### Tips and Best Practices Include a `## Tips` section for guidance that improves output quality without cluttering the core workflow. This might contain framing advice, common pitfalls, or iteration suggestions. ### Further Reading After the footer separator, link to related documentation, external resources, or complementary skills using standard markdown links. ## Complete SKILL.md Template Here is the minimal skeleton that all skills must follow: ```markdown --- name: description: "" --- # ## Purpose ## Input Arguments - `$ARG1`: - `$ARG2`: ## Output ## Instructions ### Step 1: ... ### Step N: --- ## Further Reading - [Link to related docs](...) ``` ## Real-World Examples from the Repository ### Review Resume Skill Located at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), this file demonstrates the complete structure: YAML front-matter with name and description, a clear title, overview section, detailed input arguments with `$RESUME`, explicit response structure requirements, and a tips section. ### Value Proposition Skill The [`pm-product-strategy/skills/value-proposition/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/value-proposition/SKILL.md) file illustrates optional metadata usage. It includes a `## Metadata` section with triggers and aliases, plus a detailed `## Value Proposition Template` subsection defining the 6-part JTBD structure. ### GTM Strategy Skill Found in [`pm-go-to-market/skills/gtm-strategy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-go-to-market/skills/gtm-strategy/SKILL.md), this example shows a phase-based instruction flow. Instead of simple numbered steps, it uses `## How It Works` with substeps for research, channel definition, messaging, and metrics, alongside clear input format specifications. ## Summary - **SKILL.md files** serve as canonical skill definitions in the `phuryn/pm-skills` repository - **YAML front-matter** with `name` and `description` fields must occupy the first three lines - **Input variables** use the `$PREFIX` convention to indicate required arguments - **Step-by-step instructions** drive consistent LLM behavior through numbered phases or logical sections - **Footer separator** (`---`) distinguishes core content from optional further reading - Canonical examples exist in `review-resume`, `value-proposition`, and `gtm-strategy` skill files ## Frequently Asked Questions ### What is the minimum required content for a SKILL.md file? Every SKILL.md must include YAML front-matter with `name` and `description`, a title header (`# `), a purpose section, input requirements using `$` prefixed variables, output specifications, and step-by-step instructions. The file located at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) provides a complete reference implementation. ### How do I define input variables in a SKILL.md file? Define input variables in an **Input Arguments** or **Input Requirements** section using the dollar-sign prefix convention (e.g., `$RESUME`, `$ARGUMENTS`). Each variable should include a clear description of the expected data type and content, as demonstrated in the `review-resume` and `gtm-strategy` skills. ### Can I add custom sections to a SKILL.md file? Yes, you can add optional sections such as `## Metadata` for search triggers, `## Tips` for best practices, or domain-specific templates. However, these must appear after the footer separator (`---`) or clearly labeled as optional to maintain compatibility with the skill discovery system. ### Where should I place the SKILL.md file in the repository? Place each SKILL.md file inside its own skill directory under the appropriate domain folder, such as `pm-toolkit/skills//SKILL.md`, `pm-product-strategy/skills//SKILL.md`, or `pm-go-to-market/skills//SKILL.md`. This path structure enables the toolkit to categorize and index skills automatically.