# Structure of a PM Skills Skill File: The YAML-Markdown Blueprint Explained > Explore the structure of a PM Skills skill file. Learn how YAML-Markdown blueprints define reusable LLM prompts with metadata, inputs, instructions, and output specs. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-07-06 --- **A PM Skills skill file is a Markdown document with YAML front-matter that defines a reusable LLM prompt, containing sections for metadata, input arguments, step-by-step instructions, and output specifications.** The **PM Skills** repository organizes reusable product management prompts as discrete skill files. Understanding the structure of a PM Skills skill file is essential for contributors who want to extend the toolkit or customize existing workflows. Each skill follows a strict schema that balances human readability with machine parsability. ## YAML Front-Matter: Machine-Readable Metadata Every skill file begins with YAML front-matter delimited by triple dashes (`---`). This block declares the skill’s identity and discovery metadata. ```yaml --- name: prioritize-features description: "Prioritize a backlog of feature ideas based on impact, effort, risk, and strategic alignment." --- ``` The `name` field acts as the unique identifier, while `description` explains the skill’s utility to both users and automated discovery tools. According to the repository structure, this front-matter enables CLI tools to index and invoke skills programmatically without parsing the entire document. ## Title and Purpose Sections Immediately following the front-matter, the file uses a top-level Markdown heading (`#`) for the human-readable title. The **review-resume** skill in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) demonstrates this pattern: ```markdown # Resume Review for Product Managers ``` Beneath the title, a **Purpose** section (using `## Purpose`) provides context about when and why to invoke the skill. This section typically includes 2-3 paragraphs explaining the problem domain and the intended audience. ## Input Arguments: Variable Injection Points The **Input Arguments** section standardizes variable injection using dollar-prefixed identifiers in backticks. This convention allows the execution engine to substitute user data at runtime. ```markdown ## Input Arguments - `$RESUME`: The candidate's resume text or file path. - `$JOB_POSTING` (optional): The target role description for contextual alignment. ``` As implemented in `phuryn/pm-skills`, explicit argument lists prevent runtime errors by declaring dependencies upfront. The parser validates that all required variables (`$ARGUMENTS`, `$RESUME`, etc.) are present before invoking the LLM. ## Step-by-Step Instructions The **Instructions** section drives the LLM workflow using ordered lists (`1. `) or hierarchical subheadings (`###`). The **prioritize-features** skill in [`pm-product-discovery/skills/prioritize-features/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/skills/prioritize-features/SKILL.md) illustrates this deterministic flow: ```markdown ### Instructions 1. **Understand priorities** – Confirm product objectives and constraints. 2. **Evaluate each feature** – Assess Impact, Effort, Risk, and Strategic Alignment. 3. **Recommend the top 5** – Rank selections and provide justification. ``` Breaking logic into discrete steps improves response consistency and enables iterative refinement of specific reasoning stages. ## Output Specification and Optional Sections An **Output** heading defines the expected response format, whether Markdown tables, JSON blocks, or bulleted analyses. This contracts the LLM’s output structure before generation begins. Optional sections include: - **Framework / Reference Section**: Bullet points linking to external methodologies or formulas - **Further Reading**: Curated links to documentation or tutorials at the document’s end ## Directory Organization and File Paths Skill files follow a strict physical layout within the repository: - `pm-toolkit/skills/**/SKILL.md` – Core cross-functional skills (e.g., [`review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/review-resume/SKILL.md)) - `pm-product-discovery/skills/**/SKILL.md` – Discovery-phase skills (e.g., [`prioritize-features/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/prioritize-features/SKILL.md)) - `pm-go-to-market/skills/**/SKILL.md` – GTM workflows (e.g., [`gtm-strategy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/gtm-strategy/SKILL.md)) - `pm-ai-shipping/skills/**/SKILL.md` – AI-assisted delivery skills - `pm-data-analytics/skills/**/SKILL.md` – Data analysis prompts Each skill resides in its own subdirectory containing the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file and any associated assets. ## Minimal Skill Template Create a new skill by instantiating this skeleton in the appropriate subdirectory: ```yaml --- name: my-custom-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 for product managers. ## Input Arguments - `$VARIABLE1`: Description of the first required argument. - `$VARIABLE2` (optional): Description of an optional argument. ## Instructions 1. **Step 1** – Execute initial analysis using `$VARIABLE1`. 2. **Step 2** – Process intermediate results. 3. **Step 3** – Produce the final output according to specifications. ## Output Describe the expected format (e.g., a markdown table comparing options). ## Further Reading - [Relevant framework documentation](https://example.com) ``` ## Summary - **YAML front-matter** (`name`, `description`) enables automatic skill discovery and CLI integration. - **Input Arguments** use `$VARIABLE` syntax to standardize data injection across the PM Skills toolkit. - **Step-by-step instructions** enforce deterministic LLM reasoning flows. - **Output specifications** contract the response format before generation. - Skill files reside in domain-specific subdirectories under `pm-*/skills/` with the filename [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). ## Frequently Asked Questions ### What file extension do PM Skills skill files use? All skill files use the `.md` extension and are named exactly [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). This convention allows the repository’s indexing logic to recursively discover skills across `pm-toolkit/skills/`, `pm-product-discovery/skills/`, and other domain directories by glob pattern matching. ### Is the YAML front-matter mandatory in a skill file? Yes. The `---` delimited YAML block containing at minimum the `name` and `description` keys is required. The PM Skills parser uses this metadata to build the skill registry and generate command-line help text without loading the full Markdown content. ### How do I reference user data inside a skill file? Reference user data using dollar-prefixed variables in backticks within the **Input Arguments** section (e.g., `- `$RESUME``), then invoke those variables throughout the **Instructions**. The execution engine substitutes these placeholders with actual values at runtime. ### Can a skill file include external links or dependencies? Yes. The optional **Further Reading** and **Framework** sections support standard Markdown hyperlinks. While the skill file itself should be self-contained for execution, these sections provide contributors and advanced users with links to methodological sources or extended documentation.