---
title: "PM Skills Updater"
description: "Checks for newer pm-skills releases, compares local vs. latest version, previews what would change, and updates local files after user confirmation. Generates a structured update report documenting changed files, new capabilities, and the value delta between versions. Use when you want to bring a local pm-skills installation up to date."
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:** `/update-pm-skills "Your context here"`

This skill updates a local pm-skills installation to the latest public
release. It validates connectivity, compares versions, previews changes,
and produces a structured report documenting what was updated and what
new capabilities are available.

## When to Use

- When you want to update local pm-skills to the latest release
- When you want to check if a newer version is available
- After a new pm-skills release is announced
- When onboarding and you want to confirm you have the latest version

## When NOT to Use

- To create or edit individual skills -> use `/pm-skill-builder` or `/pm-skill-iterate`
- To validate skills against conventions -> use `/pm-skill-validate`
- If you are a maintainer working directly on the pm-skills repo (use git)
- To pin a specific older version (this skill always targets the latest release)

## How to Use

Use the `/update-pm-skills` slash command:

```
/update-pm-skills "Your context here"
```

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

## Instructions

When asked to update pm-skills (without `--status`), follow these steps:

### Step 1: Pre-Flight

Run three checks before proceeding:

1. **Network access**: Reach the GitHub API or repository URL
   (`https://github.com/product-on-purpose/pm-skills`). Use any
   available method: `curl`, `wget`, GitHub CLI (`gh`), or MCP tools.

2. **Latest version**: Query the latest release using this fallback chain
   (try each in order, use the first that succeeds):
   1. GitHub API: `GET /repos/product-on-purpose/pm-skills/releases/latest`
   2. GitHub CLI: `gh release list --repo product-on-purpose/pm-skills --limit 1`
   3. Git: `git ls-remote --tags https://github.com/product-on-purpose/pm-skills.git`

   If all three fail (rate limiting, 404, malformed response, no network),
   enter degraded mode (see below).

   Record: version string, release date, release notes URL, release notes body.

3. **Local version**: Read from the first available source:
   - `.claude-plugin/plugin.json` → `version` field
   - `marketplace.json` → `plugins[0].version` field
   - `CHANGELOG.md` → most recent version header
   - Git tags → most recent `v*` tag

   **Version parsing:** Normalize by stripping an optional `v` prefix and
   trimming whitespace. If a source is present but yields an empty,
   non-semver, or malformed string (invalid JSON, missing field), skip it
   with a warning and try the next source. Only fall back to `0.0.0`
   after all four sources fail.

**If network access fails** (degraded mode):
- Report the failure with error details.
- Provide manual update instructions:
  > Visit https://github.com/product-on-purpose/pm-skills/releases to
  > download the latest release. Extract the archive and copy the
  > `skills/`, `commands/`, `_workflows/`, and other content directories
  > to your local pm-skills installation.
- Stop execution.

### Step 2: Version Comparison

Compare the local version against the latest release using semver.

**If local version >= latest version:**
- Report: "Your pm-skills installation is up to date (v{local})."
- Offer to generate a report-only anyway.
- Stop execution.

**If local version < latest version:**
- Show the version delta:
  ```
  Local version:  v{local}
  Latest version: v{latest}
  Update type:    {major | minor | patch}
  ```
- **Major version warning**: If the update is a major bump (e.g., v2.x
  to v3.x), show a prominent warning:
  > This is a major version update. It may include breaking changes to
  > skill contracts. Review the release notes before proceeding.
- Continue to Step 3.

### Step 3: Preview

Show the user what the update includes:

1. **Version delta**: local version, latest version, update type.

2. **Value summary**: Derive from CHANGELOG entries between the two
   versions, GitHub release notes, and directory diffs (new skills/,
   new _workflows/ files):
   - New skills and what they enable
   - Updated skills and what improved
   - New workflows and what they connect
   - Other notable changes

