openJiuwen 团队技能(Team Skill)创建指南:从 SKILL.md 模板到可复用的多智能体协作模式
openJiuwen 团队技能(Team Skill)创建指南:从 SKILL.md 模板到可复用的多智能体协作模式
本篇指南围绕 openJiuwen agent-core-java 仓库中的 team-skill-creator 技能与其 templates/SKILL.md 模板,完整讲解如何把一套多角色协作模式沉淀为可被框架自动发现的团队技能(Team Skill)。读完本文,你将掌握团队技能 5 类标准文件的字段语义、协作模式分类与选择技巧、生成流程与自检清单,并能参照仓库内置示例(dev_test_parallel 与 investment-analysis-team)独立创建自己的团队技能文件集。
Team Skill 与模板的定位
在 com.openjiuwen.agentteams 框架中,Team Skill(团队技能)是把一套多智能体协作模式固化为可复用模板的载体。它由 5 类文件组成,放在团队工作空间的 skills/ 目录或全局 ~/.openjiuwen/workspace/skills/ 目录下,框架(SkillUseRail)在成员启动时自动扫描、发现并加载。
team-skill-creator 是仓库内建的一项技能(.claude/skills/team-skill-creator/SKILL.md),它的职责是:当用户想把某个协作模式固化为团队技能时,引导生成一整套标准文件集。其核心输入正是 templates/ 目录下的 5 个模板文件,其中 SKILL.md 模板是团队的元数据入口,也是 leader 在 ReAct 循环中发现该技能后首先读取的编排依据。
5 类标准文件与模板对应关系如下:
| 生成文件 | 对应模板 | 本质职责 |
|---|---|---|
<team-skill-name>/SKILL.md |
templates/SKILL.md | 团队元数据:name/version/kind/roles 总览 |
<team-skill-name>/roles/<role>.md |
templates/role.md | 角色定义:Identity/Success Criteria/Boundary/Output Schema/Inline Persona |
<team-skill-name>/workflow.md |
templates/workflow.md | 执行剧本:流程图 + Step 0~N + Final Report |
<team-skill-name>/bind.md |
templates/bind.md | 约束与失败处理:资源/行为/失败三类约束 |
<team-skill-name>/dependencies.yaml |
templates/dependencies.yaml | 外部依赖声明:skills/tools/global_dependencies |
下文以 SKILL.md 模板为核心展开,其余模板作为配套说明。
SKILL.md 模板逐字段解析
SKILL.md 模板(.claude/skills/team-skill-creator/templates/SKILL.md)分为 front matter(YAML 元数据) 与 正文(Markdown 说明) 两部分,全文不足 50 行,却承担着团队身份声明、成员概览与文件清单三项关键职责。
front matter:机器可读的团队元数据
---
name: <team-skill-name> # Team skill name, kebab-case, matches directory name
version: "1.0" # Version number
kind: team-skill # Fixed value, identifies this as a team skill
roles: # Role overview, leader reads this during ReAct for orchestration
- id: <role-1> # Role id, kebab-case, matches roles/<role-1>.md filename
purpose: "<one-sentence responsibility>" # What this role does
skills: [<skill-name>] # External skills this role depends on; empty array means pure reasoning
tools: [<tool-name>] # Tools this role needs, e.g., python3/curl/jq
- id: <role-2>
purpose: "<one-sentence responsibility>"
skills: []
tools: []
---
各字段语义如下:
name:技能名,必须是 kebab-case(连字符小写),且与目录名一致。框架按目录名识别技能,目录与name不一致会导致发现与调用错位。version:版本号,建议字符串形式(如"1.0"),配合TeamSkillRail的演进机制,在迭代协作模式时可标记版本变更。kind:固定值team-skill,标识这是一个团队技能。该字段有实际代码语义——TeamSkillCreateRail.java中TEAM_SKILL_KINDS = Set.of("team-skill", "swarm-skill"),它在扫描skillsDir下的候选目录时,会逐个读取SKILL.md并解析顶层kind:字段(parseTopLevelKind),只有命中该集合的目录才会被识别为已知团队技能,用于检测"本次协作是否已经用过某个团队技能"。因此kind写错会直接影响演进 rail 的判断。roles:角色总览数组。leader 在 ReAct 编排时以它为全局视角。每个角色条目包含:id:角色标识,kebab-case,且必须与roles/<id>.md文件名一致(自检清单第一条即验证此项)。purpose:一句话职责描述,帮助 leader 在任务分发时快速判断该角色适合承接哪类任务。skills:该角色依赖的外部技能名数组。空数组表示纯推理角色(pure reasoning)。tools:该角色需要的工具,如python3/curl/jq。
front matter 中的
roles是"总览",真正的角色细节(人设、成功标准、输出模板)在roles/*.md中,两者通过id一一对应。
正文:给 leader 看的人类可读摘要
front matter 之后是 Markdown 正文,模板给出了四个固定小节:
# <Team Name>—— 2~3 句话说明:团队做什么、用什么协作模式、解决什么问题。这是技能被加载后模型最先读到的语义锚点。## Workflow—— 按顺序列出核心步骤(每步一句话),并链接到workflow.md获取完整剧本。## Role Responsibilities—— 角色职责表,三列:Role | Responsibility | Output。Output列应给出该角色产出的文件路径(如.team/reports/T1_developer.md),方便 leader 校验任务完成度。## File List—— 文件清单,逐项说明每个文件的用途。
模板中的相对链接(如 <a href="https://link.gitcode.com/i/31979338576aa8226c089e919872e003" target="_blank">workflow.md</a>、roles/*.md)在生成团队技能时指向团队技能目录内部的兄弟文件,这是模板作为"待填充骨架"的正常形态;实际生成后的技能文件集内部保持这一布局。
team-skill-creator 的生成流程:七步产出标准文件集
team-skill-creator/SKILL.md 将生成过程固定为七个步骤,必须按顺序执行:
- 收集需求(Gather Requirements):向用户询问四个问题(若用户未完整提供):
- 团队做什么?(一句话目标)
- 有多少角色?每个角色叫什么、做什么?
- 角色如何协作?(Parallel / Debate / Pipeline / Quality Gate / Hybrid)
- 每个角色依赖哪些外部 skills / tools?
- 选择协作模式(Select Collaboration Pattern):根据用户描述,从"协作模式分类表"中选择 1~3 个模式的组合。
- 创建目录(Create Directory):建立
<team-skill-name>/目录及roles/子目录。 - 从模板生成 5 类文件(Generate 5 File Types from Templates):读取对应模板、填充占位符。
- 角色文件聚焦检查(Focus Check on roles/*.md):每个角色文件必须包含
## Inline Persona for Teammate小节——框架不会自动加载该小节,leader 必须显式读取并粘贴进 dispatch prompt。 - 自检(Self-Check):逐项核对"生成后自检清单"。
- 告知放置路径(Inform Placement Path):告诉用户将生成的目录放到
~/.openjiuwen/workspace/skills/或团队工作空间skills/下,框架才能发现它。
从源码看,第 2 步的"模式选择"并非纯人工决策——框架的演进 rail 会在运行时主动触发创建诉求:当 leader 调用 spawn_member 达到阈值(默认 2 次)且本轮未使用任何已知团队技能时,TeamSkillCreateRail.maybeEnqueueCreationFollowUp 会向 leader 排发一条 follow-up prompt,引导其先用 ask_user 与用户确认,再调用 team-skill-creator 技能执行创建,新技能保存到 skillsDir(默认团队工作空间 skills/)。也就是说,创建团队技能的触发点既可以是用户主动发起,也可以由框架在多次成员 spawn 后自动提议。
协作模式分类:如何为 SKILL.md 选择 roles 与 workflow 形态
roles 数组怎么声明、workflow.md 怎么编排、bind.md 怎么写约束,都取决于所选协作模式。team-skill-creator 内置了五类模式的判别规则:
| 模式 | 特征 | 工作流结构 | bind.md 关键约束 |
|---|---|---|---|
| Parallel Decomposition(并行分解) | 多角色同时分析不同维度,彼此不可见 | 并行 spawn → 各自输出报告 → leader 汇总 | max_parallel_teammates / 分析师彼此不可见 |
| Adversarial Debate(对抗辩论) | 两个对立角色直接点对点交换观点 | Round 1 独立 → Round 2 直接辩论 → 输出结论 | debate_rounds_limit / min_debate_rounds / 直接点对点 > leader 转发 |
| Pipeline(流水线) | 上游输出自动投递到下游(通过依赖) | T1 → T2 → T3,靠 dependencies 串联 | create_task(dependencies=[...]) / member_results_delivery 自动投递 |
| Quality Gate(质量门控) | 上游完成后 leader 先校验质量再放行下游 | 上游 → 质量检查 → 下游 | 门控失败回流 / max_retry_per_step |
| Hybrid(混合) | 上述模式的组合(如 investment-analysis-team = 并行 + 辩论 + 流水线) | 多步骤组合 | 多重约束,按阶段写可见性规则 |
选择提示(用户措辞到模式的映射):
- "几个角色同时分析不同方面" → Parallel Decomposition
- "正方 vs 反方 / 乐观 vs 悲观 / 支持 vs 反对" → Adversarial Debate
- "上游完成后再继续下游" → Pipeline
- "必须检查质量后才能继续" → Quality Gate
- "既要并行又要辩论" → Hybrid
模式决定后,roles 数组的声明方式也随之确定:并行模式的角色 skills/tools 各自独立;辩论模式需要成对声明对立角色(如乐观/悲观研究员);流水线模式则通过 workflow.md 中的任务依赖和 bind.md 中的可见性规则来约束阶段间数据流。
最小完整示例:两角色并行团队
team-skill-creator 提供了最小完整参照样例 .claude/skills/team-skill-creator/references/dev_test_parallel/,对应"一个写代码、一个写测试,两者并行"的用户诉求。其 SKILL.md 是模板填充后的直接形态:
---
name: dev-test-parallel
version: "1.0"
kind: team-skill
roles:
- id: developer
purpose: "Implement functional code as described by the user"
skills: []
tools: [python3]
- id: tester
purpose: "Write test cases for the functional code"
skills: []
tools: [python3]
---
正文部分依次给出团队简介("Two people in parallel... invisible to each other, leader consolidates both outputs at the end")、三行工作流摘要(Pre-flight → Parallel Execution → Final Report)、角色职责表(developer 输出 .team/reports/T1_developer.md,tester 输出 .team/reports/T2_tester.md)与文件清单。
该样例展示了模板的关键约定:
- 输出文件命名:统一采用
.team/reports/T<序号>_<角色>_<产物>.md格式,如T1_developer.md、T2_tester.md,最终报告为T3_final_report.md。这一格式贯穿workflow.md、role.md与自检清单,保证团队内文件路径一致、leader 可校验。 - 角色边界:
developer.md的 Boundary 明确"Forbidden: Do NOT write test cases"、tester 反向禁止实现功能代码——防止角色重叠是团队技能设计的基本原则(对应bind.md的 "No cross-modification")。 - Inline Persona 的双重安全:
role.md模板中,正文的## Output Schema用标准markdown 代码块包裹,而 `## Inline Persona for Teammate` 小节特意用 **裸 `包裹**(不带markdown语言标记)——这样 leader 提取该小节粘贴进 dispatch prompt 时不会产生嵌套代码块错误。team-skill-creator` 的 SKILL.md 明确提示这是刻意设计。
配套的 workflow.md 将该团队的步骤展开为:Step 0 Pre-flight(leader 读取 dependencies.yaml 验证 python3,缺失即终止,required: true)→ Step 1 Parallel Execution(developer + tester 并行 spawn,彼此不可见,质量门控为"两个文件都存在且含完整代码块")→ Final Report(leader 用 verbatim quoting(原文引用) 把两份输出原样并入 T3_final_report.md,不做摘要)。bind.md 则给出了 max_parallel_teammates=2、total_wall_clock_budget=10min、total_token_budget=16,000、per_role_token_limit=8,000、max_retry_per_step=2 等资源约束,以及"Step 1 完全隔离 / Final Report leader 可见"的分阶段可见性规则和逐场景失败处理表。
实战示例:investment-analysis-team 的混合模式
仓库中最完整的实战样例是 examples/agent_teams/skills/investment-analysis-team/,一个 Debate pattern (B+A+C) 的 8 角色投资分析团队:并行分解(4 分析师)+ 对抗辩论(乐观/悲观研究员直接点对点辩论)+ 专业化流水线(质量门控 + 风控决策)。
其 SKILL.md 的 front matter 声明了 7 个角色(fundamental-analyst / technical-analyst / digital-media-analyst / macro-analyst / optimistic-researcher / pessimistic-researcher / portfolio-risk-controller),每个角色的 skills(如 gs_stock_financial_query、gs_stock_market_query、content-strategy)与 tools(python3/curl/jq)各不相同;正文给出 8 步工作流摘要、角色职责表与文件清单。对照模板可见,实战文件是模板的超集——它在 Role Responsibilities 表中额外增加了 When dispatched、Input、Key dependencies、Role file 四列,在 Files 表中明确了每个文件的读取时机(何时读 workflow.md、何时读 bind.md、何时读 roles/*.md)。
三条值得关注的设计机制:
- 直接点对点辩论:Round 2 中乐观/悲观研究员通过
send_message直接交换观点,无需 leader 转达。workflow.md 明确声明通信优先级:直接点对点交换(辩论强制)> 共享黑板 > Leader 转发(仅 fallback);bind.md 的 Behavioral Constraints 逐阶段写明可见性(Step 2/3 完全隔离、Step 4 直接双方可见、Step 5 leader 可见、Step 6 辩论结论可见)。从 AgentTeams.md 的实现说明看,这靠send_message工具 +MessageHandler.processUnreadMessages把对方消息 drain 进 ReAct 循环实现。 - 辩论固定 2 轮:
bind.md同时声明debate_rounds_limit=2与min_debate_rounds=2,leader 在 Step 5 完成轮次校验,不允许提前终止——这是对抗辩论模式防止"敷衍收敛"的关键约束。 - 角色文件的可读性:roles/fundamental-analyst.md 完整演示了
role.md模板的五个小节:Identity(人设引言 + 方法论)、Success Criteria(可量化的完成标准 + Focus areas)、Boundary(Forbidden/Mandatory 双向约束)、Output Schema(结构化输出模板)、Inline Persona for Teammate(可直接粘贴进 dispatch prompt 的完整人设块,含ROLE:/INPUTS YOU WILL RECEIVE/PROCESSING INSTRUCTIONS/OUTPUT FORMAT)。
依赖声明与 pre-flight 检查
dependencies.yaml 是团队技能的"启动自检依据"。模板(templates/dependencies.yaml)定义了三段结构:
skills:
- name: <skill-name> # External skill name
source: local # Source
required: false # false means degrade when missing, true means required
purpose: "<what this skill does>"
roles: # Which roles use it
- <role-name>
tools:
- name: python3
source: local
required: true # Tools are generally required: true
purpose: "<purpose>"
roles:
- <role-1>
- <role-2>
global_dependencies:
description: "<overall team dependency description>"
fallback_mode: "<degradation mode when dependencies are missing>"
community_enrichment: "<suggested community skills to find>"
skills段:外部技能依赖,通常required: false——缺失时角色降级为纯推理(inline-persona-only),团队仍可运行。tools段:工具依赖,一般required: true——如python3缺失则团队无法运行。global_dependencies段:全局说明,给出整体依赖描述、降级模式与社区技能补充建议。
workflow.md 模板的 Step 0(Pre-flight Dependency Check) 固定由 leader 执行:读取 dependencies.yaml、验证依赖可用性、向用户报告缺失项,由用户决定是否继续(Agent 不自动决定);required: true 缺失则终止,required: false 缺失则降级。investment-analysis-team 的 dependencies.yaml 是这一约定的大规模实例:4 个 gs_* / content-strategy 技能全部 required: false,python3 为 required: true,curl/jq 为 required: false,并在 global_dependencies.fallback_mode 声明"依赖技能缺失时运行在纯推理模式(inline-persona-only)"。
生成后自检清单:十项硬性校验
team-skill-creator 要求生成完 5 类文件后逐项核对自检清单(完整版见 .claude/skills/team-skill-creator/SKILL.md 的 "Post-Generation Self-Check List"):
- [ ]
SKILL.mdfront matter 包含kind: team-skill与roles总览 - [ ]
roles/下每个.md文件名与SKILL.md中的id一致 - [ ] 每个
roles/*.md包含全部五节:## Identity/## Success Criteria/## Boundary/## Output Schema/## Inline Persona for Teammate - [ ]
## Inline Persona for Teammate用裸```包裹(非嵌套 markdown 代码块),且含ROLE:/You MUST/INPUTS YOU WILL RECEIVE/PROCESSING INSTRUCTIONS/OUTPUT子节 - [ ]
workflow.md有步骤编号,每步含Executor/Input/Output/Quality Gate - [ ]
bind.md包含全部三节:Resource Constraints/Behavioral Constraints/Failure Handling - [ ]
dependencies.yaml中required: false的项缺失时可优雅降级 - [ ] 输出文件路径统一使用
.team/reports/T<序号>_<角色>_<产物>.md格式 - [ ] 角色间可见性规则与协作模式匹配(并行 = 彼此不可见,辩论 Round 2 = 直接可见)
- [ ] 已告知用户放置路径:
~/.openjiuwen/workspace/skills/或团队工作空间skills/
其中"Inline Persona"相关两条是整个体系中最易出错、也最影响运行效果的部分:框架不会自动加载 roles/*.md,若 leader 未显式 read_file 并提取粘贴,teammate 将失去人设与输出模板约束(.claude/skills/agent-team-guide/SKILL.md 的 Pitfall FAQ 中专门收录了"成员无人设/角色定义丢失"这一高频问题及对应解法)。
放置路径与框架侧发现机制
生成后的团队技能需放置在框架扫描目录内才会被加载,可用位置包括:
- 团队工作空间
skills/节点:~/.openjiuwen/.agent_teams/<team_name>/team-workspace/skills/ - 全局:
~/.openjiuwen/workspace/skills/ - 当前工作目录(
System.getProperty("user.dir"))
框架侧链路(见 AgentTeams.md 的 "Team Skill" 小节):TeamAgent.setupAgent() 构建 DeepAgentConfig 时默认打开 enableSkillDiscovery(true) 与 skillMode("all");HarnessFactory 在满足条件时自动追加 SkillUseRail(com.openjiuwen.harness.rails.SkillUseRail),它负责扫描上述目录、加载本地与远程技能(基于 mtime 签名增量热重载)、注册 list_skill 与 skill_tool 工具,并在 beforeModelCall 注入名为 skills 的 prompt section,向模型声明可用技能。配套的演进 rail TeamSkillRail(core/src/main/java/com/openjiuwen/harness/rails/skills/TeamSkillRail.java)在检测到全部任务完成时触发团队演进分析、沉淀协作经验。
结语:从模板到可复用协作资产的完整闭环
templates/SKILL.md 虽然只有几十行,却是整个团队技能体系的"入口契约":它以机器可读的 front matter 向框架与 leader 声明团队身份,以角色总览衔接 roles/*.md 的细节定义,以工作流摘要与文件清单指向 workflow.md / bind.md / dependencies.yaml 的完整约定。掌握这份模板,加上 team-skill-creator 的七步生成流程、五类协作模式判别、十项自检清单,你就能把一次成功的多智能体协作(如投资分析辩论团队)沉淀为可复用、可发现、可演进的团队技能资产,放进 skills/ 目录后即被框架自动加载,在下一次协作中直接调用。