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:

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

Version delta: local version, latest version, update type.
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

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:

Update confirmation: "These files will be overwritten. Proceed? [yes / no]"
- If major version bump: require typing "yes" explicitly.
- If the user declines: save a report-only and stop.
Backup offer: "Create a backup of current files before updating? [yes (recommended) / no]"
- If yes: copy all in-scope files to
```
_pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/
```
- Create the
```
_pm-skills/
```
  directory if it doesn't exist.

Step 5: Update

Execute the update using validated-before-copy with backup:

Download: Fetch the release ZIP asset (
```
pm-skills-vX.Y.Z.zip
```
) from the GitHub Release page to a temporary directory. This is the curated build artifact produced by
```
build-release.sh
```
. it includes only user-facing content and excludes
```
docs/internal/
```
.
Validate: Confirm the extracted archive contains
```
skills/
```
,
```
commands/
```
,
```
AGENTS.md
```
, and
```
.claude-plugin/plugin.json
```
. If validation fails, report the error and stop without writing any files.

Copy: Overwrite in-scope files from the extracted archive to the install root. Show progress per directory:

Updating pm-skills v2.9.0 -> v2.10.0...
  skills/       31/31 ████████████████████  done
  commands/     38/38 ████████████████████  done
  _workflows/    9/9  ████████████████████  done
  other files    7/7  ████████████████████  done

Clean up: Remove the temporary directory.

Step 6: Post-Update

Smoke test:
- Version consistency:
```
plugin.json
```
  ,
```
marketplace.json
```
  , and
```
CHANGELOG.md
```
  all reflect the new version. (Note: version detection in Step 1 uses first-match; the smoke test verifies all sources agree. A mismatch here suggests a release packaging issue.)
- File integrity:
```
AGENTS.md
```
  ,
```
skills/
```
  ,
```
commands/
```
  ,
```
_workflows/
```
  all exist.
- Skill count delta: count skills before and after, report the change.
- If any check fails: warn the user with specific details. Do NOT auto-rollback. Provide recovery guidance:
  - Version mismatch: "Run the update again, or manually edit {file} to set the version to {expected}."
  - Missing files: "Re-run
    /update-pm-skills
    to re-download, or restore from backup:
    cp -r _pm-skills/backups/{dir}/* .
    "
  - If backup exists: Always remind the user of the backup location and restore command.

Summary line: Show a single scannable confirmation:

Updated v{old} -> v{new} | +{n} skills, +{n} workflows | Report: _pm-skills/updates/{file}

Completion report: Generate using

references/TEMPLATE.md

and save to

_pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md

MCP advisory: If

../pm-skills-mcp/

exists, try to read

pm-skills-source.json

. If the file is missing or malformed, show: "pm-skills-mcp detected but pm-skills-source.json not found or unreadable. Check the MCP repo manually." If readable, show:

pm-skills-mcp detected at ../pm-skills-mcp/
  Embedded skills version: v{embedded}
  Updated pm-skills version: v{new}

  To update the MCP server's embedded skills:
    cd ../pm-skills-mcp && npm run embed-skills && npm run build

Next steps:

Next Steps:
- Review the update report at _pm-skills/updates/{report-file}
- Run /pm-skill-validate --all to verify skill integrity
- Run local CI: bash scripts/lint-skills-frontmatter.sh
- Check release notes: {release-url}

File Scope

The updater writes only files present in the release ZIP asset (

pm-skills-vX.Y.Z.zip

), which is the curated build produced by

build-release.sh

. The ZIP excludes

docs/internal/

and other non-user-facing content . no exclusion logic is needed at copy time.

Files included in the release ZIP (updated):

Path	Rationale
`skills/`	Core skill files
`commands/`	Slash command definitions
`_workflows/`	Workflow chains
`library/`	Sample library and skill output samples (note: user-added samples may be overwritten)
`AGENTS.md`	Skill discovery for IDEs
`.claude-plugin/plugin.json`	Version + plugin metadata
`marketplace.json`	Marketplace metadata
`CHANGELOG.md`	Release history
`README.md`	Public docs
`docs/` (public guides, reference, workflows)	User-facing documentation
`scripts/`	CI/validation scripts
`mkdocs.yml`	Docs site config

Files NOT in the release ZIP (never overwritten):

Path	Rationale
`docs/internal/`	Excluded from ZIP by `build-release.sh`
`_NOTES/`	Local-only, gitignored, not in ZIP
`_pm-skills/`	Local state (reports, backups), not in ZIP
`.github/`	CI workflows, not in ZIP
`CONTRIBUTING.md` , `LICENSE`	Not in ZIP (repo-level files)

Output Contract

The skill MUST:

Validate network access before any remote operations
Show a preview before writing any files
Require explicit user confirmation before overwriting
Offer a backup before overwriting
Use validated-before-copy (download to temp, validate, then copy; backup is the recovery path for mid-copy failures)
Generate a report in both modes (report-only and completion)
Run the post-update smoke test
Show MCP advisory if sibling repo is detected

The skill MUST NOT:

Write files without user confirmation
Proceed without network access confirmation
Modify files outside the pm-skills directory
Modify
```
docs/internal/
```
,
```
_NOTES/
```
, or
```
_pm-skills/
```
with upstream content
Auto-rollback on smoke test failure (inform the user instead)
Delete local files that don't exist in the upstream release

Quality Checklist

Before marking the update complete, verify:

Pre-flight passed: network, versions detected
User was shown preview before any files were written
User explicitly confirmed before update proceeded
Backup was offered (and created if accepted)
Archive was downloaded to temp and validated before copying
All in-scope files were written successfully
Version consistency: plugin.json, marketplace.json, CHANGELOG match
File integrity: AGENTS.md, skills/, commands/, _workflows/ exist
Skill count delta is reported (before -> after)
Report was generated and saved to
```
_pm-skills/updates/
```
MCP advisory was shown if sibling repo detected
Next steps were presented
Summary line displayed

FAQ

I'm a contributor who cloned the repo. Should I use this skill? No. Use

git pull

git fetch && git merge

instead. This skill is for end users who installed pm-skills as a plugin or downloaded a release.

Can I update to a specific version instead of the latest? Not in v1. This skill always targets the latest release. To install a specific version, download it manually from the releases page.

What happens to my local notes and planning docs? They are never touched. The skill explicitly excludes

docs/internal/

_NOTES/

, and

_pm-skills/

from updates. See the File Scope table.

What happens to files I added that aren't in the upstream release? They are left untouched. The skill only overwrites files that exist in the new release . it never deletes local files.

How do I undo an update? If you created a backup (the default offer), restore it:

cp -r _pm-skills/backups/v{version}_{timestamp}/* .

If you didn't create a backup but have git, use

git checkout .

to restore tracked files to their last committed state.

The update failed partway through. What do I do? The skill validates before copying (download to temp, check, then write), so partial failures are rare. If it does happen: restore from backup if available, or re-run

/update-pm-skills

to retry.

utility-update-pm-skills

NPX Install

Tags

SKILL.md Content