/utility-pm-skill-builder

name: utility-pm-skill-builder
description: Guides contributors from a PM skill idea to a complete Skill Implementation Packet aligned with pm-skills conventions. Runs gap analysis, validates through a Why Gate, classifies by type and phase, generates draft files, and writes to a staging area for review before promotion.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.2.0"
  updated: 2026-07-04
  category: coordination
  frameworks: [triple-diamond]
  author: product-on-purpose

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

PM Skill Builder

This skill creates new PM skills for the pm-skills library. It produces a Skill Implementation Packet - a complete design document with draft files in a staging area for review before promotion to canonical locations.

When to Use

• When you have an idea for a new PM skill
• When you want to add a domain skill (phase-specific), foundation skill

(cross-cutting), or utility skill (meta/tooling) to the pm-skills library

• When a contributor needs guided skill creation that follows repo conventions

When NOT to Use

• To modify or improve an existing skill → use `utility-pm-skill-iterate`
• To audit an existing skill against conventions → use `utility-pm-skill-validate`
• To create a skill for a non-pm-skills context → use a general agent skill builder
• To create a workflow → workflows are authored directly, not via this builder

Instructions

When asked to create a new PM skill, follow these steps:

Step 1: Understand the Idea

Accept the idea in either form:

• **Problem-first**: "What PM problem does this skill solve? Who runs into

this problem, and what do they currently produce (or fail to produce)?"

• **Skill-first**: "Describe the skill you want to create. What artifact

does it produce? What PM activity does it support?"

Both entry points produce the same downstream flow. If the user provides one form, do not ask for the other - extract what you need and proceed.

If the idea is vague, ask ONE follow-up question to clarify the artifact type and target audience before proceeding.

Step 2: Gap Analysis

Check ALL existing skills for overlap. Use the Current Library Reference below (derive the live inventory from `skill-manifest.json` or `AGENTS.md`) AND scan the `skills/` directory for the latest inventory. Include all four families - domain, foundation, utility, and tool - the tool family is easy to miss since it has no phase prefix pattern in common conversation.

Present findings with specificity:

• Name each overlapping skill and explain what it covers
• Identify the specific gap this new skill would fill
• If overlap is high, trigger the Why Gate (see below)

**Why Gate** (triggers when overlap is found): Ask the user: "Name 2-3 specific prompts or scenarios where the existing skills fail to produce what you need."

**Kill Gate**: If the user cannot articulate convincing gaps, recommend an alternative:

• "Revise [existing skill] to cover this case"
• "Create a workflow combining [skill A] + [skill B]"
• "Add a command variant, not a new skill"
• "This is a documentation improvement, not a new skill"

Do not proceed past the kill gate without either convincing evidence of a gap or explicit user override.

Step 3: Scope Check

Evaluate whether the idea should be ONE skill or MULTIPLE skills.

**Splitting signals:**

• The idea produces multiple distinct artifact types
• The idea crosses Triple Diamond phases (e.g., Discover + Deliver)
• The description naturally contains "and" connecting two activities

If splitting is warranted, present the recommendation: "This seems to cover two distinct PM activities: 1. [Activity A] → produces [Artifact A] 2. [Activity B] → produces [Artifact B] These work better as separate skills that can be chained via a workflow. Want to proceed with just [Activity A] for now?"

Step 4: Classification + Repo-Fit

Determine the skill's classification and naming:

**Domain skills** (phase-specific PM activities):

• Phase: discover | define | develop | deliver | measure | iterate
• Directory: `{phase}-{skill-name}`
• Frontmatter: `phase: {phase}` (required), no `classification` field

**Foundation skills** (cross-cutting, used across phases):

• No phase
• Directory: `foundation-{skill-name}`
• Frontmatter: `classification: foundation` (required), no `phase` field
• Use when: the skill applies to multiple phases equally

**Utility skills** (meta-skills, repo tooling):

• No phase
• Directory: `utility-{skill-name}`
• Frontmatter: `classification: utility` (required), no `phase` field
• Use when: the skill operates on the repo, workflow, or other skills

**Dialect and exemplar selection:** First, pick the skill's dialect from [Skeleton Canon: The Three Sanctioned Dialects](../../site/src/content/docs/guides/creating-pm-skills.md#skeleton-canon-the-three-sanctioned-dialects) (classic, contract-shaped, or tool-family) - this fixes the required heading skeleton before any exemplar is chosen. Do not default to "mirror the closest exemplar": an exemplar can itself carry drift (a case variant, an extra or missing section), and a straight mirror copies that drift forward into the new skill.

Then identify 1-2 existing skills in the SAME dialect that are the closest structural match:

• Same phase > same category > similar artifact type
• Read their SKILL.md to confirm instruction style, output-contract wording,

and quality-checklist pattern (the canon fixes the required headings; the exemplar informs everything else - tone, step granularity, and any skill-specific extra sections)

• Name the exemplars explicitly: "Modeled after [skill] - same phase,

[category] category, [dialect] dialect"

Present the classification, dialect, and exemplar selection for user confirmation.

Step 4.5: Eval Readiness (the eval contract)

A new skill must ship **eval-ready** so coverage never falls behind: routing health and output quality are