skill-optimization-guide git:20260804.464875dA

Immutable. This exact content is served forever at /api/v1/blob/68446a44faeab79b.

---
name: skill-optimization-guide
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 生成器只作为实现工具，不写成默认阅读对象，也不写成"模板优先"。

## 优化目标

| 维度 | 目标 | 衡量标准 |
|------|------|---------|
| 精简度 | 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 或设计流程里输出"推荐模板"字段。

## 执行步骤

### 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 输出页面场景、区块、布局和交互，不输出推荐模板字段
- [ ] 作用域判断在上层入口完成，子技能不重复使用门槛
- [ ] 长流程在 `workflow/`，长规则在 `references/`，子入口文件名为 `SKILL.md`
- [ ] 所有抽取内容在 references 中完整保留
- [ ] 所有引用链接路径正确可达
- [ ] 参考文档导航表完整（含跨 skill 共享文档）

## 参考文档

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