---
title: "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."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Utility
  - coordination
---

:::note[Quick facts]
**Classification:** Utility | **Version:** 1.0.0 | **Category:** coordination | **License:** Apache-2.0
:::

**Try it:** `/pm-skill-builder "Your context here"`

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 an existing skill → use a future validation/iteration utility (planned)
- To create a skill for a non-pm-skills context → use a general agent skill builder (planned)
- To create a workflow → workflows are authored directly, not via this builder

## How to Use

Use the `/pm-skill-builder` slash command:

```
/pm-skill-builder "Your context here"
```

Or reference the skill file directly: `skills/utility-pm-skill-builder/SKILL.md`

## 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
table below AND scan the `skills/` directory for the latest inventory.

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

**Exemplar selection:**
Identify 1-2 existing skills that are the closest structural match:
- Same phase > same category > similar artifact type
- Read their SKILL.md to understand section structure, instruction style,
  output contract format, and quality checklist pattern
- Name the exemplars explicitly: "Modeled after [skill] . same phase,
  [category] category"

Present the classification and exemplar selection for user confirmation.

### Step 5: Generate Skill Implementation Packet

Produce the complete packet using `references/TEMPLATE.md` as the format.
The packet includes:

1. **Decision** . recommendation + Why Gate evidence (if applicable)
2. **Classification** . type, phase (if domain), category, directory name
3. **Overlap Analysis** . what was found, why this skill is still needed
4. **Exemplar Skills** . which existing skills modeled, why
5. **Draft Frontmatter** . complete, valid YAML block. The frontmatter MUST begin with `---` at byte 0 of the file (no preceding content of any kind, including HTML comments, BOM, or whitespace). Place any attribution comment AFTER the closing `---` fence, never before. Reference: `library/skill-output-samples/SAMPLE_CREATION.md` Section 5.
6. **Draft SKILL.md** . full content (not an outline), mirroring exemplar structure
7. **Draft TEMPLATE.md** . section headers with guidance comments
8. **Draft EXAMPLE.md** . complete, realistic example (150-300 lines) with a
   specific PM scenario, every section filled, optional sections demonstrated
   both filled and skipped
9. **Draft Command** . command frontmatter
10. **AGENTS.md Entry** . exact text to add
11. **Validation Checklist** . all CI rules checked against the draft
12. **Next Steps** . local CI, testing, contribution workflow

### Step 6: Write to Staging Area

Write all generated files to the staging area:

```
_staging/pm-skill-builder/{skill-name}/
├── SKILL.md               ← draft skill file
├── references/
│   ├── TEMPLATE.md        ← draft template
│   └── EXAMPLE.md         ← draft example
└── command.md             ← draft command
```

> **Note**: `_staging/` is gitignored . draft artifacts never ship in releases.
> The staging folder is discarded after promotion.

Report what was written and where.

### Step 7: Promote (on confirmation)

Ask: "Review the packet above. When ready, I'll promote the files to
their canonical locations. Proceed? [yes/no]"

If yes, promote by copying each file from staging to its canonical path:

| Staging file | Canonical location |
|--------------|--------------------|
| `_staging/pm-skill-builder/{skill-name}/SKILL.md` | `skills/{dir-name}/SKILL.md` |
| `_staging/pm-skill-builder/{skill-name}/references/TEMPLATE.md` | `skills/{dir-name}/references/TEMPLATE.md` |
| `_staging/pm-skill-builder/{skill-name}/references/EXAMPLE.md` | `skills/{dir-name}/references/EXAMPLE.md` |
| `_staging/pm-skill-builder/{skill-name}/command.md` | `commands/{command-name}.md` |

Where `{dir-name}` is the classification-prefixed directory (e.g., `deliver-change-communication`).

