# SKILL.md File Structure: The Complete Specification for the pm-skills Repository > Understand the SKILL.md file structure for the phuryn/pm-skills repository. Learn about mandatory YAML front-matter and standardized sections that define product management skills. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-07-02 --- **A SKILL.md file is a markdown document with mandatory YAML front-matter followed by standardized sections including title, purpose, input requirements, and step-by-step instructions that define reusable product management capabilities in the phuryn/pm-skills repository.** The `phuryn/pm-skills` repository organizes product management expertise into modular, machine-readable skills. Every skill relies on a consistent **SKILL.md file structure** that ensures discoverability by the toolkit, enables auto-completion in the CLI, and drives LLM workflows through predictable, well-documented interfaces. ## Core Components of a SKILL.md File Every SKILL.md file follows a specific sequence of sections that balance metadata richness with execution clarity. ### YAML Front-Matter The file must begin with exactly three lines of YAML metadata surrounded by triple dashes. This section defines the `name` (URL-friendly slug) and `description` (short tagline) used by the skill catalog. ```markdown --- name: review-resume description: "Comprehensive PM resume review and feedback generation" --- ``` ### Title Header Immediately following the front-matter, a single H1 heading provides the human-readable skill name. This typically matches the `name` field but in Title Case. ```markdown # Resume Review for Product Managers ``` ### Purpose or Overview A concise section—labeled **Purpose**, **Overview**, or **When to Use**—explains when and why to invoke the skill. This helps users quickly determine if the capability matches their current need. 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 states: "Create a comprehensive go-to-market strategy for a product launch." ### Metadata (Optional) Advanced skills may include a structured **Metadata** section listing custom tags, triggers, or categorization data. This enables advanced searching and filtering across the repository. ### Input Requirements A mandatory section defining the arguments required for execution, typically prefixed with `$`. In [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), this appears as: ```markdown ## Input Arguments - `$RESUME`: The resume text to review - `$JOB_DESCRIPTION`: Optional target role description ``` ### Instructions The executable logic of the skill, often presented as numbered steps or logical phases. This section drives the LLM to follow a predictable flow. From [`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): ```markdown ## How It Works ### Step 1: Gather Research Data ... ### Step 4: Define Success Metrics ... ``` ### Output Specification A clear definition of the expected response structure, often labeled **Output**, **Response Structure**, or **Output Format**. This makes results machine-parseable and easier to validate. ### Footer Separator and Further Reading A line containing three dashes (`---`) visually separates the core skill from auxiliary material. Optional **Tips** or **Further Reading** sections may follow, providing best-practice guidance without cluttering the execution path. ## Real-World Examples from the Repository ### Resume Review Skill The file [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) demonstrates a complete implementation with metadata, purpose, input arguments, response structure, and best-practice guidance. ### Value Proposition Skill Located at [`pm-product-strategy/skills/value-proposition/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/value-proposition/SKILL.md), this example showcases the optional **Metadata** section with custom triggers and a detailed **Value Proposition Template** subsection defining a 6-part JTBD structure. ### GTM Strategy Skill The file [`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) illustrates a phased **How It Works** flow with explicit **Input Format** and **Output** definitions, including timeline and budget parameters. ## Minimal Skeleton Template All skills in the repository extend from this foundational structure: ```markdown --- name: description: "" --- # ## Purpose ## Input Arguments - `$ARG1`: - `$ARG2`: ## Output ## Instructions ### Step 1: ... ### Step N: --- ## Further Reading - [Link to related docs](...) ``` ## Summary - **SKILL.md files** serve as canonical definitions of capabilities within the `phuryn/pm-skills` repository. - **YAML front-matter** must appear in the first three lines, containing `name` and `description` fields. - **Input arguments** use the `$VARIABLE` convention to guarantee the model receives necessary context. - **Step-by-step instructions** provide the execution logic, while **output specifications** define response formatting. - **Footer separators** (`---`) distinguish core functionality from optional tips and further reading. ## Frequently Asked Questions ### What is the required YAML front-matter format for a SKILL.md file? The front-matter must occupy the first three lines of the file, enclosed in triple dashes, and contain exactly two fields: `name` (the URL-friendly slug) and `description` (a concise tagline). This strict format enables the toolkit to parse skill metadata without processing the entire document. ### How do I define input arguments in a SKILL.md file? Input arguments are declared in a dedicated section—typically titled **Input Arguments**, **Input Requirements**, or **Input Format**—using a bulleted list where each item starts with a dollar sign (e.g., `$RESUME: The text to analyze`). This convention signals to the execution engine which variables must be supplied before invoking the skill. ### Are all sections in a SKILL.md file mandatory? No, while the YAML front-matter, title header, purpose, input requirements, and instructions are essential for execution, sections like **Metadata**, **Tips**, and **Further Reading** are optional. The footer separator (`---`) is recommended whenever including optional trailing sections to maintain visual clarity. ### Where should custom metadata be placed in a SKILL.md file? Optional metadata should appear immediately after the title header in a dedicated `## Metadata` section, following the pattern seen 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). This placement keeps discovery-related tags separate from execution instructions while remaining discoverable by catalog parsers.