git:20260804.3f96b25 to git:20260805.afde623

- description: 技能文档（SKILL.md）优化指南。当用户要优化某个技能包的 SKILL.md 文档结构、精简行数、消除冗余、抽取 references 时触发。适用于技能包超过 200 行需要瘦身、多章节重复需要合并、完整代码需要抽取到 references 或 assets 等场景。不适用于：技能包的功能开发、运行时测试、静态诊断评分（应使用 skill-static-diagnosis）。

- # 技能文档优化指南

-

- 对技能包的 SKILL.md 进行结构优化，使其符合"导航枢纽"定位：精简、自包含、零冗余、可执行。

-

- ## 触发条件

-

- - 用户要求优化某个技能包的文档结构、精简行数

- - 用户要求创建或重写一个 skill 的目录、入口、workflow、references 和语言风格

- - SKILL.md 超过 200 行，需要瘦身

- - 多个章节存在重复内容，需要合并或抽取

- - 完整代码块需要迁移到 references 或 assets

- - 用户提到"技能优化"、"SKILL 瘦身"、"文档精简"、"不像给小白读"、"不够条理清晰"、"太抽象"、"要直白"

-

- **不适用场景（不要触发）**：

- - 技能包的功能开发或 bug 修复 → 直接编辑对应文件

- - 静态诊断评分 → `skill-static-diagnosis`

- - 运行时测试、接口联调 → 不在本技能范围

-

- ## 严格边界

-

- - 本技能只修改文档结构，不修改技能的业务逻辑

- - 抽取内容到 references 时，必须同步在 SKILL.md 中添加引用链接

- - 不得删除信息，只能迁移——SKILL.md 删除的内容必须在 references 中保留

- - 修改前必须先读取目标文件确认内容，避免破坏已有结构

- - 技能文档只写 agent 要执行的规则、步骤、输入输出和边界；方案讨论、个人推理、历史原因、未来可能拆分、"为什么这么设计"放到普通 docs / PRD / issue，不放进 skill。

- - 优先使用正向引导："读取/输出/保持/复用/交给/消费/完成"；只有会造成危险、破坏数据或明显误选的点才写禁止句。

- - 描述和正文都使用直白业务语言：写清"处理什么对象、执行什么动作、输出什么产物"；把"胶水/闭环/承载/赋能/一体化体验/能力中台"等抽象词改成具体动作，例如"在自定义页放置表单提交入口、流程处理入口、报表查看入口和详情页入口，用户能在当前页查看数据并继续操作"。

- - 设计类 skill 使用 `workflow/` 和 `references/scenes/` 作为默认设计依据；CLI 生成器只作为实现工具，不写成默认阅读对象，也不写成"模板优先"。

- - 历史页面经验优先沉淀为 `references/style-designs/*.design.md`：写清适用场景、视觉 DNA、布局配方、组件规则、状态规则和交付自检。文档只提供风格规则，不复制业务文案、静态数据、图片地址或页面顺序。

-

- ## 优化目标

-

- | 维度 | 目标 | 衡量标准 |

- |------|------|---------|

- | 精简度 | SKILL.md ≤ 200 行 | 大模型单次读取不超载 |

- | 自包含 | 入口文件回答"怎么做"和"什么规则" | 不需跳转即可开始开发 |

- | 零冗余 | 同一信息只在一个地方详细展开 | 任意两文件重叠率 ≤ 15% |

- | 可验证 | 规则数、规则内容、代码示例三者对齐 | 模拟阅读零矛盾 |

- | 可执行 | 每段话都能转成动作、产物或判断 | 无方案讨论、无过程性自问自答 |

- | 易读性 | 新手能读懂当前 skill 何时用、怎么做、产出什么 | 少抽象词，少比喻，少内部黑话 |

-

- ## 推荐目录结构

-

