---
name: skill-evolve-workflow
description: >-
  技能自进化工作流 —— 对已有 skill 进行反思分类、双结构维护、Auditor 检查的标准化流程。
  适用于：遇到一个 skill 执行失败后，判断是 skill 本身的问题还是执行失误，然后针对性地修改。
  Triggers: skill 改进, skill 进化, 优化 skill, skill 自进化, 技能改进, 修改 skill, 技能有缺陷,
  反思分类, 踩坑日志, audit skill, auditor 检查, S_body, S_appendix, skill 执行失败, skill 问题,
  技能不生效, skill 没效果, 帮我改进这个 skill, 这个 skill 需要优化
  Do NOT trigger for: 从零创建新 skill（用 skill-creator）, 不需要修改的已有 skill,
  不涉及 skill 文件的普通代码修改
---

# 技能自进化工作流（Skill Evolve Workflow）

这是一个**元技能**——管理其他技能进化的标准化流程。基于 SkillEvolver（arXiv:2605.10500）和 EmbodiSkill（arXiv:2605.10332）的核心机制设计。

## 核心原则

- **更新的是技能文本和代码，不是模型权重**——改 SKILL.md 文件，不需要 GPU 训练
- **先分类，再修改**——不跳过分类步骤直接改，避免把执行失误当成 skill 缺陷来修
- **验证后才能合入**——修改后必须通过独立检查和执行验证

---

## 工作流总览

```
         ┌──────────────┐
         │  检出失败场景   │
         └──────┬───────┘
                ▼
         ┌──────────────┐
         │  反思分类判断  │ ← 用 subagent 独立执行
         └──────┬───────┘
                ▼
           ┌────┴────┐
           │         │
      SkillDefect  ExecutionLapse
      Discovery    Optimization
      (改 S_body)  (改 S_appendix)
           │         │
           └────┬────┘
                ▼
         ┌──────────────┐
         │  Auditor 检查  │ ← 5 项检查通过才合入
         └──────┬───────┘
                ▼
         ┌──────────────┐
         │   clean Agent  │
         │   执行验证     │
         └──────────────┘
```

---

## 步骤一：轨迹日志

执行任务后，记录结构化执行轨迹。这是后续分类的原始证据。

格式约定（在 subagent 任务中要求输出此格式）：

```yaml
task: "任务描述"
skill_used: "使用的 skill 名称（如未激活则写 none）"
result: "success | failure"
evidence:
  - 执行了什么操作
  - 命令或工具调用
  - 输出结果
  - 退出的状态码
observed_issue: "观察到的具体问题现象"
```

不需要专门的日志工具，只要在每次执行失败后按这个格式整理即可。

---

## 步骤二：反思分类

### 四种类型

| 类型 | 触发条件 | 动作 | 修改目标 |
|------|---------|------|---------|
| **Discovery** | 任务**成功**，但发现当前 skill 可以覆盖的新场景 | 往 body **加**新内容 | S_body |
| **Optimization** | 任务**成功**，但当前方式效率不高 | **优化** body 中的现有步骤 | S_body |
| **SkillDefect** | 任务**失败**，原因是 skill 本身有缺陷 / 覆盖不全 | **修复** body 中的指令缺陷 | S_body |
| **ExecutionLapse** | 任务**失败**，但 skill 内容正确，是执行时没按 skill 走 | 往 appendix **追加**踩坑提醒 | S_appendix |

### 分类判断流程

派一个 **clean subagent**（不加载当前 skill 的上下文）执行以下判断：

```
判断问题：{描述失败现象和轨迹}

当前技能相关指令：{引用 SKILL.md 中相关的核心指令}

请按步骤判断：
1. 执行时是否遵循了 skill 中的既有指令？
   → 是/否，理由

2. skill 中是否缺少针对此场景的指令？
   → 是/否，理由

3. 如果把 skill 中的所有现有方案都套上，问题是否仍然存在？
   → 关键判定：是=SkillDefect/否=ExecutionLapse

分类结论：[Discovery / Optimization / SkillDefect / ExecutionLapse]
理由：...
建议修改方向：...
```

**关键判别准则**：如果执行者严格按照 skill 的所有方案操作后问题依然存在，就不是执行失误（ExecutionLapse），而是 skill 设计缺陷（SkillDefect）。

---

## 步骤三：按分类修改

### 修改 SKILL.md 的结构约定

