Agent-almanac create-team

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/create-team" ~/.claude/skills/pjt222-agent-almanac-create-team-8fecb6 && rm -rf "$T"

manifest: i18n/zh-CN/skills/create-team/SKILL.md

source content

创建新团队

定义协调两个或多个智能体完成需要多视角、多专业或多阶段任务的多智能体团队组合。生成的团队文件与团队注册表集成，可在 Claude Code 中按名称激活。

适用场景

任务需要单个智能体无法提供的多视角（例如代码审查 + 安全审计 + 架构审查）
需要角色分配和交接模式一致的反复出现的协作工作流
现有智能体组合被反复使用，应予以正式化
复杂流程自然分解为由不同智能体处理的阶段或专业
需要为基于 sprint、基于管道或并行工作定义协调团队

输入

必需：团队名称（小写连字符格式，例如
```
data-pipeline-review
```
）
必需：团队目的（一段描述需要多个智能体的问题）
必需：负责人智能体（必须存在于
```
agents/_registry.yml
```
）
可选：协调模式（默认：hub-and-spoke）。选项之一：
```
hub-and-spoke
```
、
```
sequential
```
、
```
parallel
```
、
```
timeboxed
```
、
```
adaptive
```
可选：成员数量（默认：3-4；建议范围：2-5）
可选：源材料（要正式化的现有工作流、操作手册或临时团队组合）

步骤

第 1 步：定义团队目的

阐明需要多个智能体协作的问题。有效的团队目的必须回答：

此团队交付什么结果？（例如综合审查报告、已部署应用、sprint 增量）
为什么单个智能体无法完成？ 识别至少两种所需的不同专业或视角。
何时应激活此团队？ 定义触发条件。

将目的写成一段话，供人或智能体阅读以决定是否激活此团队。

预期结果： 清晰的段落解释团队的价值主张，识别至少两种不同专业。

失败处理： 若无法识别两种不同专业，任务可能不需要团队。改用具有多种技能的单个智能体。

第 2 步：选择负责人智能体

负责人智能体协调团队。从

agents/_registry.yml

中选择以下特征的智能体：

在团队主要输出的相关领域具有专业知识
能将传入请求分解为其他成员的子任务
能将多位审查者的结果综合为连贯的可交付成果

# 列出所有可用智能体
grep "^  - id:" agents/_registry.yml

负责人还必须作为成员出现在团队组合中（负责人始终是成员）。

预期结果： 选定一个智能体作为负责人，已确认其存在于智能体注册表中。

失败处理： 若没有现有智能体适合负责人角色，先使用

create-agent

技能（或手动使用

agents/_template.md

）创建一个。不要创建负责人不存在智能体定义的团队。

第 3 步：选择成员智能体

选择 2-5 个成员（包括负责人），职责清晰且不重叠。为每个成员定义：

id：来自智能体注册表的智能体名称
role：简短头衔（例如"Quality Reviewer"、"Security Auditor"、"Architecture Reviewer"）
responsibilities：一句话描述此成员做其他成员不做的什么

# 验证每个候选智能体存在
grep "id: agent-name-here" agents/_registry.yml

验证无重叠：没有两个成员应有相同的主要职责。若职责重叠，要么合并角色，要么明确边界。

预期结果： 选定 2-5 个成员，每人有唯一角色和明确职责，均已在智能体注册表中确认。

失败处理： 若所需智能体不存在，先创建它。若两个成员之间职责重叠，重写以明确边界或删除其中一个成员。

第 4 步：选择协调模式

选择最适合团队工作流的模式。五种模式及其使用场景：

模式	适用场景	示例团队
hub-and-spoke	负责人分配任务、收集结果并综合。最适合审查和审计工作流。	r-package-review、gxp-compliance-validation、ml-data-science-review
sequential	每个智能体基于前一个智能体的输出构建。最适合管道和分阶段工作流。	fullstack-web-dev、tending
parallel	所有智能体同时处理独立子任务。最适合子任务无依赖时。	devops-platform-engineering
timeboxed	工作组织为固定时长的迭代。最适合有积压的持续项目工作。	scrum-team
adaptive	团队根据任务自组织。最适合未知或高度可变的任务。	opaque-team

决策指南：

