utility-update-pm-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PM Skills Updater

PM Skills 更新工具

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-skills安装版本更新至最新公开版本。它会验证网络连接、对比版本、预览变更，并生成结构化报告记录更新内容和新增功能。

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

当你想要将本地pm-skills更新至最新版本时
当你想要检查是否有可用新版本时
在pm-skills发布新版本后
入职时确认自己是否安装了最新版本

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)

创建或编辑单个技能 → 使用
```
/pm-skill-builder
```
或
```
/pm-skill-iterate
```
验证技能是否符合规范 → 使用
```
/pm-skill-validate
```
如果你是直接维护pm-skills仓库的开发者（使用git操作）
固定使用特定旧版本（此工具始终以最新版本为目标）

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

参数	行为
(无)	完整更新流程：预检 → 预览 → 确认 → 更新 → 生成报告
`--report-only`	预检 → 预览 → 生成报告（不写入文件）
`--status`	轻量版本检查：显示当前版本和最新版本后停止

--status behavior

--status 行为

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.

当使用

--status

参数时，仅运行预检并显示：

pm-skills v{local} (已安装，来源 {source})
pm-skills v{latest} (最新版本，发布于 {date})
{状态：已更新至最新版本 | 有可用更新（{类型}）}

运行 /update-pm-skills 获取详情，或运行 /update-pm-skills --report-only 预览更新内容。

不会生成报告文件，也不会写入任何文件。

Instructions

操作步骤

When asked to update pm-skills (without

--status

), follow these steps:

当要求更新pm-skills（不使用

--status

参数）时，请遵循以下步骤：

Step 1: Pre-Flight

步骤1：预检

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.

在继续前运行三项检查：

