SKILL.md File Format and Structure: A Complete Guide for the pm-skills Repository

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.

---
name: review-resume
description: "Comprehensive PM resume review and feedback"
---

As seen in 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.

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

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

---

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

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

---

## Further Reading

- [Link to related docs](...)

Real-World Examples from the Repository

Review Resume Skill

Located at 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 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, 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 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-name>/SKILL.md, pm-product-strategy/skills/<skill-name>/SKILL.md, or pm-go-to-market/skills/<skill-name>/SKILL.md. This path structure enables the toolkit to categorize and index skills automatically.

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