# 技能文档优化指南

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

## 触发条件

- 用户要求优化某个技能包的文档结构、精简行数
- SKILL.md 超过 200 行，需要瘦身
- 多个章节存在重复内容，需要合并或抽取
- 完整代码块需要迁移到 references 或 samples
- 用户提到"技能优化"、"SKILL 瘦身"、"文档精简"

**不适用场景（不要触发）**：
- 技能包的功能开发或 bug 修复 → 直接编辑对应文件
- 静态诊断评分 → `skill-static-diagnosis`
- 运行时测试、接口联调 → 不在本技能范围

## 严格边界

- 本技能只修改文档结构，不修改技能的业务逻辑
- 抽取内容到 references 时，必须同步在 SKILL.md 中添加引用链接
- 不得删除信息，只能迁移——SKILL.md 删除的内容必须在 references 中保留
- 修改前必须先读取目标文件确认内容，避免破坏已有结构

## 优化目标

| 维度 | 目标 | 衡量标准 |
|------|------|---------|
| 精简度 | SKILL.md ≤ 200 行 | 大模型单次读取不超载 |
| 自包含 | 入口文件回答"怎么做"和"什么规则" | 不需跳转即可开始开发 |
| 零冗余 | 同一信息只在一个地方详细展开 | 任意两文件重叠率 ≤ 15% |
| 可验证 | 规则数、规则内容、代码示例三者对齐 | 模拟阅读零矛盾 |

## 执行步骤

### Step 1：现状评估

1. 统计目标 SKILL.md 行数（`wc -l`）
2. 识别重复章节——以下模式是合并信号：
   - "核心约束" + "严格禁止" + "严格要求" + "编码注意事项" → 合并为"核心规则"
   - 同一规则在多个章节出现 → 只保留一处
3. 检查与 references 的内容重叠：
   - SKILL.md 有完整代码示例 → 移到 references 或 samples
   - SKILL.md 有详细规范解释 → 移到 references，SKILL.md 只留摘要+引用

### Step 2：执行优化

按优先级处理：

1. **删除完整代码块**：替换为 `openyida sample` 命令引用或 references 链接
2. **合并重复章节**：多个约束/规则章节合并为统一的"核心规则"
3. **抽取详细内容**：JSON Schema、Prompt 模板、字段类型表等 → `references/*.md`
4. **补全引用链接**：每处抽取都必须在原位添加 `> 📖 详见 [references/xxx.md]` 引用

### Step 3：验证

1. 确认行数 ≤ 200
2. 确认所有 references 链接路径正确
3. 确认无信息丢失（抽取的内容在 references 中完整保留）

## 异常处理

| 异常场景 | 处理方式 |
|---------|----------|
| SKILL.md 已经 ≤ 200 行 | 告知用户无需优化，或仅做结构微调 |
| 无法判断哪些内容应抽取 | 优先抽取完整代码块和 JSON 示例，保留流程步骤和规则摘要 |
| references 目录不存在 | 先创建 `references/` 目录再写入文件 |
| 抽取后 SKILL.md 仍超 200 行 | 进一步合并重复章节，或将使用示例也抽取到 `references/examples.md` |

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

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

| 内容类型 | SKILL.md 中保留 | 详细内容放在 |
|---------|----------------|-------------|
| 规则 | 名称 + 一句话描述 | `references/*.md` |
| 代码 | `openyida sample` 命令 | `samples/*.js` |

…