utility-update-pm-skills

Files (3)

• SKILL.md
• EXAMPLE.md · references/
• TEMPLATE.md · references/

SKILL.md (first lines)

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

From product-on-purpose/pm-skills, Apache-2.0.

More from product-on-purpose/pm-skills