Then:
1. Create the target directory: `skills/{dir-name}/references/`
2. Copy each file to its canonical location
3. Append the AGENTS.md entry from the packet
4. Run CI validation: `bash scripts/lint-skills-frontmatter.sh && bash scripts/validate-agents-md.sh && bash scripts/validate-commands.sh`
5. If validation passes, delete the staging folder: `_staging/pm-skill-builder/{skill-name}/`
6. If validation fails, report the error and keep staging intact for fixes

Design rationale lives in the GitHub issue, PR, or effort brief . not
in a permanent packet file.

Provide post-promotion guidance:
- "Run CI locally: `bash scripts/lint-skills-frontmatter.sh`"
- "Test the skill: try `/{command-name}` with a realistic scenario"
- "If contributing: create a GitHub issue with the skill-proposal template,
  then open a PR"

## Output Template

# Skill Implementation Packet: {Skill Name}

> **Created**: {date}
> **Builder version**: 1.0.0
> **Status**: Draft | Promoted | Abandoned

---

## Decision

{Recommendation: create / revise existing / workflow / command / docs-only}

{Why Gate evidence if applicable . the 2-3 specific prompts or scenarios
where existing skills fail}

---

## Classification

| Field | Value |
|-------|-------|
| Type | {domain / foundation / utility} |
| Phase | {discover / define / develop / deliver / measure / iterate / n/a} |
| Category | {specification / research / coordination / validation / reflection / ideation / problem-framing} |
| Directory | {phase/classification}-{skill-name} |
| Command | /{command-name} |

---

## Overlap Analysis

### Existing skills checked

{List of skills reviewed during gap analysis}

### Findings

{What was found . specific overlap and differentiation}

### Why this skill is still needed

{The gap this skill fills that no existing skill covers}

---

## Exemplar Skills

| Skill | Why selected |
|-------|-------------|
| {exemplar-1} | {Same phase, similar category, closest structural match} |
| {exemplar-2} | {Additional reference for a specific pattern} |

---

## Draft Frontmatter

```yaml
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
---
name: {skill-name}
description: {20-100 word description on a single line . linter reads first line only}
phase: {phase}          # for domain skills only . omit for foundation/utility
classification: {type}  # for foundation/utility only . omit for domain
version: "1.0.0"
updated: {date}
license: Apache-2.0
metadata:
  category: {category}
  frameworks: [triple-diamond]
  author: product-on-purpose
---
```

> **Linter constraint**: `description:` must be a single-line value (no `>-` or `|` folding).
> The linter extracts only the first line after the key using `sed`. Multiline YAML
> would capture the literal `>-` string and fail the 20-100 word check.

---

## Draft SKILL.md

{Full draft content . not an outline. Includes:
- Title and introductory paragraph
- When to Use section
- When NOT to Use section (if applicable)
- Instructions (numbered steps)
- Output Contract
- Quality Checklist
- Examples reference

Mirrors the section structure of the selected exemplar skill.}

---

## Draft TEMPLATE.md

{Section headers with guidance comments for each section.
Each section has:
- A ## header
- A brief instruction comment explaining what goes here
- Placeholder structure showing the expected format}

---

## Draft EXAMPLE.md

{A complete, realistic example . 150-300 lines.
- Picks a specific PM scenario appropriate to the skill's domain
- Fills every TEMPLATE.md section with concrete content
- Demonstrates optional sections both filled and skipped
- Shows what "good" looks like for ambiguous sections}

---

## Draft Command

```markdown
---
description: {One-line description of what the command does}
---

Use the `{skill-name}` skill to {primary action}.

Read the skill instructions from `skills/{directory-name}/SKILL.md` and follow them to {describe the task}.

Use `skills/{directory-name}/references/TEMPLATE.md` as the output format.

Context from user: $ARGUMENTS
```

> **Convention**: Command files use only `description:` in frontmatter. No `name`,
> `arguments`, or `skill_file` fields. The optional idea argument is handled via
> `$ARGUMENTS` in the prose body, matching all existing commands.

---

## AGENTS.md Entry

