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."

1. 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.

1. 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.

Step 7: Post-Update Validation

After applying updates, run a quick health check:

1. Version consistency: Verify that .claude-plugin/plugin.json, marketplace.json, and CHANGELOG.md all reflect the new version.
2. File integrity: Confirm that key files exist:

• AGENTS.md
• skills/ directory with expected skill count
• commands/ directory
• _workflows/ directory

1. Skill count delta: Compare the number of skills before and after the update. Report any additions or removals.

If validation fails, warn the user with specific details about what looks wrong. Do not roll back automatically -- the user may want to investigate.

Step 8: Generate Update Report

Produce the update report using the template in references/TEMPLATE.md. This is the primary output artifact.

The report includes:

1. Version summary: local (before) -> latest (after), update type.
2. Files changed: every file that was updated, with a one-line summary of what changed.