From pm-skills
Updates local pm-skills installation: checks for latest release via GitHub API/git, previews changes, confirms, applies updates, generates report on files changed and new capabilities. Use to stay current.
npx claudepluginhub product-on-purpose/pm-skillsThis skill uses the workspace's default tool permissions.
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Applies targeted improvements to existing pm-skills skills from feedback, validation reports, or convention changes. Previews file diffs, writes on confirmation, suggests version bump.
Manages skill updates by checking upstream sources for new versions via mise commands, auditing staleness, generating reports, and bootstrapping sources.toml tracking.
Checks skills-for-fabric marketplace updates weekly via persistent state, compares local package.json version against GitHub releases, shows changelog if available.
Share bugs, ideas, or general feedback.
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.
/pm-skill-builder or /pm-skill-iterate/pm-skill-validate| 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 |
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.
When asked to update pm-skills (without --status), follow these steps:
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):
GET /repos/product-on-purpose/pm-skills/releases/latestgh release list --repo product-on-purpose/pm-skills --limit 1git ls-remote --tags https://github.com/product-on-purpose/pm-skills.gitIf 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 fieldmarketplace.json → plugins[0].version fieldCHANGELOG.md → most recent version headerv* tagVersion 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):
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.
Compare the local version against the latest release using semver.
If local version >= latest version:
If local version < latest version:
Local version: v{local}
Latest version: v{latest}
Update type: {major | minor | patch}
This is a major version update. It may include breaking changes to skill contracts. Review the release notes before proceeding.
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):
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.
Prompt the user for two decisions:
Update confirmation: "These files will be overwritten. Proceed? [yes / no]"
Backup offer: "Create a backup of current files before updating? [yes (recommended) / no]"
_pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/_pm-skills/ directory if it doesn't exist.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.
Smoke test:
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.)AGENTS.md, skills/, commands/, _workflows/
all exist./update-pm-skills to re-download,
or restore from backup: cp -r _pm-skills/backups/{dir}/* ."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}
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) |
The skill MUST:
The skill MUST NOT:
docs/internal/, _NOTES/, or _pm-skills/ with upstream contentBefore marking the update complete, verify:
_pm-skills/updates/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 /update-pm-skills to retry.
For a visual walkthrough and additional context, see the Updating PM Skills Guide.