/utility-update-pm-skills

name: utility-update-pm-skills
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.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.0.1"
  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 Skills Updater

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 `utility-pm-skill-builder` or `utility-pm-skill-iterate`
• To validate skills against conventions -> use `utility-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)

Flags

| Flag | Behavior | |------|----------| | *(none)* | Full update flow: pre-flight → preview → confirm → update → report | | `--report-only` | Pre-flight → preview → report (no files written) | | `--status` | Lightweight version check - prints current and latest version, then stops |

--status behavior

When `--status` is provided, run only the pre-flight checks and display:

pm-skills v{local} (installed, from {source})
pm-skills v{latest} (latest, released {date})
{Status: up to date | update available ({type})}

Run utility-update-pm-skills for details, or utility-update-pm-skills --report-only for a preview.

No report file is generated. No files are written.

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 versi