Structure of a PM Skills Skill File: The YAML-Markdown Blueprint Explained

A PM Skills skill file is a Markdown document with YAML front-matter that defines a reusable LLM prompt, containing sections for metadata, input arguments, step-by-step instructions, and output specifications.

The PM Skills repository organizes reusable product management prompts as discrete skill files. Understanding the structure of a PM Skills skill file is essential for contributors who want to extend the toolkit or customize existing workflows. Each skill follows a strict schema that balances human readability with machine parsability.

YAML Front-Matter: Machine-Readable Metadata

Every skill file begins with YAML front-matter delimited by triple dashes (---). This block declares the skill’s identity and discovery metadata.

---
name: prioritize-features
description: "Prioritize a backlog of feature ideas based on impact, effort, risk, and strategic alignment."
---

The name field acts as the unique identifier, while description explains the skill’s utility to both users and automated discovery tools. According to the repository structure, this front-matter enables CLI tools to index and invoke skills programmatically without parsing the entire document.

Title and Purpose Sections

Immediately following the front-matter, the file uses a top-level Markdown heading (#) for the human-readable title. The review-resume skill in pm-toolkit/skills/review-resume/SKILL.md demonstrates this pattern:

# Resume Review for Product Managers

Beneath the title, a Purpose section (using ## Purpose) provides context about when and why to invoke the skill. This section typically includes 2-3 paragraphs explaining the problem domain and the intended audience.

Input Arguments: Variable Injection Points

The Input Arguments section standardizes variable injection using dollar-prefixed identifiers in backticks. This convention allows the execution engine to substitute user data at runtime.

## Input Arguments

- `$RESUME`: The candidate's resume text or file path.
- `$JOB_POSTING` (optional): The target role description for contextual alignment.

As implemented in phuryn/pm-skills, explicit argument lists prevent runtime errors by declaring dependencies upfront. The parser validates that all required variables ($ARGUMENTS, $RESUME, etc.) are present before invoking the LLM.

Step-by-Step Instructions

The Instructions section drives the LLM workflow using ordered lists (1. ) or hierarchical subheadings (###). The prioritize-features skill in pm-product-discovery/skills/prioritize-features/SKILL.md illustrates this deterministic flow:

### Instructions

1. **Understand priorities** – Confirm product objectives and constraints.
2. **Evaluate each feature** – Assess Impact, Effort, Risk, and Strategic Alignment.
3. **Recommend the top 5** – Rank selections and provide justification.

Breaking logic into discrete steps improves response consistency and enables iterative refinement of specific reasoning stages.

Output Specification and Optional Sections

An Output heading defines the expected response format, whether Markdown tables, JSON blocks, or bulleted analyses. This contracts the LLM’s output structure before generation begins.

Optional sections include:

• Framework / Reference Section: Bullet points linking to external methodologies or formulas
• Further Reading: Curated links to documentation or tutorials at the document’s end

Directory Organization and File Paths

Skill files follow a strict physical layout within the repository:

• pm-toolkit/skills/**/SKILL.md – Core cross-functional skills (e.g., review-resume/SKILL.md)
• pm-product-discovery/skills/**/SKILL.md – Discovery-phase skills (e.g., prioritize-features/SKILL.md)
• pm-go-to-market/skills/**/SKILL.md – GTM workflows (e.g., gtm-strategy/SKILL.md)
• pm-ai-shipping/skills/**/SKILL.md – AI-assisted delivery skills
• pm-data-analytics/skills/**/SKILL.md – Data analysis prompts

Each skill resides in its own subdirectory containing the SKILL.md file and any associated assets.

Minimal Skill Template

Create a new skill by instantiating this skeleton in the appropriate subdirectory:

---
name: my-custom-skill
description: "One-sentence summary of what the skill does."
---

# My Skill Title

## Purpose

Explain when this skill should be used and what problem it solves for product managers.

## Input Arguments

- `$VARIABLE1`: Description of the first required argument.
- `$VARIABLE2` (optional): Description of an optional argument.

## Instructions

1. **Step 1** – Execute initial analysis using `$VARIABLE1`.
2. **Step 2** – Process intermediate results.
3. **Step 3** – Produce the final output according to specifications.

## Output

Describe the expected format (e.g., a markdown table comparing options).

## Further Reading

- [Relevant framework documentation](https://example.com)

Summary

• YAML front-matter (name, description) enables automatic skill discovery and CLI integration.
• Input Arguments use $VARIABLE syntax to standardize data injection across the PM Skills toolkit.
• Step-by-step instructions enforce deterministic LLM reasoning flows.
• Output specifications contract the response format before generation.
• Skill files reside in domain-specific subdirectories under pm-*/skills/ with the filename SKILL.md.

Frequently Asked Questions

What file extension do PM Skills skill files use?

All skill files use the .md extension and are named exactly SKILL.md. This convention allows the repository’s indexing logic to recursively discover skills across pm-toolkit/skills/, pm-product-discovery/skills/, and other domain directories by glob pattern matching.

Is the YAML front-matter mandatory in a skill file?

Yes. The --- delimited YAML block containing at minimum the name and description keys is required. The PM Skills parser uses this metadata to build the skill registry and generate command-line help text without loading the full Markdown content.

How do I reference user data inside a skill file?

Reference user data using dollar-prefixed variables in backticks within the Input Arguments section (e.g., - $RESUME``), then invoke those variables throughout the Instructions. The execution engine substitutes these placeholders with actual values at runtime.

Can a skill file include external links or dependencies?

Yes. The optional Further Reading and Framework sections support standard Markdown hyperlinks. While the skill file itself should be self-contained for execution, these sections provide contributors and advanced users with links to methodological sources or extended documentation.

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