---
name: harness-skill-generator
description: "引导用户从 0 构建一个基于 Harness 工程的 Skill。适用于具有一定复杂度的任务场景(多阶段、多分支、需要质检、需要状态持久化)。不适用于简单的单步任务或纯 prompt 优化。触发词:'创建 Skill'、'新建 Skill'、'做一个 Skill'、'构建 Skill'、'skill generator'、'harness skill'。"
---

# Harness Skill Generator

## 边界

### 做
- 引导用户从 0 创建一个**基于 Harness 工程**的新 Skill
- 适用于**有复杂度的任务**:多阶段、多分支、需要质检、需要状态持久化
- 输出完整的 Skill 文件结构(SKILL.md + references/ + templates/)
- 引导用户走完 Problem Scan → Architecture → Scaffold → Fill → Test Run → Delivery 全流程

### 不做
- 不修改/升级已有 Skill(那是另一个流程)
- 不执行 Skill(创建完交给 Agent 用)
- 不做简单的 prompt 优化(没有阶段/质检/状态需求的任务不需要 harness)
- 不做 Skill 的市场推广/发布

### 判断规则
- 如果任务是**单步完成**(如:翻译一段话、回答一个问题)→ 不需要 harness,建议直接写 prompt
- 如果任务是**多步但无分支**(如:固定的 3 步流程)→ 可以用简化版 harness(无 Checkpoint)
- 如果任务是**多步 + 多分支 + 需要质检 + 需要状态**→ 进入本 Skill

---

## 工作流

```
Phase 0  Trigger            用户说"创建/新建一个 Skill" → 判断是否需要 harness
   ▼
Phase 1  Problem Scan       收集痛点 + 边界定义 + 人类工作流拆解 + 步骤归属审查
   └ ★Checkpoint 1         确认:痛点 / 边界 / 人类工作流 / 步骤归属
   ▼
Phase 2  Agent Architecture 方案调研 → 总体方案概览 → 逐项细化每个阶段
   └ ★Checkpoint 2         分两步:先确认总体方案,再逐项确认每个阶段
   ▼
Phase 3  Scaffold           生成文件结构 + SKILL.md 骨架
   ▼
Phase 4  Fill               逐个填写 references/,逐个与用户确认
   └ ★Checkpoint 3         验收:用一个小样本跑通,人类确认方向对
   ▼
Phase 5  Test Run           用真实任务试运行完整流程 + 修复
   ▼
Phase 6  Delivery           交付 + 交付确认 + 项目复盘
```

---

## 质检协议

| 节点 | 方式 | 产物 | 为什么 |
|---|---|---|---|
| Phase 1-2 各阶段 | 主 Agent 内联自查（上下文矛盾排查） | 无 | 主 Agent 热上下文，自己检查关联性 |
| Phase 3 骨架 | 主 Agent 内联自查 | 无 | 文件少，结构简单 |
| Phase 4 每个 reference | 用户逐个确认 | 无 | 逐个确认方向对 |
| Phase 4 整体审查 | SubAgent + 消息返回 | 无 | 交付前一致性审查 |
| Phase 4 Checkpoint 3 | 用户跑小样本验收 | checkpoint-3-review.md | 定调，防止方向错 |
| Phase 5 试运行 | 用户 + Agent 联合验收 | test-run-report.md | 最终验收 |

---

## Phase 0 - Trigger

**做什么:** 判断用户需求是否需要 harness 工程。

| 用户说的话 | 该做的 |
|---|---|
| "创建/新建一个 Skill" | 进入 Phase 1 |
| "帮我做一个 XX 的自动化流程" | 进入 Phase 1(可能是 harness 场景) |
| "帮我写一个 prompt" | 问清楚:是单步任务还是多步?如果是多步 → 推荐进入本 Skill |
| "修改/升级已有的 Skill" | 停下来:不在本 Skill 范围内 |

**自检:** 用户的任务是否有以下特征?
- 多阶段(>2 步)?
- 多分支(不同情况走不同路径)?
- 需要质检(产出质量不稳定)?
- 需要状态持久化(中断后要恢复)?

如果有 2 个以上 → 推荐用 harness 工程。
如果只有 1 个或没有 → 建议用简化方案。

---

## Phase 1 - Problem Scan

**做什么:** 定义问题 → 收集痛点 → 拆解人类工作流 → 步骤归属审查。

### 1.1 问题定义(★先定义问题,再谈痛点)

问用户两个问题:

**问题 1:** "你想利用这个 Skill 解决什么问题?"
- 不是"你让 AI 做什么",而是"你面临什么问题"

**问题 2:** "你在自己处理这个问题的过程中,想要解决的痛点是什么?"
- 痛点是问题解决方案的延伸思考

**记录为 `plan/problem-definition.md`。**

