Best Practices for Developing PM Skills: A Complete Guide to the pm-skills Framework

Developing PM Skills effectively requires creating self-contained markdown modules with standardized YAML frontmatter, explicit input arguments, and checklist-based content structures that Claude agents can automatically discover and execute.

The phuryn/pm-skills repository organizes product management knowledge as a modular marketplace of plugins, where each skill is a pure markdown file and each command orchestrates multiple skills into end-to-end workflows. Understanding the architectural layers—from the plugin manifest to individual skill files—is essential for developing PM Skills that integrate reliably with Claude Code and other AI assistants.

Understanding the pm-skills Architecture

The repository follows a strict four-layer architecture that separates concerns between marketplace organization, plugin metadata, knowledge modules, and workflow orchestration.

Layer	Description	Key Files
Marketplace	The root level groups nine plugins covering the full PM lifecycle, described in the project README with installation instructions for Claude assistants.	README.md
Plugin Manifest	Each plugin folder contains a .claude-plugin/plugin.json declaring name, version, author, and license. Claude's plugin loader reads this JSON to expose available commands and skills.	pm-toolkit/.claude-plugin/plugin.json
Skills	Every skill lives in a SKILL.md file under <plugin>/skills/. The file starts with YAML frontmatter (--- containing name and description) followed by structured guides covering purpose, inputs, response structure, and best-practice checklists.	pm-toolkit/skills/review-resume/SKILL.md
Commands	Markdown files under <plugin>/commands/ describe slash-commands (e.g., /discover, /plan-launch) that chain multiple skills together. These are declarative specifications, not executable code.	pm-go-to-market/commands/plan-launch.md

This separation ensures contributors can add new frameworks without touching unrelated code, while the Claude runtime loads only relevant pieces on demand.

10 Best Practices for Developing PM Skills

1. Keep Skills Self-Contained

Skills must be pure markdown without external script dependencies or data imports. This guarantees compatibility across any Claude-compatible assistant.

Start every new skill with the mandatory YAML block:

---
name: customer-journey-mapping
description: "Step-by-step guide to build a detailed customer journey map..."
---

Follow the pattern from review-resume/SKILL.md: purpose, inputs, response structure, then checklist.

2. Follow the Standard Checklist Layout

All existing skills use a numbered "Best Practice #" layout, making them searchable by Claude and skimmable for humans. Replicate the structure from pm-toolkit/skills/review-resume/SKILL.md with sections for Evaluation, Guidance, and Examples.

3. Use Consistent Naming

Commands and skills are referenced by their file stem (e.g., review-resume). Use kebab-case for folder and file names, ensuring the folder and file match exactly. Avoid spaces or special characters to prevent ambiguous invocations.

4. Document Input Arguments Explicitly

Skills accepting variables like $RESUME or $JOB_POSTING need clear placeholder definitions. List arguments in a bullet list under an "Input Arguments" section:

## Input Arguments

- `$PRODUCT`: Name of the product or service
- `$TARGET_USER`: Persona or segment description

5. Add Inline Links to External References

Provide markdown links to product management literature (not bare URLs) to improve the knowledge graph for Claude. Example:

