Utility Update Pm Skills

<!-- 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, detects local modifications, gives the user control over conflict resolution, and produces a structured update report documenting every change.

The updater operates in three phases:

• Pre-flight -- validate internet access and determine version delta.
• Update -- fetch the latest release and apply changes with conflict-aware overwrite-or-skip logic.
• Report -- generate a markdown report summarizing what changed, what was skipped, and what new capabilities are available.

When to Use

• When you want to update your local pm-skills to the latest release
• After a new pm-skills version is announced and you want to pull it in
• When you're unsure whether your local copy is current
• When onboarding to a team that uses pm-skills and you want the latest version
• When you want a structured summary of what changed between your version and the latest

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 instead)
• If you need to pin a specific older version (this skill always targets the latest release)

Instructions

When asked to update pm-skills, follow these steps:

Step 1: Validate Internet Access

Before attempting any remote operations, confirm connectivity to GitHub.

How to validate:

1. Attempt to reach the GitHub API or the public repository URL: https://github.com/product-on-purpose/pm-skills
2. Use any available method: curl, wget, fetch, GitHub CLI (gh), or the GitHub MCP tools.

If connectivity fails:

• Report the failure clearly with the error details.
• Suggest troubleshooting steps: check network, proxy settings, VPN, or firewall rules.
• Stop execution. Do not proceed to Step 2.

If connectivity succeeds:

• Report: "Internet access validated. Connected to GitHub."
• Proceed to Step 2.

Step 2: Determine Local Version

Read the local version from these sources (in priority order):

1. .claude-plugin/plugin.json -- version field
2. marketplace.json -- plugins[0].version field
3. CHANGELOG.md -- most recent version header
4. Git tags -- most recent v* tag

Record:

• Local version: the version string (e.g., 2.8.2)
• Local version source: which file provided the version

If no version can be determined, warn the user and default to 0.0.0 (treat as a fresh install requiring full update).

Step 3: Fetch Latest Public Release

Query the public repository for the latest release:

Methods (try in order):

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

Record:

• Latest version: the version string from the latest release
• Release date: when the release was published
• Release notes URL: link to the release page
• Release notes body: the release description (for capability diff in Step 8)

Step 4: Compare Versions

Compare the local version against the latest public version.

If local version >= latest version:

• Report: "Your pm-skills installation is up to date (v{local})."
• Offer to generate a version report anyway (skip to Step 8 with no changes to report).
• Stop execution unless the user requests a forced update.

If local version < latest version:

• Report the version delta:

  Local version:  v{local}
  Latest version: v{latest}
  Update type:    {major | minor | patch}

• If the update is a major version bump, warn: "This is a major version update. It may include breaking changes to skill contracts. Review the release notes before proceeding."
• Ask: "Proceed with update? [yes / no]"
• If no, stop execution.

Step 5: Scan for Local Modifications

Before fetching new files, scan the local installation for user modifications. This protects customizations from being silently overwritten.

How to detect modifications:

1. If the local install is a git repo (preferred):

   • Run git status --porcelain to find uncommitted changes.
   • Run git diff HEAD to see the actual modifications.
   • Any file with local changes is flagged as "locally modified."

2. If the local install is NOT a git repo (downloaded release):

   • Compare file checksums (SHA-256) against a manifest if available.
   • If no manifest is available, skip modification detection and note this limitation in the report.

Record a list of locally modified files with their modification type:

• modified -- content differs from the installed version
• added -- file exists locally but not in the original release
• deleted -- file was removed locally

Present the findings:

Locally modified files detected: {n}
- {status} | {file-path}
- {status} | {file-path}
...

If no modifications are detected, report: "No local modifications detected. Safe to update all files."

Step 6: Fetch and Apply Updates

Fetch the latest release content and apply updates file by file.

Update method (try in order):

1. Git pull/merge (if local is a git repo):

   • git fetch origin
   • git merge origin/main (or the tagged release)
   • If merge conflicts arise, handle per the conflict resolution rules below.

2. Release archive download (if not a git repo):

   • Download the release archive (.tar.gz or .zip).
   • Extract to a temporary directory.
   • Copy files to the local installation per the rules below.

File-by-file application rules:

For each file in the update:

Conflict resolution options:

• overwrite: Replace the local file with the upstream version. The original is backed up to {path}.local-backup before overwriting.
• skip: Keep the local version. Record as skipped in the report.
• diff: Show a side-by-side or unified diff of the local vs. upstream version, then re-prompt with [overwrite / skip].
• restore: Add the file back from the upstream version.
• overwrite-all: Apply overwrite to all remaining conflicts without further prompting.
• skip-all: Apply skip to all remaining conflicts without further prompting.