```markdown
#### {skill-name}
**Path:** `skills/{directory-name}/SKILL.md`

{1-2 sentence description. Imperative verb start, use-case focus.}

---
```

> **Convention**: Level-4 header (kebab-case skill name), `**Path:**` line,
> blank line, description paragraph, `---` separator. No `**Command:**` field.
> Must pass `validate-agents-md.sh` which checks path ↔ directory sync.

---

## Validation Checklist

### CI Validation (must pass . enforced by linter + validators)

- [ ] `name` matches directory name
- [ ] `description` is 20-100 words (single-line, no `>-`)
- [ ] `version` present (exactly one root-level, no `metadata.version`)
- [ ] `updated` present (ISO date format)
- [ ] `license` present (`Apache-2.0`)
- [ ] Phase/classification consistency (domain has `phase:`, foundation/utility has `classification:`)
- [ ] `references/TEMPLATE.md` exists with ≥3 `##` sections
- [ ] Command file references correct skill path (`validate-commands.sh`)
- [ ] AGENTS.md entry uses `#### {name}` + `**Path:**` format (`validate-agents-md.sh`)

### Quality Checks (should pass . builder-enforced, not CI-gated)

- [ ] `references/EXAMPLE.md` is a complete artifact (150-300 lines), not an outline
- [ ] Output contract present in SKILL.md
- [ ] Quality checklist present in SKILL.md
- [ ] Gap analysis checked all existing skills (not just same-phase)
- [ ] Why Gate evidence is specific (names prompts/scenarios, not vague)

---

## Next Steps

1. **Review**: Read through the packet above. Flag any sections that need changes.
2. **Local CI**: Run `bash scripts/lint-skills-frontmatter.sh` after promotion.
3. **Test**: Try using `/{command-name}` with a realistic PM scenario.
4. **Contribute**: If submitting to pm-skills, create a GitHub issue using the
   skill-proposal template, then open a PR with the promoted files.
5. **Iterate**: Use the pm-skill iteration utility (when available) to refine based on testing feedback.

## Example Output

<details>
<summary>Skill Implementation Packet: Change Communication</summary>

# Skill Implementation Packet: Change Communication

> **Created**: 2026-03-22
> **Builder version**: 1.0.0
> **Status**: Draft

---

## Decision

**Recommendation**: Create new skill.

A mid-stage SaaS company needs a repeatable way to produce change management
communications when shipping features that alter user workflows. Existing skills
cover adjacent concerns (release notes for external announcements, launch
checklists for cross-functional readiness) but nothing guides the actual
writing of internal adoption-focused communications that help users understand
what changed, why it matters, and what they need to do differently.

---

## Classification

| Field | Value |
|-------|-------|
| Type | domain |
| Phase | deliver |
| Category | coordination |
| Directory | deliver-change-communication |
| Command | /change-communication |

---

## Overlap Analysis

### Existing skills checked

All 63 skills reviewed. Closest matches:

- `deliver-release-notes` . produces external-facing release announcements
- `deliver-launch-checklist` . tracks cross-functional launch readiness
- `deliver-user-stories` . defines implementation requirements
- `discover-stakeholder-summary` . maps stakeholder needs and influence

### Findings

**deliver-release-notes**: Covers what shipped and why users should care, but
targets external audiences (changelog readers, update-notification subscribers).
Change communications target internal users, support teams, and account managers
who need to understand workflow impact and guide adoption.

**deliver-launch-checklist**: Includes "communications sent" as a line item but
does not guide what those communications should contain, how to structure them
for different audiences, or how to sequence rollout messaging.

### Why this skill is still needed

No existing skill produces the actual communication artifact . the email, Slack
message, or internal knowledge-base update that tells affected users what
changed, what they need to do differently, and where to get help. This is a
distinct coordination artifact in the Deliver phase.

---

## Exemplar Skills

| Skill | Why selected |
|-------|-------------|
| deliver-release-notes | Same phase (deliver), same category (coordination), closest artifact type . both produce written communications about product changes |
| deliver-launch-checklist | Same phase (deliver), different category . shows how to structure a multi-audience coordination artifact with checkpoints |

