PM Skills File Format Specifications: Complete Guide for Developers

The PM Skills file format is a lightweight markdown specification that requires a description line, argument placeholders with $ prefixes, numbered steps, and template sections to enable CLI parsing and LLM execution.

The phuryn/pm-skills repository defines a standardized markdown structure for skill files that balances human readability with machine parseability. Each skill file (conventionally named SKILL.md) follows strict formatting rules so the CLI can extract metadata, inject user values, and generate prompts for large language models.

Required Elements of the PM Skills File Format

Every skill file must contain four mandatory components. The parser in pm-toolkit/commands/*.md specifically looks for these tokens to construct the execution pipeline.

Description Line

The first non-empty line after any optional front-matter must begin with description: followed by a succinct summary. This line powers the --help text in the CLI.

description: "Review a resume for structure, impact and readability."

Argument Placeholders

Variables expected from users use the $ prefix wrapped in backticks, such as `$ARGUMENTS` or `$FORMAT`. The CLI scans for these tokens to build interactive prompts. According to the source code, every placeholder should be documented in the optional Inputs section, though the parser only requires the tokens themselves to be present.

Steps and Instructions

One or more numbered steps (1., 2., etc.) describe the workflow the LLM must follow. Steps can contain sub-bullets, inline code, and markdown formatting. These steps are sent verbatim to the LLM as the process instructions.

1. Gather user information from the provided transcript.
2. Analyze content for key decisions and action items.
3. Generate the resume section using the template below.

Template Sections

When a skill produces structured output (like a resume or NDA), a markdown code fence (```markdown) contains the template skeleton. Placeholders inside templates follow the same $VARIABLE convention, allowing the LLM to substitute values directly.

```markdown

## Resume – $NAME

**Date:** $DATE
**Participants:** $PARTICIPANTS

### Experience

- $JOB_TITLE at $COMPANY

### Output Format Description

A brief paragraph or bullet must specify how results are returned—whether saved to disk (e.g., `Resume-$NAME.md`) or returned as a markdown string. This guides the CLI's post-processing logic.

## Optional Elements and Metadata

While the parser enforces the core structure, the specification supports optional sections that improve documentation and safety.

### Front-Matter YAML

An optional one-line YAML block at the very top exposes metadata like `title`, `category`, or `tags`. The engine ignores this block, but it helps humans navigate the skill set in `pm-toolkit/skills/`.

```markdown
---
title: Review Resume
category: toolkit
---

Inputs Documentation

An optional bullet list explains each placeholder's expected type and validation rules. Though the parser skips this section, it serves as the contract between skill authors and CLI users.

- `$FORMAT`: Output format – one of **CSV**, **JSON**, **SQL**, **Python**.
- `$ROWS`: Number of rows to generate (integer).

Legal Disclaimers

Skills touching legal topics often include a bold disclaimer reminding users to seek professional advice. This is purely presentational.

**⚠️ LEGAL REVIEW REQUIRED**

How the CLI Consumes the Format

The command runner in pm-toolkit/commands/*.md implements a six-stage pipeline to transform skill files into executable LLM prompts.

1. Read the file – The runner loads the markdown file as raw text from the skills/ directory.
2. Extract the description – The first line matching ^description: becomes the short-help text shown in pm-toolkit help.
3. Detect placeholders – All `$WORD` tokens are collected; the CLI builds an interactive prompt asking for values unless supplied via command-line flags.
4. Render the steps – The numbered list is sent verbatim to the LLM as the process instructions.
5. Insert user values – The LLM substitutes $PLACEHOLDER tokens with the collected values.
6. Return the result – Based on the Output format specification, the CLI either prints the result, saves it to the working directory, or returns it to the caller.

File Structure and Examples

Reference implementations in phuryn/pm-skills demonstrate the specification in practice.

Minimal Skill File

This example from the repository shows the smallest valid skill definition:

description: "Summarize a meeting transcript."

1. Read the transcript supplied by the user.
2. Extract key decisions, action items, and open questions.
3. Output a concise markdown summary.

```markdown

## Meeting Summary – $TITLE

**Date:** $DATE  
**Participants:** $PARTICIPANTS  

### Decisions

- ...

### Action Items

- ...

### Open Questions

- ...

### Complex Skill with Multiple Placeholders

The `pm-toolkit/skills/draft-nda/SKILL.md` (referenced by `pm-toolkit/commands/draft-nda.md`) illustrates advanced usage:

```markdown
description: "Generate a dummy dataset for testing."

- `$COLUMNS`: Comma-separated list of column definitions (`name:type`).
- `$ROWS`: Number of rows to generate.
- `$FORMAT`: One of **CSV**, **JSON**, **SQL**, **Python**.

1. Validate `$COLUMNS` and `$ROWS`.
2. Create synthetic data respecting types and ranges.
3. Render the data in the `$FORMAT` specified.

```markdown

# $FORMAT output for $COLUMNS

...

### CLI Invocation

When executing a skill, the CLI reads the file, prompts for missing placeholders, and runs the LLM:

```bash
pm-toolkit generate-dataset \
  --columns "id:int,name:string,created_at:date" \
  --rows 100 \
  --format CSV

The engine writes dataset.csv to the current folder based on the output format description in the skill file.

Summary

• PM Skills files use a strict markdown format stored in SKILL.md files within repository subdirectories like pm-toolkit/skills/ and pm-execution/skills/.
• Required elements include the description: line, $ prefixed argument placeholders, numbered steps, and output format specifications.
• Template sections use markdown code fences with $VARIABLE tokens for LLM-driven content generation.
• The CLI parser in pm-toolkit/commands/*.md extracts descriptions, detects placeholders, and feeds steps to the LLM without modifying the core engine for each new skill.

Frequently Asked Questions

What file extension should PM Skills files use?

PM Skills files must use the .md extension and are conventionally named SKILL.md. The CLI loader specifically looks for markdown files when resolving skill paths in directories like pm-toolkit/skills/review-resume/.

Does the PM Skills format support YAML frontmatter?

Yes, an optional YAML frontmatter block can appear at the top of the file for metadata such as title or category. The parser ignores this block, so it does not affect CLI execution or LLM prompts.

How do I define required user inputs in a PM Skills file?

Required inputs are defined using backtick-wrapped placeholders like `$ARGUMENTS` or `$FORMAT` anywhere in the file. The CLI automatically detects these tokens and prompts the user for values unless they are provided via command-line flags.

Where is the parser implementation located?

The parser logic resides in the command files under pm-toolkit/commands/*.md and pm-execution/commands/. These files load the corresponding skill files from pm-toolkit/skills/ subdirectories and orchestrate the extraction of descriptions, placeholders, and steps.

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