utility-pm-skill-iterate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PM Skill Iterate

PM Skill 迭代改进

This skill improves an existing pm-skills skill by applying targeted changes based on input you provide. It reads the current skill files, proposes changes as before/after previews grouped by file, and writes them on your confirmation. After applying changes, it suggests a version bump class and offers to update HISTORY.md.

The iterator accepts any of these as input:

A validation report from
```
/pm-skill-validate
```
Direct feedback ("the template is missing section X")
A convention change ("all skills now need a Limitations section")
A general improvement request ("make the example more realistic")

本技能可根据你提供的输入，对现有的pm-skills技能进行针对性改进。它会读取当前技能文件，按文件分组展示变更前后的预览，在你确认后写入变更。变更应用完成后，它会建议版本升级类别，并提供更新HISTORY.md的选项。

迭代工具接受以下任意类型的输入：

来自
```
/pm-skill-validate
```
的验证报告
直接反馈（例如："模板缺少X章节"）
规范变更（例如："所有技能现在需要添加限制章节"）
通用改进请求（例如："让示例更贴合实际"）

When to Use

使用场景

After running
```
/pm-skill-validate
```
and getting a report with findings
When you have specific feedback on a skill and want to apply it
When a repo convention changes and a skill needs to conform
When a skill's example, template, or instructions need improvement
When iterating on a skill before a release

运行
```
/pm-skill-validate
```
并收到包含问题的报告后
你对某技能有具体反馈并希望应用时
仓库规范变更，技能需要适配时
技能的示例、模板或说明需要改进时
发布前对技能进行迭代优化时

When NOT to Use

不适用场景

To create a new skill from scratch -> use
```
/pm-skill-builder
```
To audit a skill before making changes -> use
```
/pm-skill-validate
```
first
To make bulk convention changes across many skills -> run
```
/pm-skill-validate --all
```
first to triage, then iterate one skill at a time

从零创建新技能 -> 使用
```
/pm-skill-builder
```
变更前审核技能 -> 先使用
```
/pm-skill-validate
```
对多个技能进行批量规范变更 -> 先运行
```
/pm-skill-validate --all
```
进行分类处理，再逐个迭代技能

Instructions

操作步骤

When asked to iterate on a skill, follow these steps:

当需要对技能进行迭代时，请遵循以下步骤：

Step 1: Identify the Target Skill

步骤1：确定目标技能

Accept the skill name in any form:

Directory name:
```
deliver-prd
```
Full path:
```
skills/deliver-prd/SKILL.md
```
Slash command:
```
/prd
```

Resolve to the canonical directory path:

skills/{name}/

If the skill directory does not exist, stop and report: "Skill directory

skills/{name}/

does not exist. Use

/pm-skill-builder

to create it."

接受任意形式的技能名称：

目录名称：
```
deliver-prd
```
完整路径：
```
skills/deliver-prd/SKILL.md
```
斜杠命令：
```
/prd
```

将其解析为标准目录路径：

skills/{name}/

。

如果技能目录不存在，请终止操作并报告："技能目录

skills/{name}/

不存在，请使用

/pm-skill-builder

创建。"

Step 2: Read Current Skill Files

步骤2：读取当前技能文件

Read all files in the skill directory:

File	Required	Purpose
`SKILL.md`	yes	Frontmatter + instructions (the primary edit target)
`references/TEMPLATE.md`	yes	Output template
`references/EXAMPLE.md`	yes	Worked example
`HISTORY.md`	no	Version history (needed for Step 7)

Record the exact content of each file at this point. You will compare against this content before writing in Step 5 (stale-preview guard).

If reading files is not possible (MCP/embedded environment), ask the user to paste the relevant file contents before proceeding (see Degraded Mode).

读取技能目录下的所有文件：

文件	是否必填	用途
`SKILL.md`	是	前端元数据 + 操作说明（主要编辑目标）
`references/TEMPLATE.md`	是	输出模板
`references/EXAMPLE.md`	是	示例案例
`HISTORY.md`	否	版本历史（步骤7需要）