---

## Draft Frontmatter

```yaml
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
---
name: deliver-change-communication
description: Creates targeted change management communications for feature launches that alter user workflows. Guides audience segmentation, impact assessment, message drafting, and rollout sequencing to drive adoption and reduce support burden for SaaS product changes.
phase: deliver
version: "1.0.0"
updated: 2026-03-22
license: Apache-2.0
metadata:
  category: coordination
  frameworks: [triple-diamond]
  author: product-on-purpose
---
```

---

## Draft SKILL.md

> Representative excerpt showing all section headers with sample content.
> A full implementation would expand each section to 5-15 lines.

```markdown
# Change Communication

Change communication bridges the gap between shipping a feature and ensuring
affected users successfully adopt the new workflow.

## When to Use

- When a feature launch changes existing user workflows
- When multiple audience segments need different levels of detail
- When support teams need advance preparation for user questions

## Instructions

### Step 1: Identify the Change and Affected Audiences
Gather the feature context and segment audiences by impact level.

### Step 2: Assess Workflow Impact
Map before/after workflows for each audience segment.

### Step 3: Draft Per-Audience Messages
Write targeted communications using the template structure.

### Step 4: Plan Rollout Sequence
Determine timing and channels for each audience segment.

### Step 5: Review and Finalize
Verify completeness, tone, and accuracy with stakeholders.

## Output Contract

Use `references/TEMPLATE.md` to structure the output.

## Quality Checklist

- [ ] All affected audience segments are identified
- [ ] Before/after workflow changes are explicit
- [ ] Each message includes what changed, why, and what to do next
- [ ] Support enablement section is complete
- [ ] Rollout timing accounts for audience dependencies

## Examples

See `references/EXAMPLE.md` for a completed example.
```

---

## Draft TEMPLATE.md

> Representative excerpt with section headers and guidance comments.

```markdown
# Change Communication: {Feature Name}

## Change Summary

> Describe the feature change in 2-3 sentences. Focus on what users will
> experience differently, not technical implementation details.

## Affected Audiences

> List each audience segment with their relationship to the change.

| Audience | Impact Level | Primary Channel |
|----------|-------------|-----------------|
| {segment} | High / Medium / Low | {email / Slack / in-app / KB article} |

## Workflow Impact Assessment

> For each audience, describe the before and after states.

### {Audience Segment}

**Before**: {current workflow}
**After**: {new workflow}
**Action required**: {what they need to do differently}

## Communications

### {Audience Segment} Message

> Draft the actual message content for this audience.

**Subject**: {email subject or message headline}
**Body**: {complete message text}

## Support Enablement

> What does the support team need to know to handle questions?

## Rollout Schedule

> When does each communication go out, relative to the launch?

| Audience | Timing | Channel | Owner |
|----------|--------|---------|-------|
| {segment} | {T-N days / launch day / T+N days} | {channel} | {person} |
```

---

## Draft EXAMPLE.md

A complete example would demonstrate a change communication package for a
realistic SaaS scenario . such as migrating a dashboard reporting interface
from a legacy layout to a new design system. It would fill every template
section with concrete content: three audience segments (power users, casual
viewers, account administrators), before/after workflow descriptions, drafted
messages per audience, a support FAQ, and a rollout timeline spanning T-5
through T+3 days. Target length: 150-300 lines.

---

## Draft Command

```markdown
---
description: Create change management communications for a feature launch
---

Use the `deliver-change-communication` skill to create targeted change communications.

Read the skill instructions from `skills/deliver-change-communication/SKILL.md` and follow them to guide the user through audience segmentation, impact assessment, and message drafting.

Use `skills/deliver-change-communication/references/TEMPLATE.md` as the output format.

Context from user: $ARGUMENTS
```

---

## AGENTS.md Entry