### 1.2 边界定义

基于问题和痛点,定义 Skill 的边界:
- **做什么:** 3-5 种明确的任务类型
- **不做什么:** 容易混淆但不属于本 Skill 的场景
- **判断规则:** 什么情况下不进本 Skill

### 1.3 人类工作流拆解

问用户:**"如果是你人工来做这件事,你的步骤是什么?"**

要求用户按步骤列出,每步包括:做什么 / 输入 / 输出 / 最容易出错的地方。

**记录为 `plan/human-workflow.md`。**

### 1.4 步骤归属审查

对人类描述的每个步骤,判断:这一步是解决当前问题所必需的,还是属于另一个独立任务?
- 去掉这一步,核心问题仍能被解决 → 属于另一个任务,拆出去
- 这一步的产出是另一步的"预设前提" → 本 Skill 接收其产出作为输入

### ★Checkpoint 1 - Problem & Boundary

确认项:
1. **痛点是否准确?** - 有没有遗漏?有没有不是真正痛点的?
2. **边界是否合理?** - 做什么/不做什么是否清晰?
3. **人类工作流是否完整?** - 有没有跳步?有没有隐含步骤?
4. **★ 步骤归属是否正确?** - 有没有把另一个独立任务的内容混进来?

铁律:每项独立确认,禁止打包。

---

## Phase 2 - Agent Architecture(★核心阶段)

**做什么:** 基于人类工作流,设计 Agent 工作流。

### 2.1 方案调研(★必须先于方案设计)

**在设计 Agent 方案之前,先调研市场上的成熟解决方案。**

**调研优先级(从高到低):**

| 优先级 | 方案来源 | 适用场景 | 举例 |
|---|---|---|---|
| **P0 · 市场成熟方案** | 权威 SaaS 软件 / 行业标准工具 / 官方 API | 通用任务,市场上已有成熟方案 | 数据采集用 Apify/八爪鱼;内容生成用 Jasper/Copy.ai |
| **P1 · Agent 原生能力** | Agent 自身能力(脚本/API/推理)替代人类操作 | 市场方案不适用,但 Agent 有更高效的方式 | 人类逐个复制 → Agent 批量提取;人类手动分析 → Agent 结构化推理 |
| **P2 · 模拟人类行为** | 浏览器自动化 / RPA / 模拟点击 | 平台限制严格,无法用 API 或脚本绕过 | 小红书/BOSS直聘等有反爬机制的平台 |

**★ 特殊情况:平台限制场景**

当任务涉及小红书、BOSS 直聘等有反爬虫/反 AI 政策的平台时,优先级反转:
- **P0:模拟人类行为**(合理操作间隔 + 时间波动 + 人机行为模拟)
- P1:官方 API(如有)
- P2:批量脚本(高风险,易被封)

**调研输出 `plan/solution-research.md`,包含:**
- 调研了哪些方案
- 各方案的优劣对比
- 最终选择的方案及理由

### 2.2 总体方案概览(★先给整体,再逐项细化)

**不能一步生成所有工作阶段方案。** 必须分两步:

**第一步:给用户看总体方案概览**

```markdown
## 总体方案

### 工作阶段概览
| 阶段 | 名称 | 一句话描述 | 依赖 |
|---|---|---|---|
| Phase 0 | [名称] | [做什么] | - |
| Phase 1 | [名称] | [做什么] | Phase 0 |
| ... | ... | ... | ... |

### 分支路由概览
[如有分支,列出条件和路径]

### 关键决策点
[列出需要人类确认的节点]
```

**等用户确认总体方案后,进入第二步。**

**第二步:逐项细化每个阶段**

对每个阶段,逐一与用户确认:
1. **阶段名称**
2. **方法**(具体怎么做)
3. **步骤**(拆成子步骤)
4. **输入/产出**(格式和存放位置)
5. **质检方案**(内联自查/SubAgent/写文件)
6. **状态文件**(哪些决策需要持久化)
7. **是否需要 Checkpoint**

**每个阶段确认完毕后,才能进入下一个阶段的细化。**

**输出 `plan/agent-workflow.md`,包含所有阶段的完整定义。**

### 2.3 分支路由设计

**如果任务有多条路径,设计路由规则:**

```markdown
## 分支路由

| 条件 | 路径 | 优先级 |
|---|---|---|
| [条件1] | 方案A | P0 |
| [条件2] | 方案B | P1 |
| [条件3] | 方案C | P2 |
| 无法判断 | ★停下来问用户 | - |
```

**铁律:无法判断时必须停下来问用户,不能猜。**

### 2.4 质检矩阵设计

对每个阶段设计质检方式:

