PM Skills SKILL.md File Format Specification: A Complete Guide for AI Agent Skills

The PM Skills repository defines a lightweight Markdown schema called SKILL.md that enables Claude-based agents to automatically discover, invoke, and execute reusable product management prompts with structured inputs and outputs.

The phuryn/pm-skills repository organizes reusable prompts for product managers using a standardized Markdown format known as SKILL.md. This self-describing schema allows AI agents including Claude Code, Claude Cowork, Codex, Gemini, and OpenCode to parse skill metadata, substitute variables, and generate consistent, structured outputs. Understanding this file format specification is essential for extending the marketplace with custom skills or integrating existing ones into your workflow.

What is the SKILL.md Format?

The SKILL.md format is a framework-agnostic specification for defining AI-ready skills. Each file serves as a single source of truth that combines metadata, instructions, and response templates in plain Markdown. Unlike proprietary prompt formats, this schema works across any LLM that ingests Markdown, enabling portable product management workflows.

Anatomy of a SKILL.md File

YAML Front-Matter for Metadata

Every SKILL.md begins with YAML front-matter declaring the skill's identity. Agents read this block to expose the skill in their plugin registry without parsing the entire file.

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

---
name: review-resume
description: "Comprehensive PM resume review with actionable feedback"
---

The name field becomes the command identifier (e.g., /review-resume), while the description appears in command palettes and help documentation.

Title and Purpose Declaration

Following the front-matter, a Markdown H1 title provides the human-readable heading. The Purpose / Role description section explains who the skill serves and what expertise it embodies. This contextualizes the model when invoked.

For example, the resume review skill declares: "You are an expert resume reviewer specializing in product management candidates..."

Input Arguments and Variable Substitution

Skills declare required and optional parameters using $PLACEHOLDER syntax. Agents perform runtime substitution before sending prompts to the LLM.

Common input pattern:

• $RESUME: The resume text or content to review
• $JOB_POSTING: The target job description for contextual feedback

When invoking via Claude Code, these map to command flags:

claude /review-resume --resume "..." --job_posting "Senior PM at Acme"

Response Structure and Guidelines

The Response structure section defines expected output format, ensuring consistent replies across invocations. This typically includes numbered sections or bullet-point templates.

The Guidelines section provides domain knowledge, such as the "10 Best Practices for PM Resumes" found in the review-resume skill. Important guidelines cover tone, style, and prohibitions (e.g., "Keep feedback casual yet professional, avoid saying 'best practice'").

Directory Structure and Discovery

Skills reside in plugin-specific directories mirroring functional groupings. The repository structure follows the pattern:

pm-toolkit/skills/
├── review-resume/SKILL.md
pm-product-strategy/skills/
├── product-vision/SKILL.md
pm-execution/skills/
└── create-prd/SKILL.md

Discovery process:

1. Agents scan directories for SKILL.md files
2. Parse YAML front-matter to register name as a command
3. Load content on invocation, substituting $PLACEHOLDER variables
4. Apply response structure to format LLM output

Concrete Implementation Examples

Resume Review Skill

Located at pm-toolkit/skills/review-resume/SKILL.md, this skill demonstrates the full specification including input variables, a 10-point best-practice checklist, and structured feedback sections.

Product Vision Skill

Found at pm-product-strategy/skills/product-vision/SKILL.md, this shows how strategic skills express high-level planning workflows.

PRD Creation Skill

The file pm-execution/skills/create-prd/SKILL.md illustrates complex execution-oriented skills with multiple input parameters and detailed output templates.

Command Line and API Usage

Claude Code Integration

Install the toolkit and invoke skills directly:

claude plugin marketplace add phuryn/pm-skills
claude plugin install pm-toolkit@pm-skills

# Direct invocation with parameters

claude /review-resume --resume "John Doe - Product Manager..." --job_posting "Senior PM at Acme Corp"

Plain-Text Prompt Usage

For generic LLMs (Gemini, OpenAI, Cursor), copy the skill content and manually substitute variables:

You are the "review-resume" skill.

$RESUME:
John Doe – Product Manager with 5 years experience...

$JOB_POSTING:
Senior Product Manager – Acme Corp seeking Agile expertise...

Follow the response structure and guidelines defined in the skill.

Repository Reference Files

Key files defining the architecture:

• pm-toolkit/skills/review-resume/SKILL.md: Canonical example of a complete skill definition
• pm-product-strategy/skills/product-vision/SKILL.md: Strategic skill implementation
• pm-execution/skills/create-prd/SKILL.md: Execution workflow skill
• README.md: Marketplace overview and installation instructions
• CLAUDE.md: Canonical agent guidance (source of truth for Claude-based tools)
• AGENTS.md: Redirect file for non-Claude agents

Summary

• The SKILL.md format uses YAML front-matter for metadata discovery and Markdown for content structure
• Input variables use $PLACEHOLDER syntax for runtime substitution by agents
• Response structures ensure consistent, parseable outputs across different LLMs
• Skills are organized in directory hierarchies (pm-toolkit/skills/, pm-execution/skills/) that mirror functional domains
• The format is framework-agnostic, working with Claude, Codex, Gemini, OpenCode, and Cursor

Frequently Asked Questions

What is the purpose of YAML front-matter in SKILL.md?

The YAML front-matter declares the skill's machine-readable identity, including the name identifier used for command invocation and the description shown in agent marketplaces. Agents scan these headers during plugin loading to build command registries without parsing full file contents.

How do agents substitute input variables?

Agents replace $PLACEHOLDER variables (such as $RESUME or $JOB_POSTING) with supplied arguments at runtime. In Claude Code, these map to command-line flags like --resume, while in plain-text prompts, users manually substitute values before sending to the LLM.

Can SKILL.md files work with LLMs other than Claude?

Yes, the format is deliberately framework-agnostic. While CLAUDE.md provides canonical guidance for Claude-based tools, the Markdown structure works with any LLM that ingests plain text, including Gemini, OpenCode, Cursor, and standard OpenAI APIs.

Where can I find example SKILL.md implementations?

Reference implementations live in the repository's skill directories: pm-toolkit/skills/review-resume/SKILL.md provides a comprehensive example with input variables, while pm-execution/skills/create-prd/SKILL.md demonstrates complex execution workflows. The README.md at the repository root indexes all available plugins and commands.

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