SKILL.md File Structure and Format in the pm-skills Repository

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 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.

---
name: <skill-identifier>
description: "<short description used for search and preview>"
---

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.

# 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.

## 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, the skill opens with:

---
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 shows a template-driven approach.

---
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, this legal-oriented skill uses:

---
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 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, pm-product-strategy/skills/value-proposition/SKILL.md, and 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 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-name>/SKILL.md and pm-product-strategy/skills/<skill-name>/SKILL.md. The root 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 routinely include disclaimer notes and links to regulatory resources alongside the standard template structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}