若负责人必须看到所有结果才能产出：hub-and-spoke
若智能体 B 需要智能体 A 的输出才能开始：sequential
若所有智能体都能在不看到彼此输出的情况下工作：parallel
若工作跨多次迭代且有规划仪式：timeboxed
若无法提前预测任务结构：adaptive

预期结果： 选定一种协调模式，并有清晰的选择理由。

失败处理： 若不确定，默认使用 hub-and-spoke。它是最常见的模式，适用于大多数审查和分析工作流。

第 5 步：设计任务分解

定义典型传入请求如何在团队成员间拆分。按阶段构建：

设置阶段：负责人分析请求并创建任务
执行阶段：每个成员处理的内容（根据协调模式，可以是并行、顺序或按 sprint）
综合阶段：如何收集结果并产生最终可交付成果

为每个成员列出其在典型请求中会执行的 3-5 个具体任务。这些任务同时出现在"任务分解"散文章节和 CONFIG 块的

tasks

列表中。

预期结果： 按阶段结构的分解，每个成员有具体任务，与所选协调模式匹配。

失败处理： 若任务太模糊（例如"审查事物"），使其具体化（例如"对照 tidyverse 风格指南审查代码风格，检查测试覆盖率，评估错误消息质量"）。

第 6 步：编写团队文件

复制模板并填写所有章节：

cp teams/_template.md teams/<team-name>.md

按顺序填写以下章节：

YAML 前置元数据：
```
name
```
、
```
description
```
、
```
lead
```
、
```
version
```
（"1.0.0"）、
```
author
```
、
```
created
```
、
```
updated
```
、
```
tags
```
、
```
coordination
```
、
```
members[]
```
（每个包含 id、role、responsibilities）
标题：
```
# Team Name
```
（人类可读，标题格式）
简介：一段摘要
目的：此团队存在的原因，结合了哪些专业
团队组合：包含成员、智能体、角色、关注点列的表格
协调模式：散文描述加流程的 ASCII 图
任务分解：按阶段分解，每个成员有具体任务
配置：机器可读的 CONFIG 块（见第 7 步）
使用场景：2-3 个具体场景和示例用户提示
限制：3-5 个已知约束
参见：成员智能体文件及相关技能/团队的链接

预期结果： 完整的团队文件，所有章节填写完毕，模板中无剩余占位文本。

失败处理： 与现有团队文件（例如

teams/r-package-review.md

）对比以验证结构。搜索模板占位字符串如"your-team-name"或"another-agent"查找未填写的章节。

第 7 步：编写 CONFIG 块

<!-- CONFIG:START -->

和

<!-- CONFIG:END -->

标记之间的 CONFIG 块为工具提供机器可读的 YAML。按如下结构：

<!-- CONFIG:START -->
```yaml
team:
  name: <team-name>
  lead: <lead-agent-id>
  coordination: <pattern>
  members:
    - agent: <agent-id>
      role: <role-title>
      subagent_type: <agent-id>  # Claude Code subagent type for spawning
    # ... repeat for each member
  tasks:
    - name: <task-name>
      assignee: <agent-id>
      description: <one-line description>
    # ... repeat for each task
    - name: synthesize-report  # final task if hub-and-spoke
      assignee: <lead-agent-id>
      description: <synthesis description>
      blocked_by: [<prior-task-names>]  # for dependency ordering
```
<!-- CONFIG:END -->

subagent_type

字段映射到 Claude Code 智能体类型。对于

.claude/agents/

中定义的智能体，使用智能体 id 作为 subagent_type。使用

blocked_by

表达任务依赖（例如综合被所有审查任务阻塞）。

预期结果： CONFIG 块是有效的 YAML，所有智能体与前置元数据成员列表中的一致，任务依赖形成有效的 DAG（无循环）。

失败处理： 验证 YAML 语法。验证任务列表中的每个

assignee

与成员列表中的

agent

匹配。检查

blocked_by

仅引用列表中之前定义的任务名称。

第 8 步：添加到注册表

编辑

teams/_registry.yml

添加新团队：

- id: <team-name>
  path: <team-name>.md
  lead: <lead-agent-id>
  members: [<agent-id-1>, <agent-id-2>, ...]
  coordination: <pattern>
  description: <one-line description matching frontmatter>

在注册表顶部更新

total_teams

数量（目前为 8；添加一个团队后变为 9）。