每个 SKILL.md 建议分为两大区域，用明确的区块标题分隔：

```markdown
## ═══ S_body：核心指令 ═══
（诊断流程、各场景修复方法、核心步骤）

## ═══ S_appendix：踩坑记录 ═══
（注意事项、踩坑日志）
```

### 修改规则

| 分类 | 改哪里 | 怎么改 |
|------|--------|--------|
| **Discovery** | S_body | 追加新的场景段落。标题级别与现有场景一致 |
| **Optimization** | S_body | 替换或精简现有段落。不改变整体结构 |
| **SkillDefect** | S_body | 修复错误指令 / 追加缺失的场景。**同时**在 S_appendix 踩坑日志中记录 |
| **ExecutionLapse** | S_appendix | 在踩坑日志中追加一条新条目。**不碰** S_body 的任何内容 |

### 踩坑日志格式

```markdown
### 踩坑日志

`YYYY-MM-DD | 类型 | 问题描述 | 解决方案`

2026-05-27 | SkillDefect | 某场景的边界条件未覆盖，导致特定参数传递失败 | 在 S_body 中新增对应场景段落
2026-05-25 | ExecutionLapse | 执行时未按 skill 要求设置必要参数 | 在 S_appendix 追加醒目标记

<!-- 新条目追加在此行之上，保持最新在最上面 -->
```

---

## 步骤四：Auditor 检查

修改完成后，在执行验证前先做 5 项快速检查。

### 检查项

| 编号 | 检查项 | 检查内容 |
|:----:|--------|---------|
| C1 | **格式完整性** | triggers 是否覆盖 description 中提到的所有场景？frontmatter 格式是否正确？ |
| C2 | **内部一致性** | 是否存在互相矛盾的指令？同一种场景是否有两套相反的说法？ |
| C3 | **可执行性** | 引用的命令、路径、工具是否实际可用？ |
| C4 | **泄露检测** | 是否包含硬编码的特定路径、文件名或"死答案"？应使用通用占位符 |
| C5 | **触发覆盖** | triggers 是否包含足够的常见关键词让 Agent 能激活这个 skill？Do NOT trigger 是否排除了不相关的场景？ |

### 执行方式

```bash
# C1: 检查 frontmatter 完整性
grep -E "^(name|description|Triggers):" SKILL.md

# C3: 检查引用工具的可用性
# 提取所有 ```bash 代码块中的命令，检查关键命令是否存在

# C4: 搜索硬编码路径
grep -n "C:\\\\Users\\\\\|/home/\|~/" SKILL.md  # 检查是否有用户特定路径
```

五项全部通过后再进入步骤五。

---

## 步骤五：Clean Agent 验证

修改后的 skill 是否真的有效，要让一个**全新的、不知道你做了哪些修改的 Agent** 去执行测试任务来判断。

### 验证流程

1. 准备一个测试任务（与步骤一中发现失败的场景相同）
2. 派一个 clean subagent，加载修改后的 skill，执行测试任务
3. 检查执行结果
4. 如果仍然失败：回到步骤二重新分类（可能是分类判断有误，或者修改内容不到位）

### 通过标准

- clean subagent 执行测试任务成功
- clean subagent 确实激活了该 skill（检查轨迹中确认 skill 被加载和使用）
- 执行过程中没有静默绕过（skill 被加载了但 Agent 选择不用）

---

## 真实案例

在一次 Windows 终端编码问题修复场景中，执行该工作流：

1. 发现边界场景：命令参数字符串在 shell 间传递时中文编码损坏，skill 提供的所有输出编码修复方案均无法解决
2. 反思分类 → SkillDefect（故障链路在参数传递环节，不在输出环节）
3. 修改 S_body → 新增场景，通过 subprocess 传参列表绕过 shell 编码层
4. 更新 S_appendix → 踩坑日志记录
5. Clean Agent 验证 → 修复通过

---

## 常见陷阱

- ❌ **跳过分类直接改**：每次失败都往 skill 里加规则 → skill 越来越臃肿自相矛盾
- ❌ **分不清 SkillDefect 和 ExecutionLapse**：执行失误当成 skill 缺陷来修 → 把正确的 skill 改坏
- ❌ **改完不验证**：修改了但 clean Agent 实际用不上 → 静默绕过
- ❌ **body 和 appendix 混在一起**：踩坑记录混入核心指令 → 下次改 body 时误删重要提醒