3. **File manifest**: List of files and folders that will be written,
   grouped by directory with counts:
   ```
   Files to be written:
     skills/       31 files (2 new, 29 updated)
     commands/     38 files (2 new, 36 updated)
     _workflows/    9 files (1 new, 8 updated)
     other          7 files
     Total:        85 files
   ```

**If `--report-only`:** Generate the report using `references/TEMPLATE.md`
with the banner "Report only . update was not applied." Save to
`_pm-skills/updates/update-report_v{latest}_report-only_{YYYY-MM-DD_HHMMSS}.md`. Stop
execution.

### Step 4: Confirmation

Prompt the user for two decisions:

1. **Update confirmation**:
   "These files will be overwritten. Proceed? [yes / no]"
   - If major version bump: require typing "yes" explicitly.
   - If the user declines: save a report-only and stop.

2. **Backup offer**:
   "Create a backup of current files before updating?
   [yes (recommended) / no]"
   - If yes: copy all in-scope files to
     `_pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/`
   - Create the `_pm-skills/` directory if it doesn't exist.

### Step 5: Update

Execute the update using validated-before-copy with backup:

1. **Download**: Fetch the release ZIP asset (`pm-skills-vX.Y.Z.zip`)
   from the GitHub Release page to a temporary directory. This is the
   curated build artifact produced by `build-release.sh` . it includes
   only user-facing content and excludes `docs/internal/`.

2. **Validate**: Confirm the extracted archive contains `skills/`,
   `commands/`, `AGENTS.md`, and `.claude-plugin/plugin.json`. If
   validation fails, report the error and stop without writing any files.

3. **Copy**: Overwrite in-scope files from the extracted archive to the
   install root. Show progress per directory:
   ```
   Updating pm-skills v2.9.0 -> v2.10.0...
     skills/       31/31 ████████████████████  done
     commands/     38/38 ████████████████████  done
     _workflows/    9/9  ████████████████████  done
     other files    7/7  ████████████████████  done
   ```

4. **Clean up**: Remove the temporary directory.

### Step 6: Post-Update

1. **Smoke test**:
   - Version consistency: `plugin.json`, `marketplace.json`, and
     `CHANGELOG.md` all reflect the new version. (Note: version detection
     in Step 1 uses first-match; the smoke test verifies all sources
     agree. A mismatch here suggests a release packaging issue.)
   - File integrity: `AGENTS.md`, `skills/`, `commands/`, `_workflows/`
     all exist.
   - Skill count delta: count skills before and after, report the change.
   - If any check fails: warn the user with specific details. Do NOT
     auto-rollback. Provide recovery guidance:
     - **Version mismatch**: "Run the update again, or manually edit
       {file} to set the version to {expected}."
     - **Missing files**: "Re-run `/update-pm-skills` to re-download,
       or restore from backup: `cp -r _pm-skills/backups/{dir}/* .`"
     - **If backup exists**: Always remind the user of the backup
       location and restore command.

2. **Summary line**: Show a single scannable confirmation:
   ```
   Updated v{old} -> v{new} | +{n} skills, +{n} workflows | Report: _pm-skills/updates/{file}
   ```

3. **Completion report**: Generate using `references/TEMPLATE.md` and
   save to `_pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md`

4. **MCP advisory**: If `../pm-skills-mcp/` exists, try to read
   `pm-skills-source.json`. If the file is missing or malformed, show:
   "pm-skills-mcp detected but pm-skills-source.json not found or
   unreadable. Check the MCP repo manually." If readable, show:
   ```
   pm-skills-mcp detected at ../pm-skills-mcp/
     Embedded skills version: v{embedded}
     Updated pm-skills version: v{new}

     To update the MCP server's embedded skills:
       cd ../pm-skills-mcp && npm run embed-skills && npm run build
   ```

