Skill Update 用于在一次完整流程中规划并应用对现有技能的修改。它读取技能审查报告(单技能或全范围)或对话中的内联发现,为每条要点起草一项编辑并附上推荐答案,然后逐条走查、应用修改,并重新校验技能。
使用场景
- 已存在 skill-review 报告,用户希望进行后续处理
- 用户表示“应用审查结果”“落实建议”“修复这个技能”等
- 聊天中已有简短修复清单,用户希望逐项确认后应用
- 简单直接、规划与应用可一步完成的编辑 若无审查结果,应先运行 skill-review 再返回。
输入
- 审查来源:skill-review 报告(单技能或 --scope=all),或对话中的内联发现
- 目标技能:待编辑的 SKILL.md 路径
- 范围(可选):要处理的优先级,如“仅 P0”“P0 和 P1”“全部”
流程 第 1 步:解析反馈。读取所有报告与说明,提取每个问题及其严重级别、受影响技能、文件与维度,提取每条建议,以及 skill-review 的触发测试结果和覆盖缺口。对批量与深度审查中重复出现的问题去重,并按类别分组:frontmatter 修复、描述重写、内容重构、指令改进、归属修复、新增内容、删除项。
第 2 步:起草编辑计划。生成每条编辑一个要点的清单,每个要点附明确推荐答案,便于用户直接确认。对每项变更评分:影响(1–3,3 表示不修改会导致技能误触发,2 表示质量受损,1 表示润色)与工作量(1–3,1 表示快速字段编辑,2 表示重写一节,3 表示大改)。按影响降序、工作量升序排序,P0 在前,P1 次之,P2/P3 靠后。每个要点应写出实际编辑文本,而非笼统的“改进描述”,例如“将描述重写为:<新文本>”,描述重写应在计划中给出可直接套用的新描述。完整要点格式见 references/plan-format.md。
第 3 步:逐条走查编辑。展示计划后逐项处理:说明变更(文件、内容、原因、推荐答案),询问“是否应用此编辑?”默认是;确认后使用 Edit 应用(每次调用只做一个逻辑变更,不要批量混合无关编辑);跳过则记录原因;修改则采纳用户修订后应用;简要确认“已更新 <技能名>:<变更内容>”。应用规则:编辑前必须先读取文件;新增参考文件时先创建文件,再在父 SKILL.md 中链接;删除内容时更新指向被删内容的链接;frontmatter 编辑保留 YAML 格式与字段顺序;若计划编辑已不再适用则跳过并说明原因;跨不同技能的 10 项以上独立编辑可用子代理并行分派。
第 4 步:编辑后校验。重新读取所有修改过的 SKILL.md,依据 frontmatter 规范校验;确认正文长度符合指导(不超过 5,000 词且不超过 500 行,为软性警告),可移入 references 的内容优先移出;解析修改文件中的所有引用链接;若 owns 字段变更,复查与其他代理角色无重叠;如可用则运行 markdownlint。完整检查清单与报告格式见 references/validation-checklist.md。
第 5 步:重跑审查与同步(可选)。可询问是否重跑 skill-review 以确认问题已消除并对比前后差异;随后询问是否同步到全局技能位置,若同意则调用 sync-skills: skills/workflows/sync-skills/scripts/sync-skills.sh --to-all 若拒绝,提醒仓库版本已更新但全局位置仍为旧版本。
错误处理
- 编辑失败:报告失败内容,跳到下一项,收集失败项并在最后给出重试/手动修复/跳过选项
- 校验失败:指出具体失败项并建议修复,询问立即修复或稍后处理,未经确认不自动修复
指导原则
- 每条要点必须具体可执行
- 每项附推荐答案,便于快速确认
- 每次 Edit 只做一个逻辑变更
- 跳过纯风格偏好,聚焦功能性改进
- 注意变更间的顺序依赖
- 不要因定向编辑而整体重排文件
数据来源 起草编辑清单前,查阅真实使用信号:对将要修改的技能运行 scripts/skill-health.sh report --json(P2-C skill-health 遥测)。它报告每技能总调用次数、7 天/30 天成功率、下降标记以及版本漂移(记录的版本与当前 SKILL.md frontmatter 版本)。计算由代码确定性完成,非提示生成。该信号较粗且为尽力而为:emitter 记录 outcome:unknown,无数据技能只是未被观测,并非损坏,因此应用于排序和佐证,而非虚构问题。版本漂移行是无信号的有力提示,说明技能记录行为滞后于当前定义。详见 contracts/installer/skill-health.md。
参考
- references/plan-format.md:每条编辑一个要点的计划格式
- references/validation-checklist.md:编辑后检查(markdownlint、frontmatter 规范、行数、断链)