Skill File Schema in PM Skills: Complete Markdown Specification Guide

The PM Skills repository defines a lightweight, self-describing Markdown schema with YAML front-matter and standardized sections that enables AI agents to parse, register, and execute skills deterministically.

The phuryn/pm-skills project organizes product management capabilities as discrete, self-contained skill files. Each skill follows a consistent Markdown-based schema that balances human readability with machine parseability, allowing the plugin loader to automatically register capabilities without requiring code changes.

Skill File Location and Conventions

All skill files reside within plugin-specific skills/ directories following the path pattern plugin-name/skills/skill-name/SKILL.md. For example, the resume review capability lives at pm-toolkit/skills/review-resume/SKILL.md according to the repository source code.

Core Schema Components

The skill file schema consists of seven distinct elements that appear in consistent order throughout every SKILL.md file.

YAML Front-Matter

Every skill file opens with YAML front-matter specifying the skill's unique identifier and description. The name field provides the machine-readable identifier, while description offers human-readable context for the plugin loader. This metadata occupies lines 1-4 of the file.

Example from pm-toolkit/skills/review-resume/SKILL.md:

---
name: review-resume
description: "Reviews a product manager resume against a job posting and provides structured feedback."
---

Title and Introduction

Immediately following the front-matter, an H1 heading (#) provides the skill's display name, followed by a brief paragraph introducing the capability. This serves as the user-facing entry point for the skill.

Purpose Section

The ## Purpose section clarifies why the skill exists and what problem it solves. According to the source analysis, this section typically appears around line 9 in standard skill files.

Input Arguments

The ## Input Arguments section defines required and optional parameters using the ## Input Arguments heading (typically line 12). Variables use the $ prefix convention—such as $RESUME, $JOB_POSTING, or $NAME—to enable runtime substitution by the execution engine.

Response Structure

Under ## Response Structure (typically line 16), skills define deterministic output formats using numbered subsections (e.g., ### 1. Introduction, ### 2. Detailed Feedback). This structure forces the model to produce predictable, parseable results that downstream commands can chain together.

Best Practices and Guidelines

The core behavioral instructions appear under ### Best Practice X sections (e.g., ### Best Practice 1: Professional Summary around line 40). These blocks contain evaluation criteria and concrete suggestions. Optional ## Important Guidelines sections (around line 96) specify tone constraints and phrasing restrictions.

Further Reading

Many skills conclude with ### Further Reading sections (around line 176) linking to external resources for deeper context.

Why This Schema Design Works

The schema provides three architectural advantages according to the phuryn/pm-skills source code:

• Self-describing: YAML headers enable machine registration while Markdown bodies remain human-maintainable.
• Deterministic output: Prescribed response structures produce predictable results that downstream commands can chain together.
• Extensible: Adding capabilities requires only copying the template and customizing content blocks, with no code changes necessary.

Minimal Skill File Example

Below is a runnable template following the schema that can be placed in any plugin's skills/ folder:

---
name: hello-world
description: "A simple demonstration skill that greets the user and echoes a supplied name."
---

# Hello World Skill

## Purpose

Say hello to the user, optionally incorporating a custom name.

## Input Arguments

- `$NAME`: (Optional) The name to insert into the greeting.

## Response Structure

### 1. Greeting

A friendly opening line.

### 2. Confirmation

A short statement confirming the name was received (if provided).

### 3. Closing

A polite sign-off.

### 1. Greeting

Hello! 👋

### 2. Confirmation

${NAME:+Nice to meet you, $NAME!}

### 3. Closing

Let me know how I can help you today.

Real-World Schema Implementations

The repository demonstrates this schema across diverse domains:

• Resume Review: pm-toolkit/skills/review-resume/SKILL.md — Complete example with multiple best practice blocks
• Legal Documents: pm-toolkit/skills/draft-nda/SKILL.md — Contract drafting with specific clause structures
• Strategic Analysis: pm-product-strategy/skills/swot-analysis/SKILL.md — Framework-based analysis
• Data Analytics: pm-data-analytics/skills/sql-queries/SKILL.md — Technical query generation
• Go-to-Market: pm-go-to-market/skills/ideal-customer-profile/SKILL.md — Market research methodologies

All files follow the identical YAML front-matter and Markdown section pattern, confirming the schema's consistency across plugin boundaries.

Summary

• PM Skills uses a Markdown-based skill file schema with YAML front-matter for metadata registration.
• Required sections include Purpose, Input Arguments (with $ prefixed variables), and Response Structure with numbered subsections.
• Best Practice blocks contain the core AI behavioral instructions that drive model output.
• Files are stored as SKILL.md within plugin skills/ directories, such as pm-toolkit/skills/review-resume/SKILL.md.
• The informal but consistent schema enables automatic skill registration without rigid validation constraints or code changes.

Frequently Asked Questions

What file extension does the skill file schema use?

All skill files use the .md extension, specifically named SKILL.md to distinguish them from documentation. The parser identifies executable skills by their location within a plugin's skills/ directory and their adherence to the YAML front-matter pattern.

How are optional parameters defined in the schema?

Optional parameters appear in the ## Input Arguments section with explicit "(Optional)" notation. The runtime substitutes variables prefixed with $ (e.g., $NAME, $JOB_POSTING), and templates can use shell-like parameter expansion such as ${NAME:+Nice to meet you, $NAME!} to handle absent values gracefully.

Where are skill files located in the repository?

According to the phuryn/pm-skills source code, skill files live under each plugin's skills/ subdirectory (e.g., pm-toolkit/skills/review-resume/SKILL.md). This hierarchical organization keeps capabilities self-contained within their respective product management domains.

Is there a formal JSON Schema or validation file?

No, the repository does not ship a separate schema definition file. The schema is informal but rigidly consistent—every skill adheres to the same YAML front-matter and Markdown heading structure. This convention-over-configuration approach allows the plugin loader to parse skills dynamically without rigid validation constraints.

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