5. **Next steps**:
   ```
   Next Steps:
   - Review the update report at _pm-skills/updates/{report-file}
   - Run /pm-skill-validate --all to verify skill integrity
   - Run local CI: bash scripts/lint-skills-frontmatter.sh
   - Check release notes: {release-url}
   ```

## Output Template

# PM Skills Update Report

<!-- MODE BANNER (choose one, delete the other) -->

<!-- For report-only mode, include this banner: -->
> **Report only . update was not applied.**
> Run `/update-pm-skills` to apply this update.

<!-- For completion mode, include this banner: -->
> **Update complete.** pm-skills has been updated to v{latest-version}.

---

## Update Summary

| Field | Value |
|-------|-------|
| Date | {YYYY-MM-DD} |
| Local version (before) | v{local-version} |
| Latest version (after) | v{latest-version} |
| Update type | {major / minor / patch} |
| Version source | {plugin.json / marketplace.json / CHANGELOG.md / git tag} |
| Release date | {release-date} |
| Release notes | [{release-url}]({release-url}) |

## Pre-Flight Results

| Check | Result |
|-------|--------|
| Network access | {PASS / FAIL} |
| Local version detected | {PASS / FAIL} -- {source} |
| Latest version fetched | {PASS / FAIL} |
| Version comparison | {up-to-date / update-available / major-update} |

## What's New

<!-- This is the centerpiece of the report. Tell the value story. -->

### Headline

{1-2 sentence narrative summarizing the update's value. Frame in terms of
what the user can now DO, not what files changed.}

<!-- Example: "This update adds meeting synthesis and slideshow creation,
expanding pm-skills from a planning toolkit into a presentation and
communication platform." -->

### New Skills

<!-- If no new skills: "No new skills in this update." -->

| Skill | What It Enables |
|-------|-----------------|
| {skill-name} | {What this skill lets the user do -- the capability, not just the description} |

### Updated Skills

<!-- If no updated skills: "No skills were updated." -->

| Skill | What Improved | Why It Matters |
|-------|---------------|----------------|
| {skill-name} | {What changed} | {How this benefits the user} |

### New Workflows

<!-- If no new workflows: "No new workflows in this update." -->

| Workflow | What It Connects |
|----------|-----------------|
| {workflow-name} | {Which skills it chains and what outcome it produces} |

### Other Changes

<!-- Bullet list of notable changes. If none: "No other notable changes." -->

- {Change description}

### Opportunities