- ```text

- skills/<skill-name>/

- SKILL.md # 唯一入口，写触发、作用域、标准流程、核心规则和参考导航

- workflow/ # 长流程步骤；步骤超过 4 个或单步超过 50 行时拆到这里

- step-1-*.md

- step-2-*.md

- references/ # 规则细节、场景参考、参数表、决策矩阵、故障处理

- scenes/*.md

- *.md

- sub_skill/<sub-name>/

- SKILL.md # 内部子入口；文件名也用 SKILL.md

- assets/ # 可复用素材或脚本输入

- ```

-

- 目录规则：

-

- - `SKILL.md` 是入口，不把长篇说明、方案演进、案例复盘和完整模板塞进去。

- - `workflow/` 放必须按顺序执行的步骤；入口用表格列出 Step、读取文件、产出物，并要求不跳步。

- - `references/` 放按场景读取的详细规则；已有 `scenes/` 时，列表/看板/详情/官网等场景规则收敛到 scene 文件，避免再建重复的 `list/ dashboard/ detail/ landing/` 平行目录。

- - `sub_skill/` 只放真正需要独立入口的子流程；子流程入口文件命名为 `SKILL.md`，并避免重复上层已说明的作用域。

- - 跨 skill 共享材料放根级 `yida-skills/references/`；单 skill 专属材料放本 skill 的 `references/`。

-

- ## SKILL.md 标准结构

-

- 按这个顺序写，缺一项会让后续 agent 容易误读：

-

- 1. **frontmatter**：`name` + `description`。description 用直白句式写"做什么、何时触发、输出什么"，不要写实现讨论或抽象口号。

- 2. **一句话定位**：说明这个 skill 负责什么业务对象、执行什么动作、交付什么产物。

- 3. **入口路由 / 作用域判断**：先判断用户要处理的对象；作用域判断放上层入口，不在每个 step 里重复。

- 4. **标准流程**：用 Step 表格写清每一步读哪个文件、做什么、产出什么；长步骤链接到 `workflow/step-*.md`。

- 5. **核心规则**：写正向、可执行规则；例如"表单入口 PC 用抽屉承载原始提交 URL，移动端整页打开"。

- 6. **输出 / doneWhen**：写最终产物、文件位置、完成证据。

- 7. **参考文件表**：列出所有需要读的 workflow / references / sub_skill，并说明何时读取。

-

- 内容边界：

-

- - 写"当前 skill 输出 X，另一个 skill 消费 X"，避免写"当前 skill 不负责 Y"这类负向边界。

- - 写给新手也能读懂的业务话：少用比喻和抽象名词；遇到"胶水/能力/体验/增强/闭环"这类词，改成具体资源、具体动作和具体结果。

- - 写可执行判断，不写"我觉得/为什么/为了避免/后续可以/如果发现过大再拆"。

- - 复杂流程放 `workflow/`，长规则放 `references/`，入口只做导航和门禁。

- - 单页、应用、主题等作用域已经在上层 skill 判断时，子 skill 不再重复"使用门槛"。

- - 页面设计文档先写业务目标、页面场景、区块、布局、交互和主题；实现文档再决定生成器入口或手写页面。不要在 PRD 或设计流程里输出"推荐模板"字段。

- - 设计沉淀文档使用"页面风格设计文档 / design.md"表达，说明它提供视觉规则；业务对象、字段、页面区块和交互路径来自当前 PRD。

-

- ## 执行步骤

-

- ### Step 1：现状评估

-

- 1. 统计目标 SKILL.md 行数（`wc -l`）

- 2. 识别重复章节——以下模式是合并信号：

- - "核心约束" + "严格禁止" + "严格要求" + "编码注意事项" → 合并为"核心规则"

- - 同一规则在多个章节出现 → 只保留一处

- 3. 检查与 references 的内容重叠：

- - SKILL.md 有完整代码示例 → 移到 references 或 assets

- - SKILL.md 有详细规范解释 → 移到 references，SKILL.md 只留摘要+引用

- 4. 检查是否混入过程性内容：

- - 方案讨论、命名争论、历史原因、"为什么这么做" → 移到普通 docs 或删除

- - 未来规划、可选拆分、暂时性想法 → 移到 task/issue，不进入 skill