| 阶段 | 产出 | 风险 | 质检方式 | 产物 |
|---|---|---|---|---|
| [阶段名] | [文件] | 低/中/高/最高 | 内联自查/SubAgent+消息/SubAgent+文件 | [无/review/xxx.md] |

### 2.5 状态文件设计

定义项目工作区结构:

```
<project>/
├── [状态文件1]     [作用]
├── [状态文件2]     [作用]
├── [产出目录]/
│   └── [产出文件]
└── review/
    └── [审查文件](按需)
```

### ★Checkpoint 2 - Architecture

**分两步确认:**

**第一步:确认总体方案**
1. **方案调研是否充分?** - 有没有遗漏更优的市场方案?
2. **总体阶段划分是否合理?** - 有没有多余/缺失的阶段?
3. **分支路由是否完整?** - 有没有未覆盖的情况?

**第二步:逐项确认每个阶段**

对每个阶段,独立确认:
1. **方法是否最优?** - 是否有更好的 Agent 方案?
2. **产出是否明确?** - 格式、存放位置、命名规范
3. **质检是否匹配?** - 风险和质检力度是否对应
4. **状态文件是否最少化?** - 有没有可以合并的文件

铁律:每个阶段独立确认,不能一次性全部确认。Agent 必须解释每个设计决策的理由。

---

## Phase 3 - Scaffold

**做什么:** 生成 Skill 文件结构 + SKILL.md 骨架。

### 3.1 创建目录结构

```bash
mkdir -p <skill-name>/{references,templates}
```

### 3.2 生成 SKILL.md 骨架

按以下模板生成,只填骨架不填细节:

```markdown
---
name: <skill-name>
description: "<一句话描述> + 触发词:<触发词列表>"
---

# <Skill 名称>

## 边界
[从 Phase 1.2 填入]

## 工作流
[从 Phase 2.2 填入阶段名和箭头]

## 质检协议
[从 Phase 2.4 填入表格]

## Phase 0 - [名称]
做什么(2-3行)
必读:references/xxx.md

## Phase 1 - [名称]
...

## ★Checkpoint N - [名称] ★硬节点
确认项:[清单]
铁律:[约束]

## 铁律
[从 Phase 2 提取最重要的 3-7 条约束]
```

### 3.3 生成 references/ 目录

为每个阶段创建一个 reference 文件骨架:

```
references/
├── [阶段1]-rules.md      Phase 1 的详细规则
├── [阶段2]-template.md   Phase 2 的模板
├── quality-checklist.md   质检清单
├── style-contract.md      风格契约(如有输出格式要求)
├── branch-routing.md      分支路由规则(如有多分支)
└── repair-rules.md        修复规则
```

---

## Phase 4 - Fill

**做什么:** 逐个填写 references/ 的内容,**逐个与用户确认**。

### 填写顺序

```
1. quality-checklist.md    质检清单(先定义标准,再写规则)
2. style-contract.md       风格契约(如有)
3. [阶段1]-rules.md       第一个阶段的详细规则
4. [阶段2]-template.md    第二个阶段的模板
5. ...                     按阶段顺序逐个填写
6. branch-routing.md       分支路由规则(最后写,因为需要全局视角)
7. repair-rules.md         修复规则(最后写)
```

### 每个 reference 的内容要求

每个 reference 文件必须包含:
1. **做什么**(3-5 行)
2. **怎么做**(详细步骤)
3. **输入/产出**(明确格式)
4. **反模式**(❌ 不能做什么)
5. **自检清单**(Agent 完成后自查的 3-5 条)

### ★ 每个 reference 完成后 - 逐个与用户确认

**不能一次性全部写完让用户自己看。必须逐个确认:**

1. 写完一个 reference
2. 展示给用户,说明这个 reference 覆盖的内容
3. **等用户确认通过后,再写下一个**

### ★ 整体审查(★所有 reference 完成后,交付前)

**所有 reference 写完 + 用户逐个确认通过后,交付前进行一次整体审查:**

1. 用 SubAgent 对整个 Skill 进行一致性审查(以消息返回 pass/fail)
2. 审查要点:reference 之间是否矛盾、SKILL.md 与 references 是否一致、质检协议是否完整
3. fail 项直接修
4. 修复后进入 Checkpoint 3

### ★Checkpoint 3 - Sample Test(★硬节点 · 必须停)

**在填写完所有 reference 后,用一个小样本跑通 Phase 0-2(至少到第一个 Checkpoint)。**

确认项:
1. **触发是否正确?** - Skill 能否被正确识别和进入?
2. **第一个阶段的产出是否符合预期?** - 格式/内容/结构是否对?
3. **reference 是否够用?** - Agent 读了 reference 后能否正确执行?

铁律:人类必须验收小样本后才能进入 Phase 5 全量测试。

---

## Phase 5 - Test Run

