openyida skill-optimization-guide
把一个臃肿或混乱的 skill 文档集，改写成入口薄、描述直白、无重复的标准结构。
作用域
| 用户诉求 | 判定 | 动作 |
|---|---|---|
| "优化 XX skill" / "重写 XX 技能文档" | 本 skill | 进入下方流程 |
| "新建一个 skill" | 不是本 skill | 交给 skill-create |
| "只改某条规则" | 不是本 skill | 直接编辑目标文件 |
铁律
- 严禁删除规则不告知：优化过程中发现原 skill 的规则，即使觉得不合理也必须保留或明确询问用户，不能默默删掉。
- 严禁编造规则：只重组和改写已有内容，不能自己发明新的业务规则塞进去。
- 严禁破坏 script/ 中可运行脚本：改写文档时不能修改脚本逻辑，只能更新脚本中的路径引用。
流程概览
📌 仅当判定为「优化已有 skill」时进入此流程。
| 步骤 | 名称 | 功能描述 | 产出物 |
|---|---|---|---|
| 1 | 评估现状 | 逐文件阅读，统计行数、标记重复和抽象词、核对规则数 | 问题清单 |
| 2 | 拆分重组 | 根据问题清单规划新文件结构，确定每条信息只放一处 | 新文件清单 |
| 3 | 逐文件改写 | 按写作规则逐个文件改写，确保直白、正向、无重复 | 改写后的全部文件 |
| 4 | 验证收尾 | 结构、重复、语言、一致性四维验证 | 验证报告 |
核心规则
- 入口必须薄：SKILL.md 建议 300 行以内，只放作用域、铁律、流程、核心规则、参考文件这几类章节。
- 流程按复杂度选格式：简单流程直接在 SKILL.md 里写 Step 1/2/3；复杂流程（步骤多或单步内容长）才拆到 workflow/ 目录。
- 一条规则只写一处：入口写一句话摘要，详细解释只放在 references 的一个文件里。
- 用直白话写：每句话写成"对象 + 动作 + 产物"，不用胶水、赋能、闭环、中台这类抽象词。
- 正向引导优先：先写"应该做什么"，只在高风险场景（铁律）写"禁止做什么"。
- 规则数量必须对齐：入口说 N 条规则，references 里展开也必须是 N 条。
- 章节名称选最直白的：比如"铁律"比"严禁事项"更直白，"入口快速路由"在复杂路由场景比"作用域"更清晰。
Checklist
- SKILL.md 建议 300 行以内
- 任意两个文件内容重叠不超过 8%
- 所有规则只在一处有详细解释
- 无抽象词（胶水/赋能/闭环/中台/一体化）
- 参考文件列表覆盖 references/ 下所有文件
- 所有相对路径链接可达
- script/ 下的脚本可直接运行（如果有）
- 铁律覆盖了该 skill 的高风险操作
参考文件
| 文件 | 说什么 | 什么时候读 |
|---|---|---|
| 目录规范 | skill 目录怎么建、每层放什么、script 和 assets 的区别 | 步骤 2 拆分重组时必读 |
| 写作规则 | 用词、句式、铁律写法、代码去重标准 | 步骤 3 逐文件改写时必读 |
| 反模式速查 | 常见错误和对应的正确做法 | 步骤 4 验证时对照检查 |