# YAML Frontmatter Format for Skill and Command Files in PM Skills > Learn the YAML frontmatter format for skill and command files in the phuryn/pm-skills repository. Define metadata like name description and argument-hint. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-06-24 --- **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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), the frontmatter appears exactly at the file start: ```yaml --- 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`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md): ```yaml --- 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., `""`). Omit this field for commands that take no arguments. The command definition in [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) demonstrates the full structure: ```yaml --- description: Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback argument-hint: "" --- ``` Additional command examples in [`pm-product-strategy/commands/strategy.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) and [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/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., `""`). 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.