harness-skill-generator

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 0 - Trigger

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

自检: 用户的任务是否有以下特征?

• 多阶段(>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 方案之前,先调研市场上的成熟解决方案。

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

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

当任务涉及小红书、BOSS 直聘等有反爬虫/反 AI 政策的平台时,优先级反转:

• P0:模拟人类行为(合理操作间隔 + 时间波动 + 人机行为模拟)
• P1:官方 API(如有)
• P2:批量脚本(高风险,易被封)

调研输出 plan/solution-research.md,包含:

• 调研了哪些方案
• 各方案的优劣对比
• 最终选择的方案及理由

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

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

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

## 总体方案

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

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

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

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

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

对每个阶段,逐一与用户确认:

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

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

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

2.3 分支路由设计

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

## 分支路由

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

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

2.4 质检矩阵设计

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

2.5 状态文件设计

定义项目工作区结构:

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

★Checkpoint 2 - Architecture

分两步确认:

第一步:确认总体方案

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

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

对每个阶段,独立确认:

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

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

---

Phase 3 - Scaffold

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

3.1 创建目录结构

mkdir -p /{references,templates}

3.2 生成 SKILL.md 骨架

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

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

# 

## 边界
[从 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//(所有 Agent 共享)
• 更新 AGENTS.md 的 Skill 列表(如需要)
• 记录到 MEMORY.md 的 Skill 创建记录

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

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

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

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

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

生成 project-summary.md,包含:

# 项目总结 - [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. 交付后必须复盘 - 不能交付就结束,必须确认交付完整性 + 生成项目总结

---

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