在收到校验报告或反馈后对已有技能做定向改进并管理版本

当你需要根据校验报告、用户反馈或仓库约定变更来改进一个已有的 pm-skills 技能文件时使用。

适用场景

解决思路

1. 接受技能名任意形式（目录名如 deliver-prd、完整路径如 skills/deliver-prd/SKILL.md、斜杠命令），解析为规范目录路径 skills/{name}/；若目录不存在则停止并提示用 utility-pm-skill-builder 创建。
2. 读取技能目录下所有文件：SKILL.md（必需，主要编辑目标）、references/TEMPLATE.md（必需）、references/EXAMPLE.md（必需）、HISTORY.md（可选，Step 7 需要）；记录每个文件的精确内容，供 Step 5 写入前比对（防陈旧预览）。
3. 若无法读取文件（MCP/嵌入式环境），请用户粘贴相关文件内容后再继续（降级模式）。
4. 在生成任何编辑前，先把输入归一化为结构化的预期变更列表：若输入是校验报告，检查头部是否有 Report schema: v1，缺失或版本不同则警告，解析 ## Recommendations 段，按 | 拆分每行提取严重级别、检查 ID、Target 文件路径、Action 变更内容；若输入是自由文本（反馈、约定变更、改进请求），识别需变更内容并映射到具体目标文件与章节，若含糊则先问一个澄清问题。
5. 向用户展示归一化后的预期变更列表（目标文件、章节、变更内容、来源）并确认；用户要增删改则调整后重新展示。
6. 为每个预期变更生成 before/after 预览，按文件分组（每个文件只展示一次，包含其全部变更）；小改动展示完整章节前后，大改动展示章节标题与首尾几行 before 加完整 after；不展示未变更的文件；询问是否应用。
7. 用户拒绝时询问要调整什么，返回 Step 3 或 Step 4。
8. 写入前重新读取每个目标文件并与 Step 2 记录的内容比对；若有文件已变化，不写任何文件，报告文件已变化并回到 Step 2 用当前内容重新生成预览。
9. 若所有目标文件一致，写入变更；将 SKILL.md frontmatter 的 updated 字段更新为今天日期（无论是否接受版本升级）。
10. 字节 0 保护：验证每个重写文件第 0 字节仍为 ---（前面无内容）；若原内容违反该放置（如第 1 行是 HTML 署名注释），在应用其他变更前防御性提示并提供在同一写入中修复。
11. 报告写入内容：列出每个文件及一行变更摘要。
12. 应用变更后分类整体变更并建议版本升级类别，不自动写入版本号：措辞澄清/示例改进/拼写修复为 patch；新增可选能力或章节为 minor；必需契约变更或交互模式破坏为 major；若用户必须做新事情才能符合必需契约则判 major，若新行为是附加或可选则判 minor，若必需行为未变仅澄清则判 patch。
13. 展示建议：Suggested bump: {class}（原因）、当前版本、建议版本，询问 yes/override/skip；yes 则写入新版本到 SKILL.md frontmatter；override 则询问目标版本，校验为合法 SemVer 且高于当前后写入；skip 则保持版本不变。
14. 版本决定后处理 HISTORY.md：若 HISTORY.md 存在且版本已升级，读取并校验格式（有 | Version | Date | Release | 表头、版本最新在前、每个表版本有对应 ## X.Y.Z 段）；格式有效则询问是否追加，同意则加新行（最新在前）和新的 ## X.Y.Z 段；格式无效则警告并展示拟添加内容供手动粘贴。
15. 若 HISTORY.md 不存在且这是技能第二个版本，询问是否创建 HISTORY.md 并包含两个版本的条目，同意则按 docs/internal/skill-versioning.md 格式创建，包含原版本（来自发布历史或 effort brief）和新版本条目。
16. 若 HISTORY.md 不存在且版本未升级，不提供创建；若 HISTORY.md 存在但版本未升级（skip），不提供追加，变更摘要留在对话中供用户自行使用。
17. 展示最终摘要：变更文件列表、版本变化（当前->新版本及类别，或 unchanged skipped）、HISTORY.md 状态（updated/created/skipped/not applicable）、后续步骤（运行 utility-pm-skill-validate {name} 验证、运行 bash scripts/lint-skills-frontmatter.sh、满意后提交）。
18. 降级模式下：优先用校验报告驱动迭代；自由文本迭代请用户粘贴每个相关文件内容；无法运行防陈旧预览保护时在摘要中注明 Applied without stale-preview check (file system not available)；HISTORY.md 操作需用户粘贴当前内容或确认不存在。
19. 遵守输出契约：必须先归一化输入为结构化预期变更列表、按文件分组展示 before/after 预览、写入前需用户明确确认、写入前重读目标文件防陈旧预览、每次应用都更新 updated 字段、只建议版本升级类别不自动写版本号、按 Step 7 规则处理 HISTORY.md；不得未预览就写文件、未确认就写文件、未明确确认就自动递增版本号、为仍处第一版的技能创建 HISTORY.md、未校验格式就追加 HISTORY.md。
20. 完成前核对质量清单：输入已归一化、所有变更已展示前后预览、写入前已获用户确认、防陈旧预览保护已运行（或注明不可用）、updated 日期已设为今天、版本升级类别及理由正确、版本仅在用户明确确认后写入、HISTORY.md 按 Step 7 规则处理、最终摘要含后续步骤。
21. 参考 references/EXAMPLE.md 中一个基于校验报告改进真实已发布技能的完整迭代示例。

适用边界 · 注意事项

• 从零创建新技能时（应使用 utility-pm-skill-builder）
• 在变更前审计技能时（应先使用 utility-pm-skill-validate）
• 跨多个技能做批量约定变更时（应先运行 utility-pm-skill-validate --all 分诊，再逐个迭代）