**做什么:** 用一个**真实的、中等复杂度**的任务试运行完整 Skill 流程。

### 试运行清单

- [ ] Phase 0:触发是否正确?
- [ ] Phase 1:输入标准化是否完整?
- [ ] Checkpoint 1:确认项是否完整?有没有遗漏?
- [ ] Phase 2:构建是否顺利?
- [ ] Phase 2+:质检是否发现了真问题?
- [ ] Checkpoint 3:交付流程是否完整?
- [ ] 状态文件:中断后能否恢复?
- [ ] 文件结构:是否清晰有序?

### 迭代原则

1. 每次试运行**只修一个问题**
2. 修 bug 而不是重设计(除非发现根本性设计缺陷)
3. 问题记录到 `test-run-report.md`

---

## Phase 6 - Delivery

**做什么:** 交付完整 Skill + 使用说明 + 项目复盘。

### 6.1 交付物

1. **完整的 Skill 目录**(SKILL.md + references/ + templates/)
2. **使用说明**(README.md:怎么安装、怎么触发、注意事项)
3. **test-run-report.md**(试运行结果 + 修复记录)
4. **project-summary.md**(项目总结 + 复盘)

### 6.2 安装

- Skill 安装到 `/Users/ii/.agents/skills/<skill-name>/`(所有 Agent 共享)
- 更新 AGENTS.md 的 Skill 列表(如需要)
- 记录到 MEMORY.md 的 Skill 创建记录

### 6.3 交付确认(★必须与用户确认)

**交付后不能直接结束。必须与用户确认:**

1. **交付是否完整?** - 用户是否收到了所有需要的文件?
2. **任务是否结束?** - 用户是否还有未完成的需求?

**只有用户确认"任务完成"后,才能进入复盘。**

### 6.4 项目复盘(★任务结束后的必做步骤)

**生成 `project-summary.md`,包含:**

```markdown
# 项目总结 - [Skill 名称]

## 1. 任务目标
[简要描述最初的任务目标]

## 2. 交付评估
- [ ] 交付物是否完整?
- [ ] 是否满足任务目标?
- [ ] 用户是否确认完成?

## 3. 过程记录

### 3.1 是否有返工/中断/调整?
| # | 阶段 | 调整内容 | 原因分析 |
|---|---|---|---|
| 1 | [阶段] | [改了什么] | [为什么] |

### 3.2 调整原因分类

对每个调整,分析根因:
- **A. 任务目标不清晰** - 当初需求细化不够,导致中途改方向
- **B. 用户预期调整** - 用户在过程中改变了想法(合理调整)
- **C. Skill 能力不足** - Skill 的设计有缺陷,无法处理某种情况

### 3.3 Skill 优化建议

如果调整原因属于 C(Skill 能力不足),记录优化建议:
| # | 问题 | 优化建议 | 优先级 |
|---|---|---|---|
| 1 | [问题] | [怎么改 Skill] | P0/P1/P2 |

## 4. 总结
[一句话总结本次项目的关键收获]
```

**复盘的目的:** 把本次项目的经验变成下次可以复用的资产。如果发现 Skill 的缺陷,记录优化建议,方便后续迭代。

---

## 铁律

1. **人类方案是起点,不是终点** - Agent 必须基于人类方案提出更优的 Agent 方案,不能照搬
2. **方案调研优先** - 先看市场成熟方案,再想 Agent 原生能力,最后才考虑模拟人类行为
3. **无法判断时必须停下来问** - 分支路由不确定时,禁止猜测
4. **先小后大** - Checkpoint 3 必须用小样本验收,不能跳过直接全量
5. **文件分层** - 状态文件 / 产出文件 / 脚本必须分开放,禁止散落根目录
6. **状态持久化** - 关键决策必须落盘到文件,不能只存在聊天上下文
7. **禁止静默替用户选择** - Checkpoint 的每项决策必须独立确认
8. **逐项细化,不一次性铺开** - Phase 2 先给总体方案,再逐阶段细化;Phase 4 逐个写 reference 并确认
9. **交付后必须复盘** - 不能交付就结束,必须确认交付完整性 + 生成项目总结

---

## 文件读取指南(渐进加载)

| 阶段 | 必读 | 按需查 |
|---|---|---|
| Phase 0 Trigger | -- | -- |
| Phase 1 Problem Scan | references/problem-scan-guide.md | -- |
| Phase 2 Architecture | references/architecture-guide.md, references/branch-routing.md | references/quality-matrix.md |
| Phase 3 Scaffold | references/scaffold-template.md | -- |
| Phase 4 Fill | references/reference-writing-guide.md, references/style-contract.md | references/quality-checklist.md |
| Phase 5 Test Run | references/test-run-guide.md | -- |
| Phase 6 Delivery | -- | -- |