# PM Skills SKILL.md File Format Specification: A Complete Guide for AI Agent Skills > Master the PM Skills SKILL.md file format specification. This guide helps Claude agents discover, invoke, and execute product management prompts efficiently with structured data. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: api-reference - Published: 2026-07-05 --- **The PM Skills repository defines a lightweight Markdown schema called [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) that enables Claude-based agents to automatically discover, invoke, and execute reusable product management prompts with structured inputs and outputs.** The `phuryn/pm-skills` repository organizes reusable prompts for product managers using a standardized Markdown format known as [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). This self-describing schema allows AI agents including Claude Code, Claude Cowork, Codex, Gemini, and OpenCode to parse skill metadata, substitute variables, and generate consistent, structured outputs. Understanding this file format specification is essential for extending the marketplace with custom skills or integrating existing ones into your workflow. ## What is the SKILL.md Format? The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) format is a framework-agnostic specification for defining AI-ready skills. Each file serves as a single source of truth that combines metadata, instructions, and response templates in plain Markdown. Unlike proprietary prompt formats, this schema works across any LLM that ingests Markdown, enabling portable product management workflows. ## Anatomy of a SKILL.md File ### YAML Front-Matter for Metadata Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) begins with YAML front-matter declaring the skill's identity. Agents read this block to expose the skill in their plugin registry without parsing the entire 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: "Comprehensive PM resume review with actionable feedback" --- ``` The `name` field becomes the command identifier (e.g., `/review-resume`), while the `description` appears in command palettes and help documentation. ### Title and Purpose Declaration Following the front-matter, a Markdown H1 title provides the human-readable heading. The **Purpose / Role description** section explains who the skill serves and what expertise it embodies. This contextualizes the model when invoked. For example, the resume review skill declares: "You are an expert resume reviewer specializing in product management candidates..." ### Input Arguments and Variable Substitution Skills declare required and optional parameters using `$PLACEHOLDER` syntax. Agents perform runtime substitution before sending prompts to the LLM. Common input pattern: - `$RESUME`: The resume text or content to review - `$JOB_POSTING`: The target job description for contextual feedback When invoking via Claude Code, these map to command flags: ```bash claude /review-resume --resume "..." --job_posting "Senior PM at Acme" ``` ### Response Structure and Guidelines The **Response structure** section defines expected output format, ensuring consistent replies across invocations. This typically includes numbered sections or bullet-point templates. The **Guidelines** section provides domain knowledge, such as the "10 Best Practices for PM Resumes" found in the review-resume skill. **Important guidelines** cover tone, style, and prohibitions (e.g., "Keep feedback casual yet professional, avoid saying 'best practice'"). ## Directory Structure and Discovery Skills reside in plugin-specific directories mirroring functional groupings. The repository structure follows the pattern: ``` pm-toolkit/skills/ ├── review-resume/SKILL.md pm-product-strategy/skills/ ├── product-vision/SKILL.md pm-execution/skills/ └── create-prd/SKILL.md ``` Discovery process: 1. Agents scan directories for [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files 2. Parse YAML front-matter to register `name` as a command 3. Load content on invocation, substituting `$PLACEHOLDER` variables 4. Apply response structure to format LLM output ## Concrete Implementation Examples ### Resume Review Skill Located at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md), this skill demonstrates the full specification including input variables, a 10-point best-practice checklist, and structured feedback sections. ### Product Vision Skill Found at [`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md), this shows how strategic skills express high-level planning workflows. ### PRD Creation Skill The file [`pm-execution/skills/create-prd/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-execution/skills/create-prd/SKILL.md) illustrates complex execution-oriented skills with multiple input parameters and detailed output templates. ## Command Line and API Usage ### Claude Code Integration Install the toolkit and invoke skills directly: ```bash claude plugin marketplace add phuryn/pm-skills claude plugin install pm-toolkit@pm-skills # Direct invocation with parameters claude /review-resume --resume "John Doe - Product Manager..." --job_posting "Senior PM at Acme Corp" ``` ### Plain-Text Prompt Usage For generic LLMs (Gemini, OpenAI, Cursor), copy the skill content and manually substitute variables: ``` You are the "review-resume" skill. $RESUME: John Doe – Product Manager with 5 years experience... $JOB_POSTING: Senior Product Manager – Acme Corp seeking Agile expertise... Follow the response structure and guidelines defined in the skill. ``` ## Repository Reference Files Key files defining the architecture: - **[`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md)**: Canonical example of a complete skill definition - **[`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md)**: Strategic skill implementation - **[`pm-execution/skills/create-prd/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-execution/skills/create-prd/SKILL.md)**: Execution workflow skill - **[`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md)**: Marketplace overview and installation instructions - **[`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)**: Canonical agent guidance (source of truth for Claude-based tools) - **[`AGENTS.md`](https://github.com/phuryn/pm-skills/blob/main/AGENTS.md)**: Redirect file for non-Claude agents ## Summary - The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) format uses YAML front-matter for metadata discovery and Markdown for content structure - Input variables use `$PLACEHOLDER` syntax for runtime substitution by agents - Response structures ensure consistent, parseable outputs across different LLMs - Skills are organized in directory hierarchies (`pm-toolkit/skills/`, `pm-execution/skills/`) that mirror functional domains - The format is framework-agnostic, working with Claude, Codex, Gemini, OpenCode, and Cursor ## Frequently Asked Questions ### What is the purpose of YAML front-matter in SKILL.md? The YAML front-matter declares the skill's machine-readable identity, including the `name` identifier used for command invocation and the `description` shown in agent marketplaces. Agents scan these headers during plugin loading to build command registries without parsing full file contents. ### How do agents substitute input variables? Agents replace `$PLACEHOLDER` variables (such as `$RESUME` or `$JOB_POSTING`) with supplied arguments at runtime. In Claude Code, these map to command-line flags like `--resume`, while in plain-text prompts, users manually substitute values before sending to the LLM. ### Can SKILL.md files work with LLMs other than Claude? Yes, the format is deliberately framework-agnostic. While [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) provides canonical guidance for Claude-based tools, the Markdown structure works with any LLM that ingests plain text, including Gemini, OpenCode, Cursor, and standard OpenAI APIs. ### Where can I find example SKILL.md implementations? Reference implementations live in the repository's skill directories: [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) provides a comprehensive example with input variables, while [`pm-execution/skills/create-prd/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-execution/skills/create-prd/SKILL.md) demonstrates complex execution workflows. The [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) at the repository root indexes all available plugins and commands.