网络访问：连接GitHub API或仓库URL (
```
https://github.com/product-on-purpose/pm-skills
```
)。可使用任意可用方法：
```
curl
```
、
```
wget
```
、GitHub CLI (
```
gh
```
)或MCP工具。
获取最新版本：通过以下优先级链查询最新版本（按顺序尝试，使用第一个成功的方法）：
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
```
如果三种方法全部失败（请求受限、404错误、响应格式错误、无网络），进入降级模式（见下文）。

记录：版本字符串、发布日期、发布说明URL、发布说明内容。
获取本地版本：从以下优先级来源读取：
- ```
.claude-plugin/plugin.json
```
  →
```
version
```
  字段
- ```
marketplace.json
```
  →
```
plugins[0].version
```
  字段
- ```
CHANGELOG.md
```
  → 最近的版本标题
- Git标签 → 最近的
```
v*
```
  标签
版本解析规则：去除可选的
```
v
```
前缀并修剪空白字符以统一格式。如果来源存在但返回空值、非语义化版本或格式错误的字符串（JSON无效、字段缺失），则跳过该来源并发出警告，尝试下一个来源。仅当四个来源全部失败时，才回退到
```
0.0.0
```
。

如果网络访问失败（降级模式）：

报告失败及错误详情。
提供手动更新说明：
访问 https://github.com/product-on-purpose/pm-skills/releases 下载最新版本。解压归档文件，将
```
skills/
```
、
```
commands/
```
、
```
_workflows/
```
及其他内容目录复制到本地pm-skills安装目录。
停止执行。

Step 2: Version Comparison

步骤2：版本对比

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.

使用semver对比本地版本与最新版本。

如果本地版本 >= 最新版本：

报告："你的pm-skills已更新至最新版本（v{local}）。"
提供是否仍要生成报告的选项。
停止执行。

如果本地版本 < 最新版本：

显示版本差异：

本地版本:  v{local}
最新版本: v{latest}
更新类型:    {major | minor | patch}

大版本更新警告：如果是大版本更新（如v2.x升级到v3.x），显示显著警告：

这是大版本更新，可能包含技能协议的破坏性变更。请在继续前查看发布说明。
继续执行步骤3。

Step 3: Preview

步骤3：预览

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.

向用户展示更新包含的内容：

版本差异：本地版本、最新版本、更新类型。
价值总结：基于两个版本间的CHANGELOG条目、GitHub发布说明和目录差异（新增skills/、新增_workflows/文件）得出：
- 新增技能及其功能
- 更新技能的改进点
- 新增工作流及其关联内容
- 其他重要变更

文件清单：将即将写入的文件和文件夹按目录分组并统计数量：

即将写入的文件：
  skills/       31个文件（2个新增，29个更新）
  commands/     38个文件（2个新增，36个更新）
  _workflows/    9个文件（1个新增，8个更新）
  其他          7个文件
  总计：        85个文件

如果使用
--report-only
参数：使用

references/TEMPLATE.md

生成报告，添加"仅报告模式，未应用更新"的标识。保存至

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

。停止执行。

Step 4: Confirmation

步骤4：确认

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.

向用户确认两项决策：

更新确认: "这些文件将被覆盖。是否继续？[是 / 否]"
- 如果是大版本更新：要求用户明确输入"yes"。
- 如果用户拒绝：生成仅报告文件并停止。
备份选项: "是否在更新前创建当前文件的备份？ [是（推荐） / 否]"
- 如果选择是：将所有相关文件复制到
```
_pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/
```
- 如果
```
_pm-skills/
```
  目录不存在则创建。

Step 5: Update

步骤5：执行更新

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.

通过验证后复制的方式执行更新，并保留备份：

下载：从GitHub发布页面获取发布ZIP资产（
```
pm-skills-vX.Y.Z.zip
```
）到临时目录。这是由
```
build-release.sh
```
生成的精选构建产物，仅包含面向用户的内容，排除
```
docs/internal/
```
。
验证：确认解压后的归档文件包含
```
skills/
```
、
```
commands/
```
、
```
AGENTS.md
```
和
```
.claude-plugin/plugin.json
```
。如果验证失败，报告错误并停止，不写入任何文件。

复制：将解压归档中的相关文件覆盖到安装根目录。按目录显示进度：

正在更新pm-skills v2.9.0 -> v2.10.0...
  skills/       31/31 ████████████████████  完成
  commands/     38/38 ████████████████████  完成
  _workflows/    9/9  ████████████████████  完成
  其他文件    7/7  ████████████████████  完成

Step 6: Post-Update

步骤6：更新后操作

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.

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}

冒烟测试:
- 版本一致性：
```
plugin.json
```
  、
```
marketplace.json
```
  和
```
CHANGELOG.md
```
  均反映新版本。（注意：步骤1中的版本检测使用首次匹配规则；冒烟测试验证所有来源是否一致。此处不匹配表明发布打包存在问题。）
- 文件完整性：
```
AGENTS.md
```
  、
```
skills/
```
  、
```
commands/
```
  、
```
_workflows/
```
  均存在。
- 技能数量差异：统计更新前后的技能数量，报告变化。
- 如果任何检查失败：向用户发出警告并提供具体详情。不自动回滚，提供恢复指导：
  - 版本不匹配："重新运行更新，或手动编辑{file}将版本设置为{expected}。"
  - 文件缺失："重新运行
```
/update-pm-skills
```
    重新下载，或从备份恢复：
```
cp -r _pm-skills/backups/{dir}/* .
```
    "
  - 如果存在备份：始终提醒用户备份位置和恢复命令。

总结信息：显示一条简洁的确认信息：

已更新 v{old} -> v{new} | +{n}个技能, +{n}个工作流 | 报告：_pm-skills/updates/{file}

完成报告：使用

references/TEMPLATE.md

生成报告，保存至

_pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md

MCP提示：如果

../pm-skills-mcp/

存在，尝试读取

pm-skills-source.json

。如果文件缺失或格式错误，显示："检测到pm-skills-mcp，但未找到或无法读取pm-skills-source.json。请手动检查MCP仓库。"如果可读，显示：

在../pm-skills-mcp/检测到pm-skills-mcp
  嵌入技能版本: v{embedded}
  更新后的pm-skills版本: v{new}

  如需更新MCP服务器的嵌入技能：
    cd ../pm-skills-mcp && npm run embed-skills && npm run build

后续步骤:

后续步骤：
- 查看更新报告：_pm-skills/updates/{report-file}
- 运行 /pm-skill-validate --all 验证技能完整性
- 运行本地CI：bash scripts/lint-skills-frontmatter.sh
- 查看发布说明：{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):

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)

更新工具仅写入发布ZIP资产（

pm-skills-vX.Y.Z.zip

）中包含的文件，该ZIP是由

build-release.sh

生成的精选构建产物。ZIP文件排除

docs/internal/

和其他非用户面向内容，因此复制时无需额外排除逻辑。

发布ZIP中包含的文件（将被更新）：

路径	说明
`skills/`	核心技能文件
`commands/`	斜杠命令定义
`_workflows/`	工作流链
`library/`	示例库和技能输出样本（注意：用户添加的样本可能被覆盖）
`AGENTS.md`	IDE技能发现文件
`.claude-plugin/plugin.json`	版本+插件元数据
`marketplace.json`	市场元数据
`CHANGELOG.md`	发布历史
`README.md`	公开文档
`docs/` （公开指南、参考文档、工作流）	用户面向文档
`scripts/`	CI/验证脚本
`mkdocs.yml`	文档站点配置

发布ZIP中不包含的文件（永远不会被覆盖）：

路径	说明
`docs/internal/`	被 `build-release.sh` 排除在ZIP外
`_NOTES/`	本地专属文件，已加入git忽略，不在ZIP中
`_pm-skills/`	本地状态文件（报告、备份），不在ZIP中
`.github/`	CI工作流，不在ZIP中
`CONTRIBUTING.md` , `LICENSE`	不在ZIP中（仓库级文件）

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

此工具必须：

在任何远程操作前验证网络访问
在写入任何文件前显示预览
在覆盖文件前要求用户明确确认
在覆盖前提供备份选项
使用验证后复制的方式（下载到临时目录，验证后再复制；备份是复制中途失败的恢复路径）
在两种模式下（仅报告和完成更新）都生成报告
运行更新后冒烟测试
如果检测到同级仓库，显示MCP提示

此工具禁止：

未经用户确认写入文件
未确认网络访问就继续执行
修改pm-skills目录外的文件
使用上游内容修改
```
docs/internal/
```
、
```
_NOTES/
```
或
```
_pm-skills/
```
在冒烟测试失败时自动回滚（改为通知用户）
删除上游版本中不存在的本地文件

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

在标记更新完成前，验证以下内容：

预检通过：网络正常、版本检测成功
在写入任何文件前已向用户展示预览
在更新前已获得用户明确确认
已提供备份选项（如果用户接受则已创建备份）
归档文件已下载到临时目录并验证后再复制
所有相关文件已成功写入
版本一致性：plugin.json、marketplace.json、CHANGELOG版本一致
文件完整性：AGENTS.md、skills/、commands/、_workflows/均存在
已报告技能数量差异（更新前→更新后）
报告已生成并保存到
```
_pm-skills/updates/
```
如果检测到同级仓库，已显示MCP提示
已展示后续步骤
已显示总结信息

FAQ

常见问题

I'm a contributor who cloned the repo. Should I use this skill? No. Use

git pull

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.

我是克隆仓库的贡献者，应该使用此工具吗？ 不应该。请使用

git pull

或

git fetch && git merge

。此工具适用于将pm-skills作为插件安装或下载发布包的终端用户。

我可以更新到特定版本而不是最新版本吗？ v1版本不支持。此工具始终以最新版本为目标。如需安装特定版本，请从发布页面手动下载。

我的本地笔记和规划文档会怎样？ 它们永远不会被改动。此工具明确排除

docs/internal/

、

_NOTES/

和

_pm-skills/

的更新。请查看文件范围表格。

我添加的不在上游版本中的文件会怎样？ 它们会被保留。此工具仅覆盖新版本中存在的文件，永远不会删除本地文件。

如何撤销更新？ 如果你创建了备份（默认提供的选项），请恢复备份：

cp -r _pm-skills/backups/v{version}_{timestamp}/* .

如果你没有创建备份但使用git，请使用

git checkout .

将跟踪文件恢复到最后一次提交的状态。

更新中途失败了怎么办？ 此工具在复制前会进行验证（下载到临时目录，检查后再写入），因此部分失败的情况很少见。如果发生这种情况：如果有备份则从备份恢复，或重新运行

/update-pm-skills

重试。

扩展阅读

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

如需可视化教程和更多上下文，请查看更新PM Skills指南。",