用途
utility-pm-skill-iterate 用于改进一个已有的 pm-skills 技能，方式是依据你提供的输入应用针对性变更。它会读取当前技能文件，按文件分组以“修改前/修改后”预览的形式提出变更，并在你确认后写入。应用变更后，它会建议一个版本号升级类别，并询问是否更新 HISTORY.md。
主要能力
该迭代器接受以下任意一种输入：
- 来自 utility-pm-skill-validate 的验证报告
- 直接反馈（例如“模板缺少 X 章节”）
- 约定变更（例如“所有技能现在都需要一个 Limitations 章节”）
- 一般改进请求（例如“让示例更真实”）
使用方式
当被要求迭代某个技能时，按以下步骤执行：
- 识别目标技能：接受目录名、完整路径或斜杠命令形式，解析为规范目录路径 skills/{name}/。若目录不存在则停止并提示使用 utility-pm-skill-builder 创建。
- 读取当前技能文件：读取 SKILL.md（必需，主要编辑目标）、references/TEMPLATE.md（必需）、references/EXAMPLE.md（必需）、HISTORY.md（可选，用于第 7 步）。记录各文件的确切内容，供第 5 步比对。若无法读取文件（MCP/嵌入式环境），请用户粘贴相关内容。
- 将输入规范化为预期变更：无论输入类型如何，先生成结构化的预期变更列表。若为验证报告，检查 Report schema: v1，解析 ## Recommendations 部分，按 | 拆分提取严重级别、检查 ID、目标文件路径和操作。若为自由文本，识别需要变更的内容并映射到具体目标文件和章节；若输入含糊，先提一个澄清问题。向用户展示规范化列表以供确认。
- 预览拟议变更：按文件分组，以修改前/修改后块展示。小改动展示完整章节前后内容；大改动展示章节标题及前后若干行。不展示未变更的文件。询问“是否应用这些变更？[yes / no]”。
- 应用变更（含过期预览防护）：写入前重新读取每个目标文件并与第 2 步记录比对。若文件已变化，不写入任何文件，报告并返回第 2 步重新生成预览。若一致，写入变更，将 SKILL.md frontmatter 中的 updated 字段更新为今天日期，并验证每个重写文件第 0 字节仍为 ---。报告写入内容。
- 建议版本号升级：应用变更后，对整体变更分类并建议升级类别，不自动写入版本号。分类规则：措辞澄清、示例改进、错别字修复为 patch；新增可选能力或章节为 minor；必需契约变更、交互模式破坏为 major。展示建议并询问 [yes / override / skip]。
- 询问是否更新 HISTORY.md：根据当前状态处理。若 HISTORY.md 存在且版本已升级，验证格式后询问是否追加；格式无效则警告并展示拟议内容而不写入。若 HISTORY.md 不存在且这是技能第二个版本，询问是否创建。若不存在且版本未升级，不提供。若存在但版本未升级（skip），不提供。
- 报告摘要：展示最终摘要，包括变更文件、版本变化、HISTORY.md 状态和后续步骤（运行 utility-pm-skill-validate 验证、运行本地 CI、提交变更）。
适用场景
- 运行 utility-pm-skill-validate 并得到含发现的报告之后
- 当你对某个技能有具体反馈并希望应用时
- 当仓库约定变更且某个技能需要遵循时
- 当某个技能的示例、模板或说明需要改进时
- 在发布前迭代某个技能时
限制
不适用于以下情况：
- 从零创建新技能 -> 使用 utility-pm-skill-builder
- 在变更前审计技能 -> 先使用 utility-pm-skill-validate
- 跨多个技能进行批量约定变更 -> 先运行 utility-pm-skill-validate --all 进行分诊，然后逐个迭代
输出契约要求：迭代器必须在编辑前将输入规范化为结构化预期变更列表；必须以按文件分组的修改前/修改后预览展示所有拟议变更；必须在写入任何文件前获得用户明确确认；必须在写入前重新读取目标文件以防过期预览；必须在每次应用时更新 updated frontmatter 字段；必须建议版本号升级类别而不自动写入版本号；必须按第 7 步规则处理 HISTORY.md。迭代器不得：未先展示预览就写入文件；未经用户确认就写入文件；未经明确确认就自动递增版本号；为仍处于第一版的技能创建 HISTORY.md；未先验证格式就追加到 HISTORY.md。
在降级模式下（无法直接读取技能文件，例如通过 MCP 或在无文件系统访问的嵌入式环境中运行）：优先采用验证报告驱动的迭代；自由文本迭代需用户粘贴相关文件内容；过期预览防护无法运行，需在摘要中注明；HISTORY.md 操作需用户粘贴当前内容或确认其不存在。