记录此时每个文件的准确内容。在步骤5写入前，你将与该内容进行对比（防止预览过期）。

如果无法读取文件（如MCP/嵌入式环境），请让用户粘贴相关文件内容后再继续（参见降级模式）。

Step 3: Normalize Input into Intended Changes

步骤3：将输入标准化为预期变更

Regardless of input type, extract a structured list of intended changes before generating any edits. This normalization step is what makes the unified flow work consistently across all input types.

If the input is a validation report (from

/pm-skill-validate

Check for
```
Report schema: v1
```
in the header. If absent or a different schema version, warn: "This report uses an unrecognized schema. I'll do my best but may miss structured fields."
Parse the
```
## Recommendations
```
section.
Split each recommendation line on
```
|
```
to extract:
- Position 1: severity (FAIL, WARN, INFO)
- Position 2: check ID
- After
```
Target:
```
  : file path
- After
```
Action:
```
  (next line): what to change
Build the intended changes list from these fields.

If the input is free text (feedback, convention change, improvement request):

Read the input and identify what needs to change.
Map each change to a specific target file and section.
If the input is vague, ask ONE clarifying question before proceeding.

Present the normalized list for user confirmation:

Intended changes:
1. Target: skills/{name}/SKILL.md -> {section}
   Change: {what will change}
   Source: {validation report check ID | user feedback | convention change}
2. Target: skills/{name}/references/EXAMPLE.md -> {section}
   Change: {what will change}
   Source: {source}

If the user wants to modify the list (add, remove, or change items), adjust and re-present before proceeding.

无论输入类型如何，在生成任何编辑内容前，先提取结构化的预期变更列表。这个标准化步骤确保所有输入类型的流程一致。

如果输入是验证报告（来自

/pm-skill-validate

）：

检查头部是否包含
```
Report schema: v1
```
。如果不存在或版本不同，警告："此报告使用未识别的 schema，我会尽力处理但可能遗漏结构化字段。"
解析
```
## Recommendations
```
章节。
将每条建议按
```
|
```
拆分，提取：
- 第1位：严重程度（FAIL、WARN、INFO）
- 第2位：检查ID
- ```
Target:
```
  后：文件路径
- 下一行
```
Action:
```
  后：需要变更的内容
根据这些字段构建预期变更列表。

如果输入是自由文本（反馈、规范变更、改进请求）：

读取输入并确定需要变更的内容。
将每项变更映射到具体的目标文件和章节。
如果输入模糊，先提出一个澄清问题再继续。

将标准化后的列表呈现给用户确认：

预期变更：
1. 目标：skills/{name}/SKILL.md -> {章节}
   变更：{具体变更内容}
   来源：{验证报告检查ID | 用户反馈 | 规范变更}
2. 目标：skills/{name}/references/EXAMPLE.md -> {章节}
   变更：{具体变更内容}
   来源：{来源}

如果用户想要修改列表（添加、删除或更改项），调整后重新呈现再继续。

Step 4: Preview Proposed Changes

步骤4：预览拟议变更

For each intended change, generate the proposed edit and present it as a before/after block grouped by file:

undefined

针对每项预期变更，生成拟议编辑内容，并按文件分组以变更前后的区块呈现：

undefined

skills/{name}/SKILL.md

{Section name} -- before:

{exact current content of the section being changed}

{Section name} -- after:

{proposed new content for this section}

{章节名称} -- 变更前：

{待变更章节的当前准确内容}

{章节名称} -- 变更后：

{该章节的拟议新内容}

skills/{name}/references/EXAMPLE.md

{Section name} -- before:

{exact current content}

{Section name} -- after:

{proposed new content}


**Preview rules:**
- Group all changes by file. Show each file once, with all its changes.
- Show enough surrounding context for the user to understand the change.
- For small edits (a few lines), show the full section before and after.
- For large edits (rewriting most of a section), show the section header
  and the first/last few lines of before, then the full after.
- Do NOT show files that are not being changed.

Ask: "Apply these changes? [yes / no]"

If the user says no, ask what to adjust and return to Step 3 or Step 4.

{章节名称} -- 变更前：

{当前准确内容}

{章节名称} -- 变更后：

{拟议新内容}


**预览规则：**
- 按文件分组所有变更。每个文件只展示一次，包含其所有变更。
- 展示足够的上下文，让用户理解变更内容。
- 对于小修改（几行内容），展示章节的完整变更前后内容。
- 对于大修改（重写章节大部分内容），展示章节标题以及变更前的首尾几行，再展示完整的变更后内容。
- 不展示未变更的文件。

询问："是否应用这些变更？[是 / 否]"

如果用户选择否，询问需要调整的内容并返回步骤3或步骤4。

Step 5: Apply Changes (with Stale-Preview Guard)

步骤5：应用变更（含预览过期防护）

Before writing any file, re-read each target file and compare its content to what you recorded in Step 2.

If any target file has changed since Step 2:

Do NOT write any files.
Report: "File
```
{path}
```
has changed since the preview was generated. Regenerating preview with current content."
Return to Step 2 with the same intended changes list.

If all target files match:

Write the changes to each target file.
Update the
```
updated
```
field in SKILL.md frontmatter to today's date. (The
```
updated
```
field tracks when the file was last modified, regardless of whether a version bump is accepted.)
Report what was written: list each file and a one-line summary of what changed.

