Understanding the Structure of a Skill File in PM Skills

A skill file in PM Skills is a Markdown document with YAML front-matter that defines reusable LLM prompts through standardized metadata, input variables, and step-by-step instructions.

The PM Skills repository (phuryn/pm-skills) organizes product management expertise into modular, machine-readable prompts. Each skill resides in a SKILL.md file that follows a strict structure enabling both human editing and programmatic invocation by the toolkit.

Core Components of a PM Skills File

Every skill file follows a canonical layout that separates machine-readable metadata from executable instructions.

YAML Front-Matter for Metadata

The file opens with YAML front-matter delimited by triple dashes (---). This block declares the skill’s identity using required fields like name and description, allowing the CLI engine to discover and expose the skill as a command without manual registration.

Document Title and Purpose

Immediately following the front-matter, a top-level Markdown heading (#) provides the human-readable title. Subsequent sections explain the Purpose & Context, describing when and why to invoke the skill, which helps contributors understand the intended use case.

Input Arguments Definition

A dedicated section lists required and optional variables using the $VARIABLE syntax. For example:

• $RESUME: The candidate's resume content
• $JOB_POSTING: The target role description
• $ARGUMENTS: Product context and feature lists

This standardization allows the toolkit to inject data programmatically at runtime.

Step-by-Step Instructions

The core logic appears as a numbered list or subsections detailing the LLM workflow. These instructions enforce deterministic reasoning by breaking complex tasks into logical steps, such as evaluating features against Impact, Effort, Risk, and Strategic Alignment.

Output Specification and Optional Sections

An Output section defines the expected response format (tables, JSON blocks, or narrative structures). Optional sections include Framework / Reference for external formulas and Further Reading for documentation links.

Real-World Examples from the Repository

The repository demonstrates this structure through concrete implementations in domain-specific directories.

Review-Resume Skill

In pm-toolkit/skills/review-resume/SKILL.md, the file opens with YAML front-matter specifying name: review-resume, followed by a title header, Purpose section, Input Arguments listing $RESUME and $JOB_POSTING, and structured instructions for analyzing candidate fit against PM best practices.

Prioritize-Features Skill

Similarly, pm-product-discovery/skills/prioritize-features/SKILL.md declares metadata for backlog prioritization, accepts $ARGUMENTS for product context, and provides step-by-step instructions for evaluating features before recommending the top five candidates.

Minimal Skill Template

Create a new skill by following this exact template:

---
name: my-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.

## Input Arguments

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

## Instructions

1. **Step 1** – Do the first thing, referencing `$VARIABLE1` if needed.
2. **Step 2** – Continue the workflow, using any intermediate results.
3. **Step 3** – Produce the final output.

## Output

Describe the expected format (e.g., a markdown table, bullet list, JSON block).

## Further Reading

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

Where Skill Files Live in the Repository

Skill files are distributed across domain-specific directories following the pattern **/SKILL.md:

• pm-toolkit/skills/**/SKILL.md: Core toolkit 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 strategy skills
• pm-ai-shipping/skills/**/SKILL.md: AI-assisted shipping skills
• pm-data-analytics/skills/**/SKILL.md: Data analytics prompts

Adding a new skill requires creating a SKILL.md following the template above and placing it in the appropriate subdirectory.

Summary

• Skill files are Markdown documents with YAML front-matter stored as SKILL.md in domain-specific directories.
• Front-matter contains machine-readable metadata (name, description) for automatic discovery and CLI exposure.
• Input arguments use $VARIABLE syntax to standardize data injection and programmatic invocation.
• Instruction sections provide step-by-step LLM workflows that ensure deterministic, high-quality outputs.
• Output specifications define expected response formats, while optional sections handle frameworks and further reading.

Frequently Asked Questions

What file extension do PM Skills use?

PM Skills uses the .md extension for all skill files, specifically requiring the filename SKILL.md to distinguish executable prompts from documentation. This convention allows the toolkit to recursively discover skills across subdirectories.

Can I include optional variables in a skill file?

Yes. The structure supports optional arguments by denoting them in the Input Arguments section, typically marked with "(optional)" in the description while using the standard $VARIABLE syntax. The toolkit handles injection for both required and optional parameters.

How does the PM Skills toolkit discover new skills?

The toolkit parses the YAML front-matter in each SKILL.md file to extract the name and description fields, enabling automatic indexing and command exposure without manual registration or configuration updates.

Where should I place a new skill file in the repository?

Place new skills in the appropriate domain subdirectory under pm-toolkit/skills/, pm-product-discovery/skills/, or other relevant categories (pm-go-to-market/, pm-ai-shipping/, pm-data-analytics/), ensuring the file is named exactly SKILL.md to maintain discovery compatibility.

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