# 验证条目已添加
grep "id: <team-name>" teams/_registry.yml

预期结果： 新条目出现在注册表中，

total_teams

数量递增 1。

失败处理： 若团队名称已存在于注册表，选择不同的名称或更新现有条目。验证 YAML 缩进与现有条目匹配。

第 9 步：运行 README 自动化

从更新后的注册表重新生成 README 文件：

npm run update-readmes

这会更新

teams/README.md

中的动态章节以及任何引用团队数据的带有

<!-- AUTO:START -->

<!-- AUTO:END -->

标记的其他文件。

预期结果： 命令以 0 退出，

teams/README.md

现在列出新团队。

失败处理： 运行

npm run check-readmes

查看哪些文件不同步。若脚本失败，验证存储库根目录存在

package.json

且

js-yaml

已安装（

npm install

）。

第 10 步：验证团队激活

测试团队在 Claude Code 中是否可以激活：

User: Use the <team-name> team to <typical task description>

Claude Code 应当：

在
```
teams/<team-name>.md
```
找到团队文件
识别负责人和成员
遵循文件中描述的协调模式

预期结果： Claude Code 识别团队名称，识别正确的负责人和成员，并遵循协调模式。

失败处理： 验证团队文件位于

teams/<team-name>.md

（而非子目录中）。检查所有成员智能体是否存在于

.claude/agents/

（链接到

agents/

）。确认团队已列入

teams/_registry.yml

。

第 11 步：生成翻译文件

所有团队必须执行。 本步骤同时适用于人类作者和遵循此流程的 AI 智能体。不要跳过——遗漏的翻译会累积为过期的待办积压。

在提交新团队后，立即为全部 4 种受支持的语言环境生成翻译文件：

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- teams <team-name> "$locale"
done

然后翻译每个文件中生成的散文内容（代码块和 ID 保持英文）。最后重新生成状态文件：

npm run translation:status

预期结果： 在

i18n/{de,zh-CN,ja,es}/teams/<team-name>.md

创建 4 个文件，全部的

source_commit

与当前 HEAD 匹配。

npm run validate:translations

针对新团队显示 0 条过期警告。

失败处理： 若脚手架失败，请确认该团队存在于

teams/_registry.yml

中。若状态文件未更新，请显式运行

npm run translation:status

——CI 不会自动触发该命令。

验证清单

团队文件存在于
```
teams/<team-name>.md
```
YAML 前置元数据解析无误
所有必需前置元数据字段存在：
```
name
```
、
```
description
```
、
```
lead
```
、
```
version
```
、
```
author
```
、
```
coordination
```
、
```
members[]
```
前置元数据中每个成员都有
```
id
```
、
```
role
```
和
```
responsibilities
```
所有章节存在：Purpose、Team Composition、Coordination Pattern、Task Decomposition、Configuration、Usage Scenarios、Limitations、See Also

CONFIG 块存在于

<!-- CONFIG:START -->

和

<!-- CONFIG:END -->

标记之间

CONFIG 块 YAML 有效且可解析
所有成员智能体 id 存在于
```
agents/_registry.yml
```
负责人智能体出现在成员列表中
没有两个成员共有相同的主要职责
团队已列入
```
teams/_registry.yml
```
，路径、负责人、成员和协调模式正确
注册表中的
```
total_teams
```
数量已递增
```
npm run update-readmes
```
无错误完成

常见问题

成员过多：超过 5 个成员的团队协调困难。分发任务和综合结果的开销超过额外视角带来的收益。拆分为两个团队或减少到必要专业。
职责重叠：若两个成员都"审查代码质量"，他们的发现会冲突，负责人浪费时间去重。每个成员必须有明确不同的关注领域。
协调模式选择错误：当智能体需要彼此输出时使用 hub-and-spoke（应该是 sequential），或当智能体可以独立工作时使用 sequential（应该是 parallel）。回顾第 4 步中的决策指南。
缺少 CONFIG 块：CONFIG 块不是可选的散文装饰。工具读取它来用
```
TeamCreate
```
自动创建团队。没有它，团队文件只是人类可读的，无法以程序方式激活。
负责人不在成员列表中：负责人还必须作为成员出现，有自己的角色和职责。只"协调"而不做实质性工作的负责人浪费了一个名额。给负责人一个具体的审查或综合职责。