- - 负向句过多 → 改成正向动作和输出要求

- 5. 检查语言是否直白：

- - 抽象词、比喻、内部黑话 → 改成"对象 + 动作 + 产物"

- - description 读完仍不知道何时触发或产出什么 → 重写为一到两句具体业务话

- ### Step 2：执行优化

- 按优先级处理：

- 1. **删除完整代码块**：替换为 references 链接、代码骨架或实现步骤说明

- 2. **合并重复章节**：多个约束/规则章节合并为统一的"核心规则"

- 3. **抽取详细内容**：JSON Schema、Prompt 模板、字段类型表等 → `references/*.md`

- 4. **补全引用链接**：每处抽取都必须在原位添加 `> 📖 详见 [references/xxx.md]` 引用

- 5. **重写语言**：把"不要/禁止/不应该"优先改成"使用/保持/输出/读取/复用/交给"，保留少量高风险禁止句；把抽象词和比喻改成具体对象、动作和产物。

- ### Step 3：验证

- 1. 确认行数 ≤ 200

- 2. 确认所有 references 链接路径正确

- 3. 确认无信息丢失（抽取的内容在 references 中完整保留）

- 4. 用 `rg` 扫描旧 skill 名、旧模式名、临时讨论词和重复章节标题

- 5. 源码态 skill 改动后运行 `npm run build:skills`，再运行 `npm run check:skills`

- ## 异常处理

- | 异常场景 | 处理方式 |

- |---------|----------|

- | SKILL.md 已经 ≤ 200 行 | 告知用户无需优化，或仅做结构微调 |

- | 无法判断哪些内容应抽取 | 优先抽取完整代码块和 JSON 示例，保留流程步骤和规则摘要 |

- | references 目录不存在 | 先创建 `references/` 目录再写入文件 |

- | 抽取后 SKILL.md 仍超 200 行 | 进一步合并重复章节，或将使用示例也抽取到 `references/examples.md` |

- ## SKILL.md 的导航枢纽原则

- SKILL.md 是导航枢纽，不是内容倾倒场：

- | 内容类型 | SKILL.md 中保留 | 详细内容放在 |

- |---------|----------------|-------------|

- | 规则 | 名称 + 一句话描述 | `references/*.md` |

- | 代码 | 只保留命令或骨架说明 | `references/*.md` 或 `assets/` |

- | API | 速查表（方法名+说明+必填参数） | `yida-api.md` |

- | 流程 | 完整保留（bash 步骤） | — |

- | JSON Schema | 引用链接 | `references/*.md` |

- | Prompt 模板 | 引用链接 | `references/*.md` |

- ## 完成检查清单

- - [ ] SKILL.md ≤ 200 行

- - [ ] SKILL.md 无完整代码块（只有 bash 命令和速查表）

- - [ ] SKILL.md 没有方案讨论、命名讨论、历史复盘、未来拆分设想

- - [ ] 语言直白、条理清晰、简单易懂；description 和正文都能回答"处理什么、怎么做、产出什么"

- - [ ] 语言以正向动作和产物为主，负向禁止只用于高风险边界

- - [ ] 抽象词、比喻和内部黑话已替换为具体业务对象、操作和结果

- - [ ] 设计类 skill 没有把生成器入口写成默认设计依据；PRD 按页面输出场景、区块、布局、交互、页面风格、`designMd` 和视觉 DNA

- - [ ] 作用域判断在上层入口完成，子技能不重复使用门槛

- - [ ] 长流程在 `workflow/`，长规则在 `references/`，子入口文件名为 `SKILL.md`

- - [ ] 所有抽取内容在 references 中完整保留

- - [ ] 所有引用链接路径正确可达

- - [ ] 参考文档导航表完整（含跨 skill 共享文档）

- ## 参考文档

- | 文档 | 覆盖范围 | 何时阅读 |

- |------|---------|---------|

- | [优化方法论](references/optimization-methodology.md) | 三层职责模型、规则分级标准、代码去重规范、验证方法、反模式案例 | 首次执行优化前必读 |