在写入任何文件前，重新读取每个目标文件并与步骤2中记录的内容对比。

如果任何目标文件自步骤2后已变更：

不要写入任何文件。
报告："文件
```
{path}
```
自生成预览后已变更，正在使用当前内容重新生成预览。"
带着相同的预期变更列表返回步骤2。

如果所有目标文件内容一致：

将变更写入每个目标文件。
更新SKILL.md前端元数据中的
```
updated
```
字段为当前日期。（
```
updated
```
字段记录文件最后修改时间，无论是否接受版本升级。）
报告写入内容：列出每个文件及变更的一行摘要。

Step 6: Suggest Version Bump

步骤6：建议版本升级

After changes are applied, classify the overall change and suggest a version bump class. Do NOT auto-write the version number.

Classification rules (from

docs/internal/skill-versioning.md

Change type	Bump class	Examples
Wording clarified, examples improved, typos fixed	patch	Reworded checklist item, better example scenario, description expanded
New optional capability or section added	minor	New optional output section, handles more scenarios, new quality check
Required contract changed, interaction pattern breaks	major	Command renamed, required section removed, "done" definition narrowed

Tie-breaker: If a user must do something new to stay compliant with the skill's required contract, classify as major. If the new behavior is additive or optional, classify as minor. If the required behavior is unchanged and only clarified, classify as patch.

Present the suggestion:

Suggested bump: {class} ({reason}).
Current version: {current}.
Bump to {suggested}? [yes / override / skip]

yes: Write the new version to SKILL.md frontmatter.
override: Ask for the desired version, validate it's valid SemVer and higher than current, then write it.
skip: Leave the version unchanged. The user may bump it later during release prep.

变更应用完成后，对整体变更进行分类并建议版本升级类别。不要自动写入版本号。

分类规则（来自

docs/internal/skill-versioning.md

）：

变更类型	升级类别	示例
措辞澄清、示例优化、错别字修正	patch	重写检查项内容、更优示例场景、扩展描述
添加新的可选功能或章节	minor	新增可选输出章节、支持更多场景、新增质量检查
要求的契约变更、交互模式破坏	major	命令重命名、移除必填章节、缩小"完成"定义范围

**平局规则：**如果用户必须采取新操作才能符合技能的必填契约，归类为major。如果新行为是附加或可选的，归类为minor。如果必填行为未变更仅做澄清，归类为patch。

呈现建议：

建议升级：{类别}（{原因}）。
当前版本：{当前版本}。
是否升级至{建议版本}？[是 / 自定义 / 跳过]

是：将新版本号写入SKILL.md前端元数据。
自定义：询问期望的版本，验证其为有效的SemVer且高于当前版本，然后写入。
跳过：保持版本不变，用户可在发布准备阶段后续升级。

Step 7: Offer HISTORY.md Update

步骤7：提供HISTORY.md更新选项

After the version decision, produce a change summary and handle HISTORY.md based on the current state:

If HISTORY.md exists and version was bumped:

Read HISTORY.md and validate its format:
- Has a summary table with
```
| Version | Date | Release | ...
```
  header
- Versions are newest-first in the table
- Each table version has a corresponding
```
## X.Y.Z
```
  section below
If format is valid: offer to append. "Would you like me to add this version to HISTORY.md? [yes / no]" On yes: add a new row to the summary table (newest-first) and a new
```
## X.Y.Z
```
section with the change summary.
If format is invalid: warn and show the proposed content without writing. "HISTORY.md doesn't follow the expected format. Here's what I would add -- you can paste it manually:" Then show the proposed table row and version section.

If HISTORY.md does not exist and this is the skill's second version: Offer to create it. "This is the second version of this skill. Would you like me to create HISTORY.md with entries for both versions? [yes / no]" On yes: create HISTORY.md with the format from

docs/internal/skill-versioning.md

, including entries for both the original version (from release history or effort brief) and the new version.

If HISTORY.md does not exist and version was not bumped: No offer. HISTORY.md is premature until the skill has shipped a second version.

If HISTORY.md exists but version was not bumped (skip): No offer. The change summary is available in the conversation for the user to use at their discretion.

版本决策完成后，生成变更摘要并根据当前状态处理HISTORY.md：

如果HISTORY.md存在且版本已升级：

读取HISTORY.md并验证其格式：
- 包含
```
| Version | Date | Release | ...
```
  标题的摘要表格
- 表格中版本按从新到旧排序
- 表格中的每个版本下方对应有
```
## X.Y.Z
```
  章节
如果格式有效：提供追加选项。 "是否要将此版本添加到HISTORY.md？[是 / 否]" 选择是：在摘要表格中添加新行（放在最上方），并新增
```
## X.Y.Z
```
章节包含变更摘要。
如果格式无效：发出警告并展示拟议内容但不写入。"HISTORY.md不符合预期格式，以下是我要添加的内容——你可以手动粘贴：" 然后展示拟议的表格行和版本章节。

如果HISTORY.md不存在且这是技能的第二个版本： 提供创建选项。"这是该技能的第二个版本，是否要创建HISTORY.md并添加两个版本的记录？[是 / 否]" 选择是：按照

docs/internal/skill-versioning.md

中的格式创建HISTORY.md，包含原始版本（来自发布历史或工作简报）和新版本的记录。

如果HISTORY.md不存在且版本未升级： 不提供选项。在技能发布第二个版本前，HISTORY.md还不需要创建。

如果HISTORY.md存在但版本未升级（跳过）： 不提供选项。变更摘要可在对话中查看，用户可自行决定使用时机。

Step 8: Report Summary

步骤8：报告摘要

Present a final summary:

undefined

呈现最终摘要：

undefined

Iteration Complete: {skill-name}

迭代完成：{技能名称}

Files changed:

skills/{name}/SKILL.md -- {summary}
skills/{name}/references/EXAMPLE.md -- {summary}

Version: {current} -> {new} ({class}) | or: unchanged (skipped) HISTORY.md: updated | created | skipped | not applicable

Next steps:

Run
```
/pm-skill-validate {name}
```
to verify the changes pass
Run local CI:
```
bash scripts/lint-skills-frontmatter.sh
```
If satisfied, commit the changes

undefined

已变更文件：

skills/{name}/SKILL.md -- {摘要}
skills/{name}/references/EXAMPLE.md -- {摘要}

版本： {当前版本} -> {新版本}（{类别}） | 或：未变更（已跳过） HISTORY.md： 已更新 | 已创建 | 已跳过 | 不适用

后续步骤：

运行
```
/pm-skill-validate {name}
```
验证变更是否通过
运行本地CI：
```
bash scripts/lint-skills-frontmatter.sh
```
如果满意，提交变更

undefined

Degraded Mode

降级模式

If you cannot read skill files directly (e.g., running via MCP or in an embedded environment without file system access):

Validation-report-driven iteration is preferred in this mode. The report carries the context (check IDs, target paths, actions).
For free-text iteration, ask the user to paste the content of each relevant file before proposing changes.
The stale-preview guard (Step 5) cannot run -- note in the summary: "Applied without stale-preview check (file system not available)."
HISTORY.md operations require the user to paste the current file content or confirm it does not exist.

如果无法直接读取技能文件（例如通过MCP运行或在无文件系统访问权限的嵌入式环境中）：

基于验证报告的迭代在此模式下更优，报告包含上下文（检查ID、目标路径、操作）。
对于自由文本迭代，在提出变更前请用户粘贴每个相关文件的内容。
预览过期防护（步骤5）无法运行——在摘要中注明："已应用变更，未进行预览过期检查（无文件系统访问权限）。"
HISTORY.md操作需要用户粘贴当前文件内容或确认其不存在。

Output Contract

输出契约

The iterator MUST:

Normalize input into a structured intended-changes list before editing
Present all proposed changes as before/after previews grouped by file
Require explicit user confirmation before writing any file
Re-read target files before writing to guard against stale previews
Update the
```
updated
```
frontmatter field on every apply
Suggest a version bump class without auto-writing the version number
Handle HISTORY.md according to the rules in Step 7

The iterator MUST NOT:

Write files without showing a preview first
Write files without user confirmation
Auto-increment the version number without explicit confirmation
Create HISTORY.md for a skill still on its first version
Append to HISTORY.md without validating its format first

迭代工具必须：

在编辑前将输入标准化为结构化的预期变更列表
将所有拟议变更按文件分组以变更前后的预览呈现
写入任何文件前需要用户明确确认
写入前重新读取目标文件以防止预览过期
每次应用变更时更新
```
updated
```
前端元数据字段
建议版本升级类别但不自动写入版本号
根据步骤7的规则处理HISTORY.md

迭代工具不得：

未展示预览就写入文件
未获得用户确认就写入文件
未获得明确确认就自动递增版本号
为仍处于第一个版本的技能创建HISTORY.md
未验证格式就追加到HISTORY.md

Quality Checklist

质量检查清单

Before completing the iteration, verify:

Input was normalized into an intended-changes list before editing
All proposed changes were shown as before/after previews
User confirmed before any files were written
Stale-preview guard ran before writing (or noted as unavailable)
```
updated
```
date was set to today in SKILL.md frontmatter
Version bump class was suggested with correct reasoning
Version was only written after explicit user confirmation
HISTORY.md was handled correctly per Step 7 rules
Final summary was presented with next steps

完成迭代前，请验证：

编辑前已将输入标准化为预期变更列表
所有拟议变更已以变更前后的预览展示
写入任何文件前已获得用户确认
写入前已运行预览过期防护（或注明不可用）
SKILL.md前端元数据中的
```
updated
```
日期已设置为当前日期
已正确建议版本升级类别及理由
仅在获得用户明确确认后才写入版本号
已根据步骤7的规则正确处理HISTORY.md
已呈现包含后续步骤的最终摘要

Examples

示例

See

references/EXAMPLE.md

for a completed iteration demonstrating a validation-report-driven improvement to a real shipped skill.

请查看

references/EXAMPLE.md

获取完整的迭代示例，展示如何基于验证报告对已发布的真实技能进行改进。