File Format for a Skill in phuryn/pm-skills: YAML Front Matter Specification

A skill in the phuryn/pm-skills repository is defined as a Markdown file named SKILL.md that contains YAML front matter specifying the skill's metadata, followed by free-form Markdown content describing the prompt structure, inputs, and outputs.

The phuryn/pm-skills repository organizes product management capabilities as discrete, file-based modules. Understanding the file format for a skill in phuryn/pm-skills is essential for extending the toolkit, as the system dynamically discovers and loads these files at runtime based on strict naming and structure conventions.

Skill File Structure

Every skill file consists of two distinct sections parsed by the toolkit. The formal structure enables automated discovery while maintaining flexibility for documentation.

YAML Front Matter Requirements

The file must begin with YAML front matter delimited by triple dashes (---). This section declares the skill's identity using two required fields:

• name: A kebab-case identifier used as the internal reference (e.g., review-resume)
• description: A concise one-sentence summary displayed in skill listings

---
name: review-resume
description: "Comprehensive PM resume review and tailoring against 10 best practices..."
---

Markdown Body Content

Following the front matter, the remainder of the file uses standard Markdown to document the skill's behavior. The body typically includes sections for purpose, input arguments (denoted with dollar-prefixed variables like $PRODUCT), response structure, and best-practice guidance. There is no fixed schema for the body content, allowing authors to structure documentation as needed using headings, bullet lists, and code blocks.

File Location and Naming Convention

Skills must reside in specific directory patterns to be discovered by the toolkit. The primary location follows this structure:

pm-toolkit/skills/<skill-name>/SKILL.md

For example, the resume review skill is located at pm-toolkit/skills/review-resume/SKILL.md. The toolkit also scans additional directories such as pm-product-strategy/skills/<skill-name>/SKILL.md for strategy-related capabilities. The uniform naming convention—always SKILL.md inside a skill-specific folder—enables the dynamic loader to recurse through these directories and register available skills automatically.

Creating a New Skill: Practical Example

To create a skill named value-prop-statement, create the directory pm-toolkit/skills/value-prop-statement/ and save the following content to SKILL.md:

---
name: value-prop-statement
description: "Generate concise product value‑prop statements from a brief."
---

# Value Proposition Statement Generator

## Purpose

Produce a one‑sentence value proposition that captures the product’s core benefit.

## Input Arguments

- `$PRODUCT`: Name of the product.
- `$TARGET`: Target audience or customer segment.
- `$PROBLEM`: Core problem the product solves.

## Response Structure

1. **Headline** – a punchy one‑liner.
2. **Explanation** – 1‑2 sentences expanding the headline.

Saving this file makes the skill immediately available to the toolkit without additional configuration, as the system parses the YAML header to extract the name and description while treating the Markdown body as the skill's operational specification.

How the Toolkit Discovers Skills

According to the phuryn/pm-skills source code, the toolkit implements a dynamic loader that scans for files named exactly SKILL.md within the skills directories. Upon discovery, it parses the YAML front matter to validate the presence of name and description fields. This architecture allows the repository to scale organically—adding new capabilities requires only creating a new directory with a properly formatted SKILL.md file, with no registry files or manifest updates needed.

Summary

• Format: Markdown files using .md extension named exactly SKILL.md
• Structure: YAML front matter (with name and description fields) followed by Markdown body content
• Location: pm-toolkit/skills/<skill-name>/SKILL.md or pm-product-strategy/skills/<skill-name>/SKILL.md
• Discovery: Toolkit auto-detects files by scanning for SKILL.md filenames and parsing their front matter
• Flexibility: Body content supports standard Markdown with no fixed schema beyond the required YAML header

Frequently Asked Questions

What are the required fields in the YAML front matter for a skill?

The front matter must include two fields: name (a kebab-case identifier such as review-resume) and description (a one-sentence summary of the skill's purpose). These fields are mandatory for the toolkit to register and list the skill correctly.

Can I use custom fields in the YAML front matter?

While the toolkit specifically requires name and description for discovery and listing, additional custom fields may be included in the YAML block. However, the current implementation primarily consumes these two standard fields, with the remaining content handled as free-form Markdown.

What happens if I use a different filename than SKILL.md?

The toolkit will not recognize the file as a skill. The discovery mechanism specifically searches for files named SKILL.md (case-sensitive) within the skills directories. Using alternative names or extensions will exclude the file from automatic loading.

Is there a specific Markdown flavor required for the body content?

The repository uses standard Markdown syntax for the body. You can include headings, bullet lists, numbered lists, code blocks, and links. The content is rendered as-is when the skill is invoked, so clear structure using ## and ### headings is recommended for readability.

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