{2-3 sentences describing what the user can now do that they couldn't before.
Ground suggestions in detected skills and workflows . reference actual new
capabilities by name with their slash commands (e.g., "Try `/mermaid-diagrams`
on your next PRD"). Label speculative pairings as suggestions. Link workflows
to their component skills.}

<!-- Example: "With the new `/slideshow-creator` skill, you can now go from a
PRD directly to a stakeholder presentation without leaving Claude. Try
pairing it with `/persona` to create audience-tailored decks. The new
discover-to-present workflow chains `/interview-synthesis` → `/problem-statement`
→ `/solution-brief` → `/slideshow-creator` into a single flow." -->

## Files {Written / That Would Be Written}

<!-- Use "Files Written" for completion reports, "Files That Would Be Written"
     for report-only. -->

| Directory | Files | New | Updated |
|-----------|-------|-----|---------|
| `skills/` | {n} | {n new} | {n updated} |
| `commands/` | {n} | {n new} | {n updated} |
| `_workflows/` | {n} | {n new} | {n updated} |
| Other | {n} | {n new} | {n updated} |
| **Total** | **{n}** | **{n new}** | **{n updated}** |

## Backup

<!-- Completion reports only. For report-only: delete this section. -->

{If backup was created:}
Backup saved to: `_pm-skills/backups/v{local-version}_{date}/`

To restore: `cp -r _pm-skills/backups/v{local-version}_{date}/* .`

{If backup was declined:}
No backup was created (user opted out).

## Post-Update Validation

<!-- Completion reports only. For report-only: delete this section. -->

| Check | Result |
|-------|--------|
| Version consistency | {PASS / FAIL -- detail} |
| File integrity | {PASS / FAIL -- detail} |
| Skill count | {before} -> {after} ({+n / -n / unchanged}) |

## Next Steps

<!-- Adjust based on report mode and results. -->

- Review this report for a summary of what changed
- Run `/pm-skill-validate --all` to verify skill integrity
- Run local CI: `bash scripts/lint-skills-frontmatter.sh`
- Check release notes for migration steps: {release-url}
- {For report-only: "Run `/update-pm-skills` to apply this update"}
- {For completion with MCP: "Update pm-skills-mcp: `cd ../pm-skills-mcp && npm run embed-skills && npm run build`"}

## Example Output

<details>
<summary>PM Skills Update Report</summary>

# PM Skills Update Report

> **Update complete.** pm-skills has been updated to v2.10.0.

---

## Update Summary

| Field | Value |
|-------|-------|
| Date | 2026-04-11 |
| Local version (before) | v2.9.1 |
| Latest version (after) | v2.10.0 |
| Update type | minor |
| Version source | .claude-plugin/plugin.json |
| Release date | 2026-04-11 |
| Release notes | [v2.10.0](https://github.com/product-on-purpose/pm-skills/releases/tag/v2.10.0) |

## Pre-Flight Results

| Check | Result |
|-------|--------|
| Network access | PASS |
| Local version detected | PASS -- .claude-plugin/plugin.json |
| Latest version fetched | PASS |
| Version comparison | update-available |

## What's New

### Headline

This update adds a self-updater skill that lets you check for new
pm-skills releases, preview what's changed, and update your local
installation . all from a single slash command. It also formally
releases the mermaid diagramming and slideshow creation skills that
were available since v2.9.1.

### New Skills

| Skill | What It Enables |
|-------|-----------------|
| utility-update-pm-skills | Check for updates, preview changes, and update your local pm-skills with `/update-pm-skills`. Supports `--status` for a quick version check and `--report-only` for a preview without writing files. |

### Updated Skills

No skills were updated in this release.

### New Workflows

No new workflows in this update.

### Other Changes

- New CI scripts: `validate-version-consistency` (hard-fail), `validate-gitignore-pm-skills` (advisory), `validate-script-docs` (advisory)
- `_pm-skills/` local state directory convention (gitignored)
- `/update-pm-skills` slash command with `--status` and `--report-only` flags
- User-facing guide at `docs/guides/updating-pm-skills.md`

### Opportunities

With `/update-pm-skills --status` you can quickly check whether you're
current without committing to an update. Try `/update-pm-skills --report-only`
before updating to see exactly what files will change and what new
capabilities are available. The self-updater means you no longer need to
manually download releases . future updates are one command away.

## Files Written

| Directory | Files | New | Updated |
|-----------|-------|-----|---------|
| `skills/` | 32 | 3 (1 skill x 3 files) | 29 |
| `commands/` | 39 | 1 | 38 |
| `_workflows/` | 10 | 0 | 10 |
| Other | 8 | 1 (guide) | 7 |
| **Total** | **89** | **5** | **84** |

## Backup

Backup saved to: `_pm-skills/backups/v2.9.1_2026-04-11_143022/`

To restore: `cp -r _pm-skills/backups/v2.9.1_2026-04-11_143022/* .`

## Post-Update Validation

| Check | Result |
|-------|--------|
| Version consistency | PASS -- plugin.json, marketplace.json, and CHANGELOG.md all show v2.10.0 |
| File integrity | PASS -- AGENTS.md, skills/, commands/, _workflows/ all present |
| Skill count | 31 -> 32 (+1: utility-update-pm-skills) |

## Next Steps

- Review this report for a summary of what changed
- Run `/pm-skill-validate --all` to verify skill integrity
- Run local CI: `bash scripts/lint-skills-frontmatter.sh`
- Check release notes: [v2.10.0](https://github.com/product-on-purpose/pm-skills/releases/tag/v2.10.0)
- Try `/update-pm-skills --status` to confirm you're current

---

# Report-Only Example

Below is what `/update-pm-skills --report-only` produces for the same update.

---

# PM Skills Update Report

> **Report only . update was not applied.**
> Run `/update-pm-skills` to apply this update.

---

## Update Summary

| Field | Value |
|-------|-------|
| Date | 2026-04-11 |
| Local version (before) | v2.9.1 |
| Latest version (after) | v2.10.0 |
| Update type | minor |
| Version source | .claude-plugin/plugin.json |
| Release date | 2026-04-11 |
| Release notes | [v2.10.0](https://github.com/product-on-purpose/pm-skills/releases/tag/v2.10.0) |

## Pre-Flight Results

| Check | Result |
|-------|--------|
| Network access | PASS |
| Local version detected | PASS -- .claude-plugin/plugin.json |
| Latest version fetched | PASS |
| Version comparison | update-available |

## What's New

### Headline

This update adds a self-updater skill for keeping your pm-skills
installation current, plus formally releases mermaid diagramming and
slideshow creation.

### New Skills

| Skill | What It Enables |
|-------|-----------------|
| utility-update-pm-skills | Check for updates and update your local pm-skills from a single command. |

### Updated Skills

No skills were updated.

### New Workflows

No new workflows.

### Other Changes

- 3 new CI scripts, `/update-pm-skills` command, user-facing update guide

### Opportunities

The self-updater means future releases are one command away. Try
`/update-pm-skills --status` anytime to check if you're current.

## Files That Would Be Written

| Directory | Files | New | Updated |
|-----------|-------|-----|---------|
| `skills/` | 32 | 3 | 29 |
| `commands/` | 39 | 1 | 38 |
| `_workflows/` | 10 | 0 | 10 |
| Other | 8 | 1 | 7 |
| **Total** | **89** | **5** | **84** |

## Next Steps

- Run `/update-pm-skills` to apply this update
- Review the release notes: [v2.10.0](https://github.com/product-on-purpose/pm-skills/releases/tag/v2.10.0)

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine PM running /update-pm-skills to update from v2.9.1 to v2.10.0</summary>

**Prompt:**

```
/update-pm-skills
```

---

**Output:**

# PM Skills Update Report

> **Update complete.** pm-skills has been updated to v2.10.0.

---

</details>

## Quality Checklist

Before marking the update complete, verify:

- [ ] Pre-flight passed: network, versions detected
- [ ] User was shown preview before any files were written
- [ ] User explicitly confirmed before update proceeded
- [ ] Backup was offered (and created if accepted)
- [ ] Archive was downloaded to temp and validated before copying
- [ ] All in-scope files were written successfully
- [ ] Version consistency: plugin.json, marketplace.json, CHANGELOG match
- [ ] File integrity: AGENTS.md, skills/, commands/, _workflows/ exist
- [ ] Skill count delta is reported (before -> after)
- [ ] Report was generated and saved to `_pm-skills/updates/`
- [ ] MCP advisory was shown if sibling repo detected
- [ ] Next steps were presented
- [ ] Summary line displayed

## Output Contract

The skill MUST:
- Validate network access before any remote operations
- Show a preview before writing any files
- Require explicit user confirmation before overwriting
- Offer a backup before overwriting
- Use validated-before-copy (download to temp, validate, then copy; backup is the recovery path for mid-copy failures)
- Generate a report in both modes (report-only and completion)
- Run the post-update smoke test
- Show MCP advisory if sibling repo is detected

The skill MUST NOT:
- Write files without user confirmation
- Proceed without network access confirmation
- Modify files outside the pm-skills directory
- Modify `docs/internal/`, `_NOTES/`, or `_pm-skills/` with upstream content
- Auto-rollback on smoke test failure (inform the user instead)
- Delete local files that don't exist in the upstream release
