skill-optimization-guide git:20260805.afde623A

Immutable. This exact content is served forever at /api/v1/blob/68113a03e23aaffa.

---
name: skill-optimization-guide
description: 当需要优化一个已有 skill 文档时触发。读取目标 skill 全部文件，按四步流程重写，产出结构清晰、入口薄、描述直白的 skill 文档集。
---

# skill-optimization-guide

把一个臃肿或混乱的 skill 文档集，改写成入口薄、描述直白、无重复的标准结构。

## 作用域

| 用户诉求 | 判定 | 动作 |
|---------|------|------|
| "优化 XX skill" / "重写 XX 技能文档" | 本 skill | 进入下方流程 |
| "新建一个 skill" | 不是本 skill | 交给 skill-create |
| "只改某条规则" | 不是本 skill | 直接编辑目标文件 |

## 铁律

1. **严禁删除规则不告知**：优化过程中发现原 skill 的规则，即使觉得不合理也必须保留或明确询问用户，不能默默删掉。
2. **严禁编造规则**：只重组和改写已有内容，不能自己发明新的业务规则塞进去。
3. **严禁破坏 script/ 中可运行脚本**：改写文档时不能修改脚本逻辑，只能更新脚本中的路径引用。

## 流程概览

> 📌 仅当判定为「优化已有 skill」时进入此流程。

| 步骤 | 名称 | 功能描述 | 产出物 |
|------|------|----------|--------|
| 1 | [评估现状](workflow/step-1-assess.md) | 逐文件阅读，统计行数、标记重复和抽象词、核对规则数 | 问题清单 |
| 2 | [拆分重组](workflow/step-2-restructure.md) | 根据问题清单规划新文件结构，确定每条信息只放一处 | 新文件清单 |
| 3 | [逐文件改写](workflow/step-3-rewrite.md) | 按写作规则逐个文件改写，确保直白、正向、无重复 | 改写后的全部文件 |
| 4 | [验证收尾](workflow/step-4-verify.md) | 结构、重复、语言、一致性四维验证 | 验证报告 |

## 核心规则

1. **入口必须薄**：SKILL.md 建议 300 行以内，只放作用域、铁律、流程、核心规则、参考文件这几类章节。
2. **流程按复杂度选格式**：简单流程直接在 SKILL.md 里写 Step 1/2/3；复杂流程（步骤多或单步内容长）才拆到 workflow/ 目录。
3. **一条规则只写一处**：入口写一句话摘要，详细解释只放在 references 的一个文件里。
4. **用直白话写**：每句话写成"对象 + 动作 + 产物"，不用胶水、赋能、闭环、中台这类抽象词。
5. **正向引导优先**：先写"应该做什么"，只在高风险场景（铁律）写"禁止做什么"。
6. **规则数量必须对齐**：入口说 N 条规则，references 里展开也必须是 N 条。
7. **章节名称选最直白的**：比如"铁律"比"严禁事项"更直白，"入口快速路由"在复杂路由场景比"作用域"更清晰。

## Checklist

- [ ] SKILL.md 建议 300 行以内
- [ ] 任意两个文件内容重叠不超过 8%
- [ ] 所有规则只在一处有详细解释
- [ ] 无抽象词（胶水/赋能/闭环/中台/一体化）
- [ ] 参考文件列表覆盖 references/ 下所有文件
- [ ] 所有相对路径链接可达
- [ ] script/ 下的脚本可直接运行（如果有）
- [ ] 铁律覆盖了该 skill 的高风险操作

## 参考文件

| 文件 | 说什么 | 什么时候读 |
|------|--------|-----------|
| [目录规范](references/directory-convention.md) | skill 目录怎么建、每层放什么、script 和 assets 的区别 | 步骤 2 拆分重组时必读 |
| [写作规则](references/writing-rules.md) | 用词、句式、铁律写法、代码去重标准 | 步骤 3 逐文件改写时必读 |
| [反模式速查](references/anti-patterns.md) | 常见错误和对应的正确做法 | 步骤 4 验证时对照检查 |