YAML Frontmatter Format for Skill and Command Files in PM Skills

Both skill and command files in the pm-skills repository use a YAML frontmatter block enclosed in triple dashes (---) at the top of the file to declare metadata such as name, description, and optional argument-hint fields.

The pm-skills marketplace organizes product management capabilities into reusable assets defined by markdown files with strict YAML frontmatter conventions. This metadata block enables the Claude Code and Claude Cowork runtimes to discover, load, and describe skills and commands correctly. Understanding the exact schema prevents parsing errors and ensures seamless integration with the toolset.

Skill File Frontmatter (SKILL.md)

Skill definitions reside in SKILL.md files and require a minimal metadata block that establishes identity and purpose.

Required Fields

Every skill frontmatter must declare two keys:

• name – A unique identifier used when commands reference this skill (e.g., review-resume)
• description – A human-readable summary displayed in help text and UI listings

In pm-toolkit/skills/review-resume/SKILL.md, the frontmatter appears exactly at the file start:

---
name: review-resume
description: "Comprehensive PM resume review and tailoring against 10 best practices including XYZ+S formula, keyword optimization, job-specific tailoring, and structure."
---

Another example from pm-product-strategy/skills/product-vision/SKILL.md:

---
name: product-vision
description: "Craft an inspiring, achievable, and emotional product vision"
---

Command File Frontmatter (*.md)

Command files support a richer schema that includes UI hints for argument handling.

Required Fields

• description – A one-sentence explanation shown in the command palette

Optional Fields

• argument-hint – A short placeholder indicating what input the command expects (e.g., "<resume as text or file>"). Omit this field for commands that take no arguments.

The command definition in pm-toolkit/commands/review-resume.md demonstrates the full structure:

---
description: Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback
argument-hint: "<resume as text or file>"
---

Additional command examples in pm-product-strategy/commands/strategy.md follow the same pattern, varying only the specific hint text to match their input requirements.

Critical Formatting Rules

The runtime parser enforces strict formatting requirements that differ from standard markdown conventions:

• Position: The --- delimiters must occupy the very first lines of the file. Any preceding whitespace, comments, or text will break parsing.
• Case Sensitivity: All keys must be lower-case (name, not Name).
• Syntax: Use standard YAML key-value pairs with a colon followed by a space.
• Quoting: Wrap strings in single or double quotes when they contain commas, special characters, or colons to prevent YAML parsing errors.

Summary

• Skill files (SKILL.md) require name and description keys in their YAML frontmatter.
• Command files (*.md) require description and support an optional argument-hint field for UI placeholders.
• The frontmatter block must start at line one with triple dashes (---) and use lower-case keys only.
• Reference implementations exist in pm-toolkit/skills/review-resume/SKILL.md and pm-toolkit/commands/review-resume.md within the phuryn/pm-skills repository.

Frequently Asked Questions

Do I need to quote string values in the YAML frontmatter?

Quote strings that contain commas, special characters, or colons. Simple single-word values like product-vision do not require quotes, but descriptive text with punctuation—such as "Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback"—must be enclosed in single or double quotes to prevent YAML parsing errors.

Is the argument-hint field required for every command?

No, argument-hint is optional. Include it only when your command accepts arguments and you want to display a placeholder in the UI (e.g., "<resume as text or file>"). Commands that require no input should omit this key entirely, as demonstrated in several command files in the repository.

What happens if I include text before the YAML frontmatter block?

The parser will fail to recognize the metadata. According to the source implementation, the frontmatter must be the very first content in the file. Any preceding whitespace, comments, or markdown text will cause the runtime to ignore the skill or command definition, preventing discovery and loading.

Can I use uppercase letters in the YAML keys?

No, keys must be lower-case. The schema requires name, description, and argument-hint exactly as written. Using Name or Description will result in the field being unrecognized by the Claude Code runtime.

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