PM Skills Updater

Try it: /pm-skills:utility-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 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)

How to Use

Invoke the skill by name (/pm-skills:utility-update-pm-skills on Claude Code, $utility-update-pm-skills on Codex):

/pm-skills:utility-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:

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

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 utility-pm-skill-validate --all to verify skill integrity
- Run local CI: bash scripts/lint-skills-frontmatter.sh
- Check release notes: {release-url}

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

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. As of v2.30.0 the ZIP also carries the agents/ sub-agent definitions and the hooks/ activation hooks, so a ZIP install has the runtime files the dispatch skills reference. 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
`agents/`	Sub-agent definitions the `utility-pm-*` dispatch skills read at runtime
`hooks/`	Activation hooks (guardrails + phase router) including `hooks.json`
`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

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.

Output Template

PM Skills Update Report

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

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

Update Summary

Field	Value
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

Check	Result
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

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

Updated Skills

Skill	What Improved	Why It Matters
{skill-name}	{What changed}	{How this benefits the user}

New Workflows

Workflow	What 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 utility-mermaid-diagrams on your next PRD”). Label speculative pairings as suggestions. Link workflows to their component skills.}

Files {Written / That Would Be Written}

Directory	Files	New	Updated
`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

Check	Result
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 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”}

Example Output

PM Skills Update Report

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

Update Summary

Field	Value
Date	2026-04-11
Local version (before)	v2.9.1
Latest version (after)	v2.10.0
Update type	minor
Version source	.claude-plugin/plugin.json
Release date	2026-04-11
Release notes	v2.10.0

Pre-Flight Results

Check	Result
Network access	PASS
Local version detected	PASS — .claude-plugin/plugin.json
Latest version fetched	PASS
Version comparison	update-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

Skill	What It Enables
utility-update-pm-skills	Check for updates, preview changes, and update your local pm-skills with `utility-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)
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

Directory	Files	New	Updated
`skills/`	32	3 (1 skill x 3 files)	29
`commands/`	39	1	38
`_workflows/`	10	0	10
Other	8	1 (guide)	7
Total	89	5	84

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

Check	Result
Version consistency	PASS — plugin.json, marketplace.json, and CHANGELOG.md all show v2.10.0
File integrity	PASS — AGENTS.md, skills/, commands/, _workflows/ all present
Skill count	31 -> 32 (+1: utility-update-pm-skills)

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

Field	Value
Date	2026-04-11
Local version (before)	v2.9.1
Latest version (after)	v2.10.0
Update type	minor
Version source	.claude-plugin/plugin.json
Release date	2026-04-11
Release notes	v2.10.0

Pre-Flight Results

Check	Result
Network access	PASS
Local version detected	PASS — .claude-plugin/plugin.json
Latest version fetched	PASS
Version comparison	update-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

Skill	What It Enables
utility-update-pm-skills	Check 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, 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

Directory	Files	New	Updated
`skills/`	32	3	29
`commands/`	39	1	38
`_workflows/`	10	0	10
Other	8	1	7
Total	89	5	84

Next Steps

Run utility-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 utility-update-pm-skills to update from v2.9.1 to v2.10.0

Prompt:

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

PM Skills Updater

When to Use

When NOT to Use

How to Use

Instructions

Step 1: Pre-Flight

Step 2: Version Comparison

Step 3: Preview

Step 4: Confirmation

Step 5: Update

Step 6: Post-Update

Flags

—status behavior

File Scope

Output Contract

FAQ

Further Reading

Output Template

PM Skills Update Report

Update Summary

Pre-Flight Results

What’s New

Headline

New Skills

Updated Skills

New Workflows

Other Changes

Opportunities

Files {Written / That Would Be Written}

Backup

Post-Update Validation

Next Steps

Example Output

PM Skills Update Report

Update Summary

Pre-Flight Results

What’s New

Headline

New Skills

Updated Skills

New Workflows

Other Changes

Opportunities

Files Written

Backup

Post-Update Validation

Next Steps

Report-Only Example

PM Skills Update Report

Update Summary

Pre-Flight Results

What’s New

Headline

New Skills

Updated Skills

New Workflows

Other Changes

Opportunities

Files That Would Be Written

Next Steps

Real-World Examples

PM Skills Update Report

Quality Checklist