# Best Practices for Writing AI-Compatible PM Skills in the PM-Skills Marketplace > Learn best practices for writing AI-compatible PM skills. Structure your SKILL.md file with YAML frontmatter, clear instructions, and defined input/output for optimal AI interaction. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: best-practices - Published: 2026-07-05 --- **To write AI-compatible PM skills, create a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with YAML frontmatter defining the name, description, and triggers, followed by structured sections for Instructions, Input Requirements, and Output Format that use numbered steps and concrete evaluation criteria.** The **PM-Skills Marketplace** is a collection of skills (knowledge-base markdown files) and commands (slash-invoked workflows) that Claude-compatible AI assistants load automatically from the `phuryn/pm-skills` repository. Each skill encodes a proven product-management framework, and following the repository’s strict conventions for metadata, input handling, and response structure ensures your skill is usable by AI agents. ## Architecture of an AI-Compatible PM Skill The repository organizes AI-compatible components into a predictable hierarchy. Understanding these file locations and purposes is essential for creating valid skills. ### Skill Definition Files Skill definitions reside at `*/skills/*/SKILL.md` within plugin folders. These markdown files serve as prompt templates that describe the skill's name, description, input arguments, and step-by-step process. Claude extracts the `name` header from the YAML frontmatter, loads the description into its knowledge graph, and follows the *Instructions* section when invoked. ### Command Definitions Command files live in `*/commands/*.md` and map slash-commands (e.g., `/discover`) to sequences of skill invocations. When a user types `/discover`, the assistant loads the command file, parses the ordered list of skills, and runs each in turn, feeding the output of one as the input to the next. ### Plugin Structure Plugins are logical groupings under `pm-/` directories (e.g., `pm-product-discovery/`). Installing a plugin makes every contained skill available automatically. The AI runtime discovers all [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files in the plugin directory and registers them under the plugin namespace. ## Best Practices for Metadata and Naming The frontmatter and metadata section determine how the AI discovers and invokes your skill. - **Use kebab-case for the skill name**. This keeps URLs and command references tidy. For example, `name: product-vision` (as seen in [`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md)). - **Provide a concise one-sentence description**. This appears in the plugin catalog and helps the AI decide when to auto-load. Example: `description: "Brainstorm an inspiring, achievable, and emotional product vision..."`. - **Add `Triggers` keywords** that match likely user intents. This enables auto-loading when the model detects relevant phrases. Example: `Triggers: product vision, vision statement, north star vision`. - **Document required arguments with `$VARIABLE` placeholders**. This guarantees the AI knows what it must retrieve from the user. See `$RESUME` and `$JOB_POSTING` in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md). ## Designing Effective Instructions The Instructions section determines how the AI executes the framework. Follow these patterns derived from existing skills like `review-resume` and `product-vision`. **Start with a clear role statement**. Begin with `You are an expert...` to give the model a persona. For example, "You are an expert resume reviewer..." sets the appropriate tone and expertise level. **Break the workflow into numbered steps**. This makes the model’s reasoning traceable and ensures deterministic output order. See the six-step process under *Process* in [`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md). **Provide concrete evaluation criteria**. Specific criteria allow the model to give actionable, measurable feedback rather than generic advice. Example: "Check for first-person pronouns" instead of "check tone." **Include example good/bad snippets**. Lines 48-53 in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) demonstrate how examples help the model understand the difference between high and low quality outputs. **End with a concise output format**. Use structured headers like `### Part 1: Summary` to guarantee predictable output that downstream commands can parse, as implemented in [`pm-toolkit/skills/draft-nda/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/draft-nda/SKILL.md). ## Content Quality Standards Maintain strict quality standards to ensure reliable AI performance. - **Stay domain-specific** – Focus on PM frameworks (e.g., XYZ+S formula, Opportunity Solution Tree). - **Be concise** – Keep files under 2,000 lines; large blocks of static text make prompts heavy and slow. - **Use plain language** – The model should be able to explain the skill to a non-technical user. - **Add disclaimers where required** – Avoid legal or medical advice; see the disclaimer pattern in [`pm-toolkit/skills/draft-nda/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/draft-nda/SKILL.md). ## Testing and Validation Before submitting, verify your skill functions correctly within the AI runtime. 1. **Run the skill through Claude or OpenCode** using a minimal prompt to verify the output matches the declared structure. 2. **Check that all `$VARIABLE`s are substituted** by the command runner; missing variables cause the model to ask for clarification. 3. **Confirm that triggers do not clash** with other skills by searching with `grep` for duplicate trigger words across the repository. ## Code Examples ### Minimal Skill Skeleton Create new skills using this exact structure found in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md): ```markdown --- name: my-new-skill description: "Brief one-sentence summary of what the skill does." --- # My New Skill ## Metadata - **Name**: my-new-skill - **Description**: … - **Triggers**: keyword1, keyword2 ## Instructions You are a seasoned product manager. Your job is to … (describe the role). ## Input Requirements - `$INPUT_A`: Description of the first argument. - `$INPUT_B` (optional): … ## Output 1. **Header** – a short statement of the result. 2. **Details** – bullet points or a table with the core findings. ## Process 1. Validate `$INPUT_A` exists. 2. Apply the framework (list steps). 3. Summarize the outcome in the format above. ``` This ordering—frontmatter → title → metadata → instructions → input → output → process—matches all existing skills and allows reliable AI parsing. ### Chaining Skills with Commands Create workflow commands in [`pm-product-discovery/commands/discover.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/commands/discover.md) to chain multiple skills: ```markdown # /my-workflow ## Description Runs a complete product discovery flow: idea generation → assumption mapping → prioritization. ## Steps 1. `brainstorm-ideas-existing` – uses the user’s product context. 2. `identify-assumptions-existing` – consumes the ideas output. 3. `prioritize-assumptions` – consumes the assumptions output. 4. `brainstorm-experiments-existing` – consumes the prioritized list. ## Example Invocation /my-workflow AI-powered note-taking app ``` When a user types `/my-workflow`, the assistant loads each listed skill in order, passing the previous skill’s output as `$ARGUMENTS` to the next skill. ## Key Reference Files Study these existing implementations to understand the conventions: - **Resume Review**: [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) - **NDA Drafting**: [`pm-toolkit/skills/draft-nda/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/draft-nda/SKILL.md) - **Product Vision**: [`pm-product-strategy/skills/product-vision/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-strategy/skills/product-vision/SKILL.md) - **Opportunity Solution Tree**: [`pm-product-discovery/skills/opportunity-solution-tree/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/skills/opportunity-solution-tree/SKILL.md) - **Create PRD**: [`pm-execution/skills/create-prd/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-execution/skills/create-prd/SKILL.md) - **SQL Queries**: [`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md) - **GTM Strategy**: [`pm-go-to-market/skills/gtm-strategy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-go-to-market/skills/gtm-strategy/SKILL.md) - **Shipping Artifacts**: [`pm-ai-shipping/skills/shipping-artifacts/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md) ## Summary - Create [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files in `pm-/skills//` with YAML frontmatter and kebab-case names. - Define clear input variables using `$VARIABLE` syntax and deterministic output formats. - Write Instructions with numbered steps, role statements, and concrete evaluation criteria. - Add `Triggers` keywords for auto-discovery and keep content under 2,000 lines. - Use command files in `*/commands/*.md` to chain skills into end-to-end workflows. - Validate variable substitution and trigger uniqueness before committing. ## Frequently Asked Questions ### What file extension should I use for PM skills? Use `.md` (markdown) for all skill definitions. The AI runtime specifically searches for files named [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) within skill directories to identify loadable skills. Command files should also use the `.md` extension and reside in the `commands` folder of their respective plugin. ### How do I handle optional inputs in a skill? Mark optional inputs in the **Input Requirements** section with the `(optional)` tag after the variable name. For example: `- $INPUT_B (optional): Description here.` The AI will attempt to substitute the variable if provided, but will not prompt the user if it remains undefined, allowing the skill to proceed with default logic. ### Can I reference external knowledge or URLs in a skill? While you can include URLs in the description or metadata, the skill should be self-contained. The AI loads the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) content as a prompt template; it cannot fetch external URLs during execution. All frameworks, criteria, and examples should be inline within the file to ensure deterministic behavior without external dependencies. ### How do I organize related skills into a workflow? Create a command file in the `pm-/commands/` directory. List the skills in execution order under the `## Steps` section. The output of each skill automatically feeds into the next as `$ARGUMENTS`. For example, [`pm-product-discovery/commands/discover.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/commands/discover.md) chains idea generation, assumption mapping, and prioritization into a single `/discover` invocation.