Skip to content
pm-skills

PM Skills Updater

Quick facts

Classification: Utility | Version: 1.0.0 | Category: coordination | License: Apache-2.0

Try it: /update-pm-skills "Your context here"

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)

How to Use

Use the /update-pm-skills slash command:

/update-pm-skills "Your context here"

Or reference the skill file directly: skills/utility-update-pm-skills/SKILL.md

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

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

  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}

Output Template

PM Skills Update Report

Report only . update was not applied. Run /update-pm-skills to apply this update.

Update complete. pm-skills has been updated to v{latest-version}.

Update Summary

FieldValue
Date{YYYY-MM-DD}
Local version (before)v{local-version}
Latest version (after)v{latest-version}
Update type{major / minor / patch}
Version source{plugin.json / marketplace.json / CHANGELOG.md / git tag}
Release date{release-date}
Release notes{release-url}

Pre-Flight Results

CheckResult
Network access{PASS / FAIL}
Local version detected{PASS / FAIL} — {source}
Latest version fetched{PASS / FAIL}
Version comparison{up-to-date / update-available / major-update}

What’s New

Headline

{1-2 sentence narrative summarizing the update’s value. Frame in terms of what the user can now DO, not what files changed.}

New Skills

SkillWhat It Enables
{skill-name}{What this skill lets the user do — the capability, not just the description}

Updated Skills

SkillWhat ImprovedWhy It Matters
{skill-name}{What changed}{How this benefits the user}

New Workflows

WorkflowWhat It Connects
{workflow-name}{Which skills it chains and what outcome it produces}

Other Changes

  • {Change description}

Opportunities

{2-3 sentences describing what the user can now do that they couldn’t before. Ground suggestions in detected skills and workflows . reference actual new capabilities by name with their slash commands (e.g., “Try /mermaid-diagrams on your next PRD”). Label speculative pairings as suggestions. Link workflows to their component skills.}

Files {Written / That Would Be Written}

DirectoryFilesNewUpdated
skills/{n}{n new}{n updated}
commands/{n}{n new}{n updated}
_workflows/{n}{n new}{n updated}
Other{n}{n new}{n updated}
Total{n}{n new}{n updated}

Backup

{If backup was created:} Backup saved to: _pm-skills/backups/v{local-version}_{date}/

To restore: cp -r _pm-skills/backups/v{local-version}_{date}/* .

{If backup was declined:} No backup was created (user opted out).

Post-Update Validation

CheckResult
Version consistency{PASS / FAIL — detail}
File integrity{PASS / FAIL — detail}
Skill count{before} -> {after} ({+n / -n / unchanged})

Next Steps

  • Review this report for a summary of what changed
  • Run /pm-skill-validate --all to verify skill integrity
  • Run local CI: bash scripts/lint-skills-frontmatter.sh
  • Check release notes for migration steps: {release-url}
  • {For report-only: “Run /update-pm-skills to apply this update”}
  • {For completion with MCP: “Update pm-skills-mcp: cd ../pm-skills-mcp && npm run embed-skills && npm run build”}

Example Output

PM Skills Update Report

PM Skills Update Report

Update complete. pm-skills has been updated to v2.10.0.

Update Summary

FieldValue
Date2026-04-11
Local version (before)v2.9.1
Latest version (after)v2.10.0
Update typeminor
Version source.claude-plugin/plugin.json
Release date2026-04-11
Release notesv2.10.0

Pre-Flight Results

CheckResult
Network accessPASS
Local version detectedPASS — .claude-plugin/plugin.json
Latest version fetchedPASS
Version comparisonupdate-available

What’s New

Headline

This update adds a self-updater skill that lets you check for new pm-skills releases, preview what’s changed, and update your local installation . all from a single slash command. It also formally releases the mermaid diagramming and slideshow creation skills that were available since v2.9.1.

New Skills

SkillWhat It Enables
utility-update-pm-skillsCheck for updates, preview changes, and update your local pm-skills with /update-pm-skills. Supports --status for a quick version check and --report-only for a preview without writing files.

Updated Skills

No skills were updated in this release.

New Workflows

No new workflows in this update.

Other Changes

  • New CI scripts: validate-version-consistency (hard-fail), validate-gitignore-pm-skills (advisory), validate-script-docs (advisory)
  • _pm-skills/ local state directory convention (gitignored)
  • /update-pm-skills slash command with --status and --report-only flags
  • User-facing guide at docs/guides/updating-pm-skills.md

Opportunities

With /update-pm-skills --status you can quickly check whether you’re current without committing to an update. Try /update-pm-skills --report-only before updating to see exactly what files will change and what new capabilities are available. The self-updater means you no longer need to manually download releases . future updates are one command away.

Files Written

DirectoryFilesNewUpdated
skills/323 (1 skill x 3 files)29
commands/39138
_workflows/10010
Other81 (guide)7
Total89584

Backup

Backup saved to: _pm-skills/backups/v2.9.1_2026-04-11_143022/

To restore: cp -r _pm-skills/backups/v2.9.1_2026-04-11_143022/* .

Post-Update Validation

CheckResult
Version consistencyPASS — plugin.json, marketplace.json, and CHANGELOG.md all show v2.10.0
File integrityPASS — AGENTS.md, skills/, commands/, _workflows/ all present
Skill count31 -> 32 (+1: utility-update-pm-skills)

Next Steps

  • Review this report for a summary of what changed
  • Run /pm-skill-validate --all to verify skill integrity
  • Run local CI: bash scripts/lint-skills-frontmatter.sh
  • Check release notes: v2.10.0
  • Try /update-pm-skills --status to confirm you’re current

Report-Only Example

Below is what /update-pm-skills --report-only produces for the same update.

PM Skills Update Report

Report only . update was not applied. Run /update-pm-skills to apply this update.

Update Summary

FieldValue
Date2026-04-11
Local version (before)v2.9.1
Latest version (after)v2.10.0
Update typeminor
Version source.claude-plugin/plugin.json
Release date2026-04-11
Release notesv2.10.0

Pre-Flight Results

CheckResult
Network accessPASS
Local version detectedPASS — .claude-plugin/plugin.json
Latest version fetchedPASS
Version comparisonupdate-available

What’s New

Headline

This update adds a self-updater skill for keeping your pm-skills installation current, plus formally releases mermaid diagramming and slideshow creation.

New Skills

SkillWhat It Enables
utility-update-pm-skillsCheck for updates and update your local pm-skills from a single command.

Updated Skills

No skills were updated.

New Workflows

No new workflows.

Other Changes

  • 3 new CI scripts, /update-pm-skills command, user-facing update guide

Opportunities

The self-updater means future releases are one command away. Try /update-pm-skills --status anytime to check if you’re current.

Files That Would Be Written

DirectoryFilesNewUpdated
skills/32329
commands/39138
_workflows/10010
Other817
Total89584

Next Steps

  • Run /update-pm-skills to apply this update
  • Review the release notes: v2.10.0

Real-World Examples

See this skill applied to three different product contexts:

Storevine (B2B): Storevine PM running /update-pm-skills to update from v2.9.1 to v2.10.0

Prompt:

/update-pm-skills

Output:

PM Skills Update Report

Update complete. pm-skills has been updated to v2.10.0.

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

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