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

--report-only

--status

--status behavior

When

--status

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

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

   • New skills and what they enable
   • Updated skills and what improved
   • New workflows and what they connect
   • Other notable changes

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

references/TEMPLATE.md

_pm-skills/updates/update-report_v{latest}_report-only_{YYYY-MM-DD_HHMMSS}.md

Step 4: Confirmation

Prompt the user for two decisions:

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

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

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

   .

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

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

4. Clean up: Remove the temporary directory.

Step 6: Post-Update

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

2. Summary line: Show a single scannable confirmation:

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

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

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

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

build-release.sh

docs/internal/

Files included in the release ZIP (updated):

skills/

commands/

_workflows/

library/

AGENTS.md

.claude-plugin/plugin.json

marketplace.json

CHANGELOG.md

README.md

docs/

scripts/

mkdocs.yml

Files NOT in the release ZIP (never overwritten):

docs/internal/

build-release.sh

_NOTES/

_pm-skills/

.github/

CONTRIBUTING.md

LICENSE

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

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/

_pm-skills/

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}/* .

git checkout .

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

Further Reading

For a visual walkthrough and additional context, see the Updating PM Skills Guide.