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, 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)

## 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 /update-pm-skills for details, or /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):

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

More from product-on-purpose/pm-skills