Best Practices for Writing AI-Compatible PM Skills in the PM-Skills Marketplace

To write AI-compatible PM skills, create a 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-<domain>/ directories (e.g., pm-product-discovery/). Installing a plugin makes every contained skill available automatically. The AI runtime discovers all 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).

• 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.

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.

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 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.

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.

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 $VARIABLEs 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:

---
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 to chain multiple skills:

# /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
• NDA Drafting: pm-toolkit/skills/draft-nda/SKILL.md
• Product Vision: pm-product-strategy/skills/product-vision/SKILL.md
• Opportunity Solution Tree: pm-product-discovery/skills/opportunity-solution-tree/SKILL.md
• Create PRD: pm-execution/skills/create-prd/SKILL.md
• SQL Queries: pm-data-analytics/skills/sql-queries/SKILL.md
• GTM Strategy: pm-go-to-market/skills/gtm-strategy/SKILL.md
• Shipping Artifacts: pm-ai-shipping/skills/shipping-artifacts/SKILL.md

Summary

• Create SKILL.md files in pm-<domain>/skills/<your-skill>/ 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 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 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-<domain>/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 chains idea generation, assumption mapping, and prioritization into a single /discover invocation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}