```markdown
#### change-communication
**Path:** `skills/deliver-change-communication/SKILL.md`

Creates targeted change management communications for feature launches that alter user workflows. Use when multiple audiences need different messages about what changed, why, and what to do next.

---
```

---

## Validation Checklist

### CI Validation

- [x] `name` matches directory name (`deliver-change-communication`)
- [x] `description` is 20-100 words (single-line) . 33 words
- [x] `version` present (`"1.0.0"`)
- [x] `updated` present (`2026-03-22`)
- [x] `license` present (`Apache-2.0`)
- [x] Phase/classification: domain skill has `phase: deliver`, no `classification:` field
- [x] `references/TEMPLATE.md` has ≥3 `##` sections (6 sections)
- [x] Command file references correct path (`skills/deliver-change-communication/SKILL.md`)
- [x] AGENTS.md entry uses `#### change-communication` + `**Path:**` format

### Quality Checks

<!-- count-exempt:start -->
<!-- This block is illustrative example output captured at v2.7.0 era; the
     "27 existing skills" count is intentionally point-in-time and is not
     a current-state claim. Excluded from check-count-consistency. -->
- [x] `references/EXAMPLE.md` will be a complete artifact (150-300 lines)
- [x] Output contract present in draft SKILL.md
- [x] Quality checklist present in draft SKILL.md
- [x] Gap analysis checked all 27 existing skills
- [x] Why Gate not triggered (no high overlap . release-notes and launch-checklist serve different purposes)
<!-- count-exempt:end -->

---

## Next Steps

1. **Review**: Read through the packet above. Flag any sections that need changes.
2. **Local CI**: Run `bash scripts/lint-skills-frontmatter.sh` after promotion.
3. **Test**: Try using `/change-communication` with a realistic feature launch scenario.
4. **Contribute**: If submitting to pm-skills, create a GitHub issue using the
   skill-proposal template, then open a PR with the promoted files.
5. **Iterate**: Use the pm-skill iteration utility (when available) to refine based on testing feedback.

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . using the skill builder to create a campaign-analytics skill</summary>

**Prompt:**

```
/pm-skill-builder

Idea: A skill for defining email campaign measurement frameworks -- funnel metrics (sent > delivered > opened > clicked > converted), cohort comparison, and revenue attribution. Existing measure skills handle dashboards and event tracking but not campaign-specific analytics frameworks.
```

---

**Output:**

# Skill Implementation Packet: campaign-analytics

> **Created**: 2026-04-11
> **Builder version**: 1.0.0
> **Status**: Draft

</details>

## Quality Checklist

Before finalizing the packet, verify all items in both tiers:

### CI Validation (must pass)
- [ ] `name` matches directory name
- [ ] Description is 20-100 words (single-line, no multiline YAML)
- [ ] `version`, `updated`, `license` all present
- [ ] Classification correct (domain → `phase:`, foundation/utility → `classification:`)
- [ ] Directory name follows convention: `{phase/classification}-{skill-name}`
- [ ] TEMPLATE.md has ≥3 `##` sections
- [ ] Command file references correct skill path
- [ ] AGENTS.md entry uses `####` + `**Path:**` format

### Quality Checks (should pass)
- [ ] Gap analysis checked all existing skills (not just same-phase)
- [ ] Why Gate evidence is specific (names prompts/scenarios, not vague)
- [ ] EXAMPLE.md is a complete artifact (150-300 lines), not an outline
- [ ] Output contract is present in draft SKILL.md
- [ ] Quality checklist is present in draft SKILL.md

## Output Contract

The builder MUST produce draft files for the new skill:
- `SKILL.md` . full skill instructions
- `references/TEMPLATE.md` . output template with guidance comments
- `references/EXAMPLE.md` . complete worked example (150-300 lines)
- `command.md` . slash command file

All drafts are written to `_staging/pm-skill-builder/{skill-name}/` (gitignored).

On promotion, files are copied to canonical locations, AGENTS.md is
updated, and the staging folder is discarded.
