企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习

本篇指南围绕 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 类标准文件与模板对应关系如下：

下文以 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 正文，模板给出了四个固定小节：

1. # <Team Name>—— 2~3 句话说明：团队做什么、用什么协作模式、解决什么问题。这是技能被加载后模型最先读到的语义锚点。
2. ## Workflow—— 按顺序列出核心步骤（每步一句话），并链接到workflow.md获取完整剧本。
3. ## Role Responsibilities—— 角色职责表，三列：Role | Responsibility | Output。Output列应给出该角色产出的文件路径（如.team/reports/T1_developer.md），方便 leader 校验任务完成度。
4. ## File List—— 文件清单，逐项说明每个文件的用途。

模板中的相对链接（如[workflow.md](https://link.gitcode.com/i/0abe6f5735d9d0fc36cce8b95bc033b8)、roles/*.md）在生成团队技能时指向团队技能目录内部的兄弟文件，这是模板作为"待填充骨架"的正常形态；实际生成后的技能文件集内部保持这一布局。

team-skill-creator 的生成流程：七步产出标准文件集

team-skill-creator/SKILL.md将生成过程固定为七个步骤，必须按顺序执行：

1. 收集需求（Gather Requirements）：向用户询问四个问题（若用户未完整提供）：
   • 团队做什么？（一句话目标）
   • 有多少角色？每个角色叫什么、做什么？
   • 角色如何协作？（Parallel / Debate / Pipeline / Quality Gate / Hybrid）
   • 每个角色依赖哪些外部 skills / tools？
2. 选择协作模式（Select Collaboration Pattern）：根据用户描述，从"协作模式分类表"中选择 1~3 个模式的组合。
3. 创建目录（Create Directory）：建立<team-skill-name>/目录及roles/子目录。
4. 从模板生成 5 类文件（Generate 5 File Types from Templates）：读取对应模板、填充占位符。
5. 角色文件聚焦检查（Focus Check on roles/*.md）：每个角色文件必须包含## Inline Persona for Teammate小节——框架不会自动加载该小节，leader 必须显式读取并粘贴进 dispatch prompt。
6. 自检（Self-Check）：逐项核对"生成后自检清单"。
7. 告知放置路径（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内置了五类模式的判别规则：

选择提示（用户措辞到模式的映射）：

• "几个角色同时分析不同方面" → 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）。

三条值得关注的设计机制：

1. 直接点对点辩论：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. 辩论固定 2 轮：bind.md同时声明debate_rounds_limit=2与min_debate_rounds=2，leader 在 Step 5 完成轮次校验，不允许提前终止——这是对抗辩论模式防止"敷衍收敛"的关键约束。
3. 角色文件的可读性：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，向模型声明可用技能。配套的演进 railTeamSkillRail（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/目录后即被框架自动加载，在下一次协作中直接调用。

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习