Utility Update Pm Skills

<!-- 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 utility-pm-skill-builder or utility-pm-skill-iterate
• To validate skills against conventions -> use utility-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

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

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

Files NOT in the release ZIP (never overwritten):

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 or 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 utility-update-pm-skills to retry.

Further Reading

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

PM Skills Update Report

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

---

Update Summary

Pre-Flight Results

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

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)
• utility-update-pm-skills slash command with --status and --report-only flags
• User-facing guide at docs/guides/updating-pm-skills.md

Opportunities

With utility-update-pm-skills --status you can quickly check whether you're current without committing to an update. Try utility-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

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

Next Steps

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

---

Report-Only Example

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

---

PM Skills Update Report

Report only - update was not applied.

Run utility-update-pm-skills to apply this update.

---

Update Summary

Pre-Flight Results

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

Updated Skills

No skills were updated.

New Workflows

No new workflows.

Other Changes

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

Opportunities

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

Files That Would Be Written

Next Steps

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

PM Skills Update Report

<!-- MODE BANNER (choose one, delete the other) -->

<!-- For report-only mode, include this banner: -->

Report only - update was not applied.

Run utility-update-pm-skills to apply this update.

<!-- For completion mode, include this banner: -->

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

---

Update Summary

Pre-Flight Results

What's New

<!-- This is the centerpiece of the report. Tell the value story. -->

Headline

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

<!-- Example: "This update adds meeting synthesis and slideshow creation, expanding pm-skills from a planning toolkit into a presentation and communication platform." -->

New Skills

<!-- If no new skills: "No new skills in this update." -->

Updated Skills

<!-- If no updated skills: "No skills were updated." -->

New Workflows

<!-- If no new workflows: "No new workflows in this update." -->

Other Changes

<!-- Bullet list of notable changes. If none: "No other notable 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 utility-mermaid-diagrams on your next PRD"). Label speculative pairings as suggestions. Link workflows to their component skills.}

<!-- Example: "With the new utility-slideshow-creator skill, you can now go from a PRD directly to a stakeholder presentation without leaving Claude. Try pairing it with foundation-persona to create audience-tailored decks. The new discover-to-present workflow chains discover-interview-synthesis → define-problem-statement → develop-solution-brief → utility-slideshow-creator into a single flow." -->

Files {Written / That Would Be Written}

<!-- Use "Files Written" for completion reports, "Files That Would Be Written" for report-only. -->

Backup

<!-- Completion reports only. For report-only: delete this section. -->

{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

<!-- Completion reports only. For report-only: delete this section. -->

Next Steps

<!-- Adjust based on report mode and results. -->

• Review this report for a summary of what changed
• Run utility-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 utility-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"}