SKILL.md File Structure: The Complete Specification for the pm-skills Repository

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.

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

# 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, 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, this appears as:

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

## 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 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, 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 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:

---
name: <slug>
description: "<short description>"
---

# <Skill Title>

## Purpose

<When and why to use this skill>

## Input Arguments

- `$ARG1`: <description>
- `$ARG2`: <description>

## Output

<Describe the expected sections / format>

## Instructions

### Step 1: <action>

...

### Step N: <action>

---   <!-- footer separator -->

## 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. This placement keeps discovery-related tags separate from execution instructions while remaining discoverable by catalog parsers.

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