Harness Agent定义文件教程：必须写全的6大区块

Harness Agent定义文件教程：必须写全的6大区块

【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness

Harness 是 Claude Code 的一个元技能（meta-skill），能根据你描述的业务领域自动设计出一支Agent 团队，并生成这些 Agent 使用的技能文件。它落地的核心产物就是Agent 定义文件：.claude/agents/目录下的每一个.md文件，都完整定义了一位专业 Agent 的角色、工作原则、输入输出格式与协作方式。本教程基于 Harness 官方模板和真实团队示例，带你逐个拆解 Agent 定义文件必须写全的 6 大区块，新手也能照着写出可复用的 Agent。

为什么 Agent 必须写成定义文件？

Harness 有一条硬性规则：每个 Agent 必须以.claude/agents/{name}.md独立文件定义，禁止把角色直接写进调用 prompt 里（规则原文见 SKILL.md 的 Phase 3）。原因有三点：

即使使用general-purpose、Explore这类内置类型，也要生成定义文件：内置类型通过subagent_type参数指定，而角色、原则和协议全部写进文件里。

Agent 定义文件 6 大区块速览

官方定义结构模板在 agent-design-patterns.md。一个完整的 Agent 定义文件 = 头部 frontmatter + 正文 6 个 H2 区块，骨架如下：

--- name: agent-name description: "1-2句角色说明。触发关键词罗列。" --- # Agent 名称 — 角色一句话摘要 你是 [领域] 的 [角色] 专家。 ## 核心角色 ## 工作原则 ## 输入/输出协议 ## 团队通信协议 ## 错误处理 ## 协作

本教程的区块划分：frontmatter 是区块 1；核心角色、工作原则、输入/输出协议、团队通信协议是区块 2~5；末尾的"错误处理"与"协作"两节合并构成区块 6。下面逐个讲清楚每块写什么、怎么写。

区块 1｜Frontmatter：Agent 的"营业执照"

文件顶部的 YAML frontmatter 只有两个字段，但都必填：

• name：Agent 唯一名称，与文件名对应（如worldbuilder→worldbuilder.md），也是调用时subagent_type的取值
• description：1-2 句角色说明 + 触发关键词，回答"这个人擅长什么"，要具体到领域和产出物

frontmatter 之后紧跟两行"门面"：# Agent 名称 — 角色一句话摘要的标题，以及"你是 [领域] 的 [角色] 专家"的定位句。它们和 frontmatter 一起构成文件的身份头。

⚠️ 常见坑：description 只写"负责调研"这类空话。对照官方示例——"构建 SF 小说世界观的专家。设计物理法则、社会结构、技术水平、历史。"——具体才有用。

区块 2｜核心角色：这个 Agent 具体干什么

用编号列表写 1~4 条职责，关键是具体、可检验：

• ✅ "定义世界的物理法则与技术水平"
• ❌ "负责世界观相关工作"

每条职责都应能对应到一次实际产出，模糊的职责会让 Agent 在运行时自行发挥，结果不可预期。

区块 3｜工作原则：遇到模糊时的判断标准

原则告诉 Agent如何做取舍。官方 SF 世界观 Agent 的三条原则就很有参考价值：

• 内部一致性优先——设定之间不能互相矛盾
• 用"如果这个技术存在？"的连锁提问推演世界的派生影响
• 世界观为故事服务——避免妨碍剧情的过度设定

好的原则是"可执行的标准"，而不是"追求高质量"这种空话。

区块 4｜输入/输出协议：从哪拿、往哪放

这一区块定义 Agent 的"工作接口"，必须写全三要素：

📌 输出路径注意 Harness 的命名约定{phase}_{agent}_{artifact}.{ext}（如01_analyst_requirements.md）。这是编排器推荐的文件式数据传递方式，中间产物统一存_workspace/，便于事后验证与审计追溯，规则详见 SKILL.md 数据传递协议。

区块 5｜团队通信协议：跟谁说话、说什么

Agent 团队模式（Harness 的默认执行模式）下，这一区块必填，需要写清三件事：

1. 消息接收：从谁那里收什么消息（如"从 science-consultant 接收科学错误反馈 → 修正设定"）
2. 消息发送：发给谁、发什么（如"向 character-designer 发送社会结构、阶级体系信息"）
3. 任务请求：从共享任务列表中请求哪类任务

团队模式下，成员之间用SendMessage直接对话、用TaskCreate共享任务列表自行协调，不必事事经过负责人。通信协议写得越明确，团队协作质量越高——写不出"发给谁"，运行时就只能靠 Agent 临场发挥。

区块 6｜错误处理与协作：兜底与边界

最后一块包含两节内容：

• 错误处理：失败时做什么、超时时做什么。例如官方漫画审核 Agent："图像加载失败 → 该格判 REDO；重绘 2 次仍 REDO → 带警告强制 PASS"
• 协作：与其他 Agent 的关系——向谁提供信息、采纳谁的反馈

即使你认为"不会出错"也要写。Harness 的验证阶段会做干运行测试，逐条检查每个错误场景是否都有可执行的兜底路径（检查项见 SKILL.md 的 6-5 节）。

完整真实示例：worldbuilder.md

Team Examples 中收录了 SF 小说团队的worldbuilder.md（世界观设计 Agent）完整文件，是 6 大区块齐全的样板：

--- name: worldbuilder description: "构建 SF 小说世界观的专家。设计物理法则、社会结构、技术水平、历史。" --- # Worldbuilder — SF 世界观设计专家 你是 SF 小说的世界观设计专家。 ## 核心角色 1. 定义世界的物理法则与技术水平 2. 设计社会结构、政治体系、经济系统 ... ## 团队通信协议 - 向 character-designer：SendMessage 社会结构、阶级体系信息 ...

同文件里还有调研团队、漫画制作团队、代码评审团队、代码迁移团队等 5 个真实团队的配置，配合 orchestrator-template.md 的编排器模板，可以覆盖从单 Agent 到多 Agent 团队的几乎所有场景。

验收自检清单

写完文件后，对照官方 产出示例清单 逐项检查：

• 文件位于.claude/agents/{name}.md，name 与文件名一致
• frontmatter 的 name、description 齐全，description 含具体触发关键词
• 核心角色是 1~4 条具体职责
• 工作原则是可执行的标准，不是口号
• 输入/输出协议写明路径与格式，遵循_workspace/命名约定
• 团队通信协议写清收/发对象与任务请求范围（团队模式必填）
• 错误处理覆盖"失败"与"超时"两种情形
• 协作节写明与其他 Agent 的关系

总结

Agent 定义文件就是 Harness 团队里的"人事档案"：frontmatter 是名片，核心角色是岗位说明书，工作原则是行为准则，输入/输出协议是工作接口，团队通信协议是通讯录，错误处理与协作是兜底和边界。6 大区块写全，这位 Agent 就能在任何会话、任何团队里被直接复用——这也是用 Harness 搭建可靠多智能体系统的地基。

想继续深入：

• Agent 分离标准、6 种架构模式与复用设计：agent-design-patterns.md
• 5 分钟快速上手，从一句话生成完整团队：docs/quickstart.md
• 技能编写规范：skill-writing-guide.md
• 项目入口与全部功能说明：README.md

【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness