# Best Practices for Developing PM Skills: A Complete Guide to the pm-skills Framework > Master PM skills with best practices for developing self-contained markdown modules, standardized YAML frontmatter, and explicit arguments for Claude agents. Build your PM expertise now. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: best-practices - Published: 2026-06-19 --- **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`](https://github.com/phuryn/pm-skills/blob/main/README.md) | | **Plugin Manifest** | Each plugin folder contains a [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json) | | **Skills** | Every skill lives in a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file under `/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`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) | | **Commands** | Markdown files under `/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`](https://github.com/phuryn/pm-skills/blob/main/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: ```markdown --- name: customer-journey-mapping description: "Step-by-step guide to build a detailed customer journey map..." --- ``` Follow the pattern from [`review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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: ```markdown ## 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: ```markdown 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: ```markdown ## Example /journey-map product=AcmeCRM target=SMB-sales-team ``` ### 7. Version Plugins Semantically The [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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: ```bash 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`](https://github.com/phuryn/pm-skills/blob/main/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: ```bash mkdir -p pm-market-research/skills/customer-journey-mapping ``` 2. Add [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) with the complete structure: ```markdown --- 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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-market-research/commands/journey-map.md): ```markdown # /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: ```bash 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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/README.md) | Marketplace overview and installation steps | Root | | [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) | Contributor guide defining agent behavior standards | Root | | [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) | Plugin manifest declaring version and metadata | `/.claude-plugin/plugin.json` | | [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) | Canonical skill template with YAML frontmatter | [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) | | [`plan-launch.md`](https://github.com/phuryn/pm-skills/blob/main/plan-launch.md) | Example command chaining strategic skills | [`pm-go-to-market/commands/plan-launch.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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 `/skills/` that contains specific domain knowledge (e.g., resume review frameworks). A **command** is a workflow orchestrator under `/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`](https://github.com/phuryn/pm-skills/blob/main/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.