# PM Skills File Format Specifications: Complete Guide for Developers > Understand the PM Skills file format specifications for developers. Our guide covers markdown structure, argument placeholders, numbered steps, and template sections for CLI parsing and LLM execution. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-06-19 --- **The PM Skills file format is a lightweight markdown specification that requires a description line, argument placeholders with `$` prefixes, numbered steps, and template sections to enable CLI parsing and LLM execution.** The `phuryn/pm-skills` repository defines a standardized markdown structure for skill files that balances human readability with machine parseability. Each skill file (conventionally named [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)) follows strict formatting rules so the CLI can extract metadata, inject user values, and generate prompts for large language models. ## Required Elements of the PM Skills File Format Every skill file must contain four mandatory components. The parser in `pm-toolkit/commands/*.md` specifically looks for these tokens to construct the execution pipeline. ### Description Line The first non-empty line after any optional front-matter must begin with `description:` followed by a succinct summary. This line powers the `--help` text in the CLI. ```markdown description: "Review a resume for structure, impact and readability." ``` ### Argument Placeholders Variables expected from users use the `$` prefix wrapped in backticks, such as `` `$ARGUMENTS` `` or `` `$FORMAT` ``. The CLI scans for these tokens to build interactive prompts. According to the source code, every placeholder should be documented in the optional Inputs section, though the parser only requires the tokens themselves to be present. ### Steps and Instructions One or more numbered steps (`1.`, `2.`, etc.) describe the workflow the LLM must follow. Steps can contain sub-bullets, inline code, and markdown formatting. These steps are sent verbatim to the LLM as the process instructions. ```markdown 1. Gather user information from the provided transcript. 2. Analyze content for key decisions and action items. 3. Generate the resume section using the template below. ``` ### Template Sections When a skill produces structured output (like a resume or NDA), a markdown code fence (`` ```markdown ``) contains the template skeleton. Placeholders inside templates follow the same `$VARIABLE` convention, allowing the LLM to substitute values directly. ```markdown ```markdown ## Resume – $NAME **Date:** $DATE **Participants:** $PARTICIPANTS ### Experience - $JOB_TITLE at $COMPANY ``` ``` ### Output Format Description A brief paragraph or bullet must specify how results are returned—whether saved to disk (e.g., `Resume-$NAME.md`) or returned as a markdown string. This guides the CLI's post-processing logic. ## Optional Elements and Metadata While the parser enforces the core structure, the specification supports optional sections that improve documentation and safety. ### Front-Matter YAML An optional one-line YAML block at the very top exposes metadata like `title`, `category`, or `tags`. The engine ignores this block, but it helps humans navigate the skill set in `pm-toolkit/skills/`. ```markdown --- title: Review Resume category: toolkit --- ``` ### Inputs Documentation An optional bullet list explains each placeholder's expected type and validation rules. Though the parser skips this section, it serves as the contract between skill authors and CLI users. ```markdown - `$FORMAT`: Output format – one of **CSV**, **JSON**, **SQL**, **Python**. - `$ROWS`: Number of rows to generate (integer). ``` ### Legal Disclaimers Skills touching legal topics often include a bold disclaimer reminding users to seek professional advice. This is purely presentational. ```markdown **⚠️ LEGAL REVIEW REQUIRED** ``` ## How the CLI Consumes the Format The command runner in `pm-toolkit/commands/*.md` implements a six-stage pipeline to transform skill files into executable LLM prompts. 1. **Read the file** – The runner loads the markdown file as raw text from the `skills/` directory. 2. **Extract the description** – The first line matching `^description:` becomes the short-help text shown in `pm-toolkit help`. 3. **Detect placeholders** – All `` `$WORD` `` tokens are collected; the CLI builds an interactive prompt asking for values unless supplied via command-line flags. 4. **Render the steps** – The numbered list is sent verbatim to the LLM as the process instructions. 5. **Insert user values** – The LLM substitutes `$PLACEHOLDER` tokens with the collected values. 6. **Return the result** – Based on the *Output format* specification, the CLI either prints the result, saves it to the working directory, or returns it to the caller. ## File Structure and Examples Reference implementations in `phuryn/pm-skills` demonstrate the specification in practice. ### Minimal Skill File This example from the repository shows the smallest valid skill definition: ```markdown description: "Summarize a meeting transcript." 1. Read the transcript supplied by the user. 2. Extract key decisions, action items, and open questions. 3. Output a concise markdown summary. ```markdown ## Meeting Summary – $TITLE **Date:** $DATE **Participants:** $PARTICIPANTS ### Decisions - ... ### Action Items - ... ### Open Questions - ... ``` ``` ### Complex Skill with Multiple Placeholders The `pm-toolkit/skills/draft-nda/SKILL.md` (referenced by `pm-toolkit/commands/draft-nda.md`) illustrates advanced usage: ```markdown description: "Generate a dummy dataset for testing." - `$COLUMNS`: Comma-separated list of column definitions (`name:type`). - `$ROWS`: Number of rows to generate. - `$FORMAT`: One of **CSV**, **JSON**, **SQL**, **Python**. 1. Validate `$COLUMNS` and `$ROWS`. 2. Create synthetic data respecting types and ranges. 3. Render the data in the `$FORMAT` specified. ```markdown # $FORMAT output for $COLUMNS ... ``` ``` ### CLI Invocation When executing a skill, the CLI reads the file, prompts for missing placeholders, and runs the LLM: ```bash pm-toolkit generate-dataset \ --columns "id:int,name:string,created_at:date" \ --rows 100 \ --format CSV ``` The engine writes `dataset.csv` to the current folder based on the output format description in the skill file. ## Summary - **PM Skills files** use a strict markdown format stored in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files within repository subdirectories like `pm-toolkit/skills/` and `pm-execution/skills/`. - **Required elements** include the `description:` line, `$` prefixed argument placeholders, numbered steps, and output format specifications. - **Template sections** use markdown code fences with `$VARIABLE` tokens for LLM-driven content generation. - **The CLI parser** in `pm-toolkit/commands/*.md` extracts descriptions, detects placeholders, and feeds steps to the LLM without modifying the core engine for each new skill. ## Frequently Asked Questions ### What file extension should PM Skills files use? PM Skills files must use the `.md` extension and are conventionally named [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). The CLI loader specifically looks for markdown files when resolving skill paths in directories like `pm-toolkit/skills/review-resume/`. ### Does the PM Skills format support YAML frontmatter? Yes, an optional YAML frontmatter block can appear at the top of the file for metadata such as `title` or `category`. The parser ignores this block, so it does not affect CLI execution or LLM prompts. ### How do I define required user inputs in a PM Skills file? Required inputs are defined using backtick-wrapped placeholders like `` `$ARGUMENTS` `` or `` `$FORMAT` `` anywhere in the file. The CLI automatically detects these tokens and prompts the user for values unless they are provided via command-line flags. ### Where is the parser implementation located? The parser logic resides in the command files under `pm-toolkit/commands/*.md` and `pm-execution/commands/`. These files load the corresponding skill files from `pm-toolkit/skills/` subdirectories and orchestrate the extraction of descriptions, placeholders, and steps.