Reference: [Continuous Discovery Habits](https://www.amazon.com/Continuous-Discovery-Habits-Discover-Products/dp/1736633309/)

6. Include Usage Examples in Commands

Every command file should show a one-line invocation example. Add an "Example" block at the bottom mirroring the README's "Start Here" style:

## Example

/journey-map product=AcmeCRM target=SMB-sales-team

7. Version Plugins Semantically

The plugin.json version follows semver. Bump the minor version when adding new skills, and the patch version for bug fixes. Update the version field and commit with conventional commit messages:

git commit -m "feat(pm-toolkit): add customer-journey-mapping skill"

8. Write Unit-Test-Like Scenarios

Add a "Test Scenario" section with sample user prompts and expected Claude replies in fenced code blocks. This helps reviewers verify expected behavior without running the full plugin.

9. Store Images in .docs/images/

All visual assets belong in this central location. Reference them with relative paths (.docs/images/my-diagram.png) to prevent broken links across plugins.

10. Review Licensing and Attribution

Every plugin.json declares the MIT license. Ensure new files contain license references or appropriate attribution for third-party content.

Creating a New Skill: Step-by-Step Implementation

To add a "customer-journey-mapping" skill to the pm-market-research plugin:

1. Create the folder structure:

mkdir -p pm-market-research/skills/customer-journey-mapping

2. Add SKILL.md with the complete structure:

---
name: customer-journey-mapping
description: "Step-by-step guide to build a detailed customer journey map, covering stages, touchpoints, emotions, and pain points."
---

# Customer Journey Mapping

## Purpose

Create a visual representation of a user's end-to-end experience...

## Input Arguments

- `$PRODUCT`: Name of the product or service
- `$TARGET_USER`: Persona or segment description

## Response Structure

1. **Stages** – List the main phases (Awareness, Consideration, …)
2. **Touchpoints** – For each stage, enumerate key interactions
3. **Emotions & Pain Points** – Qualitative notes

## Best Practice 1: Define Clear Stages

...

3. Update pm-market-research/.claude-plugin/plugin.json to version 1.1.0 (minor bump for new skill).

Orchestrating Workflows with Commands

Commands chain skills into conversational flows. To wire the new skill to a command, create pm-market-research/commands/journey-map.md:

# /journey-map

Chains the `customer-journey-mapping` skill with optional follow-up `metrics-dashboard` skill.

## Example

/journey-map product=AcmeCRM target=SMB-sales-team

Users can now invoke /journey-map and Claude will automatically load the associated skill.

CLI Invocation Example

Install and invoke existing commands directly:

claude plugin install pm-go-to-market@pm-skills
claude /plan-launch "AI-code-review tool for mid-size engineering teams"

Claude loads the plan-launch command from pm-go-to-market/commands/plan-launch.md, which internally calls the gtm-strategy, ideal-customer-profile, and growth-loops skills.

Essential File Reference

File	Role	Location
README.md	Marketplace overview and installation steps	Root
CLAUDE.md	Contributor guide defining agent behavior standards	Root
plugin.json	Plugin manifest declaring version and metadata	<plugin>/.claude-plugin/plugin.json
SKILL.md	Canonical skill template with YAML frontmatter	pm-toolkit/skills/review-resume/SKILL.md
plan-launch.md	Example command chaining strategic skills	pm-go-to-market/commands/plan-launch.md
plugins.png	Visual plugin landscape overview	.docs/images/plugins.png

Summary

• Developing PM Skills requires treating each skill as an independent markdown module with mandatory YAML frontmatter (name and description)
• Follow the established checklist layout from review-resume/SKILL.md to ensure Claude can parse content effectively
• Use kebab-case naming consistently across folders and files to prevent invocation errors
• Document input arguments explicitly and provide inline markdown links to external references
• Version plugins semantically in plugin.json, bumping minor versions for new skills
• Store all images in .docs/images/ and maintain MIT license compliance across all new contributions

Frequently Asked Questions

How do I structure the YAML frontmatter for a new skill?

Every skill file must begin with a YAML block enclosed in triple dashes containing exactly two fields: name (kebab-case identifier) and description (short summary). This metadata allows Claude's plugin loader to index the skill correctly. See pm-toolkit/skills/review-resume/SKILL.md for the canonical implementation.

What is the difference between a skill and a command in pm-skills?

A skill is a self-contained markdown module under <plugin>/skills/ that contains specific domain knowledge (e.g., resume review frameworks). A command is a workflow orchestrator under <plugin>/commands/ that chains multiple skills together using slash-command syntax (e.g., /plan-launch). Commands are declarative specifications, not executable scripts.

How should I version my plugin when adding new skills?

Follow semantic versioning in the plugin's plugin.json. Increment the minor version (e.g., 1.0.0 to 1.1.0) when adding new skills, and increment the patch version (e.g., 1.0.0 to 1.0.1) for bug fixes or documentation updates. Use conventional commit messages like feat(plugin-name): add skill-name.

Where should I store documentation images and diagrams?

Always place visual assets in the .docs/images/ directory at the repository root. Reference them using relative paths (e.g., .docs/images/workflow-diagram.png) rather than absolute URLs. This central location prevents broken links when plugins are moved or referenced across different contexts.

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