当你在用 Cursor、Claude Code 或任何 AI 编程助手时，有没有想过：为什么装了几个 skill，agent 就突然"会"了新东西？Harness 又是什么？这些概念之间到底是什么关系？
📌 一句话速览
| 概念 | 是什么 | 类比 |
|---|---|---|
| Skill | Agent 会的单个能力 | 乐高积木 |
| Harness | 跑 Agent 的平台/框架 | 乐高底板 + 机械臂 |
| Workflow | 多个 Skill 串联的流程 | 乐高拼装步骤 |
如果你时间紧，记住这张表就够了。下面展开讲清楚。
1️⃣ Skill：Agent 的"技能包"
什么是 Skill？
Skill 是一份 Markdown 指南，告诉 Agent 在特定场景下该怎么做。
比如你装了一个叫 tdd 的 skill，Agent 就知道：
- 用户说"测试驱动开发"时，该读这份指南
- 先写测试，再写实现，最后重构
- 遵循红-绿-重构的流程
Skill 长什么样？
---
name: tdd
description: >-
Test-driven development. Use when the user wants to build
features test-first, mentions "red-green-refactor"...
---
# TDD
## When to Use
- User wants test-first development
- Mentions "red-green-refactor"
## Steps
1. Write a failing test (Red)
2. Make it pass (Green)
3. Refactor while keeping tests green
Skill 的触发机制
Skill 不会自动运行，而是被自动匹配：
| 行为 | 说明 |
|---|---|
| 自动匹配 | Agent 根据 skill 描述里的关键词判断该不该读 |
| 自动执行 | ❌ 不会——skill 只是指南，Agent 读完后按流程走 |
举个例子：
tdd的描述写着："Use when user mentions 'red-green-refactor'"- 当你说"帮我用 TDD 方式加个功能"，Agent 匹配到意图 → 读 skill → 按流程走
- 你不提 TDD，它就不会主动跑
Skill 的作用域
| 类型 | 路径 | 说明 |
|---|---|---|
| 全局 Skill | ~/.agents/skills/ |
你个人工具箱，任何项目都能用 |
| 项目 Skill | 项目/.qoder/skills/ |
跟着仓库走，只在该项目生效 |
全局 skill 是"你走到哪都能用的通用能力"，项目 skill 是"这个仓库专属的知识"。
2️⃣ Harness：Agent 的"舞台"
什么是 Harness？
Harness 不是 Agent 的能力，而是承载 Agent 运行的基础设施。
| 角色 | 是什么 | 例子 |
|---|---|---|
| Agent | 干活的 AI | Claude、GPT、Qoder |
| Harness | 跑 Agent 的平台 | Cursor IDE、Claude Code CLI、Qoder |
类比理解
想象一个剧院：
┌─────────────────────────────────────┐
│ Harness（剧院） │
│ ┌───────────────────────────────┐ │
│ │ Agent（演员） │ │
│ │ - 读剧本（Skill） │ │
│ │ - 表演（执行任务） │ │
│ │ - 输出（交付结果） │ │
│ └───────────────────────────────┘ │
│ │
│ Harness 负责： │
│ • 开演/散场（启动/停止 Agent） │
│ • 提供道具（工具：读文件、写代码） │
│ • 舞台管理（会话状态、错误恢复） │
│ • 多演员协调（多 Agent 编排） │
└─────────────────────────────────────┘
Harness 具体做什么？
| 职责 | 说明 |
|---|---|
| 生命周期管理 | 启动、暂停、恢复、终止 Agent |
| 提供工具 | 读文件、写代码、执行命令、搜索 |
| 会话状态 | 记住对话上下文，跨轮次保持连贯 |
| 错误恢复 | Agent 挂了自动重启 |
| 多 Agent 协调 | 同时跑多个 Agent 时负责调度 |
具体到你的环境：
- Qoder/Cursor 就是 Harness
- 它启动我（Agent），给我工具，管理我们的对话
- 它决定把哪些 skill 注入给我看
- 如果我挂了，它负责恢复
我（Agent）不是 Harness：
- 我只是在 Harness 里运行的 AI
- 我会读 skill、匹配意图、执行任务
- 但我不能控制自己的启动/停止
3️⃣ Workflow：Skill 的"串联"
什么是 Workflow？
Workflow 是多个 Skill 按顺序串联成的流程。
单个 Skill 解决单个问题，Workflow 解决"从开始到完成"的完整任务。
一个典型的开发 Workflow
brainstorming → writing-plans → tdd → executing-plans → verification → code-review
↓ ↓ ↓ ↓ ↓ ↓
想清楚 写计划 先写测试 按步骤实现 完成前自检 主动求审
| 阶段 | Skill | 作用 |
|---|---|---|
| 1. 需求澄清 | brainstorming / grill-me |
拷问需求，想清楚要做什么 |
| 2. 规格定义 | writing-plans / spec-driven |
写成文档，明确边界 |
| 3. 测试先行 | tdd / test-driven-development |
先写测试，再写实现 |
| 4. 按步实现 | executing-plans |
按计划一步步做 |
| 5. 完成自检 | verification-before-completion |
交活前验证 |
| 6. 请求审查 | requesting-code-review |
主动求审 |
谁来驱动 Workflow？
| 方式 | 说明 |
|---|---|
| 手动 | 你一个个 slash command 调用 |
| Harness 自动 | 按规则自动串联（如 /better-harness） |
| Agent 自主 | Agent 根据任务匹配 skill 描述，自动按序调用 |
4️⃣ 三者的关系
层次图
┌─────────────────────────────────────────────┐
│ Harness（基础设施层） │
│ 启动/停止 Agent，提供工具，管理状态 │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ Workflow（流程编排层） │ │
│ │ 决定 Skill 的调用顺序和条件分支 │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Skill A │→│ Skill B │→│ Skill C │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ ↑ ↑ ↑ │ │
│ │ 执行单元 执行单元 执行单元 │ │
│ └───────────────────────────────────────┘ │
│ │
│ Agent（AI 执行者） │
│ 读 Skill，匹配意图，执行任务 │
└─────────────────────────────────────────────┘
一句话总结
Skill 是零件，Workflow 是装配图，Harness 是工厂流水线。
- Skill：单个能力，解决单个问题
- Workflow：多个 Skill 串联，解决完整任务
- Harness：运行环境，让 Agent 能跑起来
5️⃣ 为什么这些概念重要？
对开发者
| 理解这些概念后，你能... | 之前可能... |
|---|---|
| 知道为什么装了某个 skill，Agent 就"会"了新东西 | 困惑"为什么我的 Agent 不会做 X" |
| 区分"Agent 不会"和"Harness 不支持" | 出了问题不知道找谁 |
| 自己写 Workflow 串联多个 Skill | 每次手动一个个调用 |
| 选择适合的 Harness（Cursor/Claude Code/Qoder） | 盲目跟风用工具 |
对团队
- Skill 可以共享：团队写好的 skill 放进仓库，新人入职就"会"了
- Workflow 可以标准化：把"需求→设计→开发→测试→审查"固化成 skill 串联
- Harness 可以选型：不同团队选不同 Harness，skill 通用
6️⃣ 常见误区
❌ 误区 1：Skill 是 Harness 的功能
正解：Skill 是独立的知识包，Harness 只是运行环境。同一个 skill 可以在不同 Harness 里用。
❌ 误区 2：装了 Skill 就自动生效
正解：Skill 需要被触发。Agent 根据描述匹配意图，不是装了就会用。
❌ 误区 3：Workflow 是 Harness 的一部分
正解：Workflow 是流程编排，Harness 可以支持 Workflow，但两者是不同层次的概念。
❌ 误区 4：Agent 自己就是 Harness
正解：Agent 是在 Harness 里运行的 AI。Harness 负责启动/停止 Agent，提供工具。
7️⃣ 小结
| 概念 | 一句话 | 类比 |
|---|---|---|
| Skill | Agent 会的单个能力 | 乐高积木 |
| Harness | 跑 Agent 的平台 | 乐高底板 + 机械臂 |
| Workflow | 多个 Skill 串联的流程 | 乐高拼装步骤 |
下次你装 skill、用 Agent、或者纠结选哪个 Harness 时，想想这三个层次：
- Skill：我需要什么能力？
- Workflow：这些能力怎么串联？
- Harness：在哪个平台上跑？
想清楚了，AI 编程助手的用法就不再是黑箱。
本文基于实际使用 Cursor、Claude Code、Qoder 等工具的经验总结，概念解释力求准确，示例为说明用途的简化表达。
