# Skill File Schema in PM Skills: Complete Markdown Specification Guide > Explore the Skill File schema in PM Skills. This guide details the complete Markdown specification, enabling AI agents to parse, register, and execute skills deterministically. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-06-28 --- **The PM Skills repository defines a lightweight, self-describing Markdown schema with YAML front-matter and standardized sections that enables AI agents to parse, register, and execute skills deterministically.** The phuryn/pm-skills project organizes product management capabilities as discrete, self-contained skill files. Each skill follows a consistent Markdown-based schema that balances human readability with machine parseability, allowing the plugin loader to automatically register capabilities without requiring code changes. ## Skill File Location and Conventions All skill files reside within plugin-specific `skills/` directories following the path pattern [`plugin-name/skills/skill-name/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/plugin-name/skills/skill-name/SKILL.md). For example, the resume review capability lives at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) according to the repository source code. ## Core Schema Components The skill file schema consists of seven distinct elements that appear in consistent order throughout every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. ### YAML Front-Matter Every skill file opens with **YAML front-matter** specifying the skill's unique identifier and description. The `name` field provides the machine-readable identifier, while `description` offers human-readable context for the plugin loader. This metadata occupies lines 1-4 of the file. Example from [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md): ```yaml --- name: review-resume description: "Reviews a product manager resume against a job posting and provides structured feedback." --- ``` ### Title and Introduction Immediately following the front-matter, an H1 heading (`#`) provides the skill's display name, followed by a brief paragraph introducing the capability. This serves as the user-facing entry point for the skill. ### Purpose Section The `## Purpose` section clarifies why the skill exists and what problem it solves. According to the source analysis, this section typically appears around line 9 in standard skill files. ### Input Arguments The `## Input Arguments` section defines required and optional parameters using the `## Input Arguments` heading (typically line 12). Variables use the `$` prefix convention—such as `$RESUME`, `$JOB_POSTING`, or `$NAME`—to enable runtime substitution by the execution engine. ### Response Structure Under `## Response Structure` (typically line 16), skills define deterministic output formats using numbered subsections (e.g., `### 1. Introduction`, `### 2. Detailed Feedback`). This structure forces the model to produce predictable, parseable results that downstream commands can chain together. ### Best Practices and Guidelines The core behavioral instructions appear under `### Best Practice X` sections (e.g., `### Best Practice 1: Professional Summary` around line 40). These blocks contain evaluation criteria and concrete suggestions. Optional `## Important Guidelines` sections (around line 96) specify tone constraints and phrasing restrictions. ### Further Reading Many skills conclude with `### Further Reading` sections (around line 176) linking to external resources for deeper context. ## Why This Schema Design Works The schema provides three architectural advantages according to the phuryn/pm-skills source code: - **Self-describing**: YAML headers enable machine registration while Markdown bodies remain human-maintainable. - **Deterministic output**: Prescribed response structures produce predictable results that downstream commands can chain together. - **Extensible**: Adding capabilities requires only copying the template and customizing content blocks, with no code changes necessary. ## Minimal Skill File Example Below is a runnable template following the schema that can be placed in any plugin's `skills/` folder: ```markdown --- name: hello-world description: "A simple demonstration skill that greets the user and echoes a supplied name." --- # Hello World Skill ## Purpose Say hello to the user, optionally incorporating a custom name. ## Input Arguments - `$NAME`: (Optional) The name to insert into the greeting. ## Response Structure ### 1. Greeting A friendly opening line. ### 2. Confirmation A short statement confirming the name was received (if provided). ### 3. Closing A polite sign-off. ### 1. Greeting Hello! 👋 ### 2. Confirmation ${NAME:+Nice to meet you, $NAME!} ### 3. Closing Let me know how I can help you today. ``` ## Real-World Schema Implementations The repository demonstrates this schema across diverse domains: - **Resume Review**: [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) — Complete example with multiple best practice blocks - **Legal Documents**: [`pm-toolkit/skills/draft-nda/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/draft-nda/SKILL.md) — Contract drafting with specific clause structures - **Strategic Analysis**: [`pm-product-strategy/skills/swot-analysis/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/swot-analysis/SKILL.md) — Framework-based analysis - **Data Analytics**: [`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md) — Technical query generation - **Go-to-Market**: [`pm-go-to-market/skills/ideal-customer-profile/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-go-to-market/skills/ideal-customer-profile/SKILL.md) — Market research methodologies All files follow the identical YAML front-matter and Markdown section pattern, confirming the schema's consistency across plugin boundaries. ## Summary - PM Skills uses a Markdown-based **skill file schema** with YAML front-matter for metadata registration. - Required sections include Purpose, Input Arguments (with `$` prefixed variables), and Response Structure with numbered subsections. - Best Practice blocks contain the core AI behavioral instructions that drive model output. - Files are stored as [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) within plugin `skills/` directories, such as [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md). - The informal but consistent schema enables automatic skill registration without rigid validation constraints or code changes. ## Frequently Asked Questions ### What file extension does the skill file schema use? All skill files use the `.md` extension, specifically named [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) to distinguish them from documentation. The parser identifies executable skills by their location within a plugin's `skills/` directory and their adherence to the YAML front-matter pattern. ### How are optional parameters defined in the schema? Optional parameters appear in the `## Input Arguments` section with explicit "(Optional)" notation. The runtime substitutes variables prefixed with `$` (e.g., `$NAME`, `$JOB_POSTING`), and templates can use shell-like parameter expansion such as `${NAME:+Nice to meet you, $NAME!}` to handle absent values gracefully. ### Where are skill files located in the repository? According to the phuryn/pm-skills source code, skill files live under each plugin's `skills/` subdirectory (e.g., [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md)). This hierarchical organization keeps capabilities self-contained within their respective product management domains. ### Is there a formal JSON Schema or validation file? No, the repository does not ship a separate schema definition file. The schema is informal but rigidly consistent—every skill adheres to the same YAML front-matter and Markdown heading structure. This convention-over-configuration approach allows the plugin loader to parse skills dynamically without rigid validation constraints.