agent-Specialization/agentskills/sub-agent-guide/SKILL.md

name	description
sub-agent-guide	子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体用于并行处理多个完全独立的任务，如：并行生成多个模块的文档、同时进行多个网络调研、大范围信息搜集（分析项目认证实现、收集系统信息）。关键限制：子智能体之间无法通信，看不到主对话历史，只能通过文件共享信息。不适合需要协作或精细控制的任务（如代码重构）。

子智能体使用指南

核心原则

一个子智能体 = 一个完整的独立任务

子智能体拥有完整工具能力，但与主智能体和其他子智能体完全隔离。它们看不到你的对话历史，无法互相通信，只能通过文件系统共享信息。

何时使用

适合：

• 并行独立任务：同时生成3个不同模块的文档、并行测试多个功能
• 大范围信息搜集：分析项目的前后端认证实现、收集系统硬件信息（CPU/GPU/内存）
• 网络调研：搜索并整理英伟达2025财报、对比 Claude 和 ChatGPT 最新模型
• 耗时分析任务：大规模日志分析、代码库依赖关系梳理

不适合：

• 任务之间需要频繁协调（子智能体无法互相通信）
• 简单快速的任务（创建子智能体有开销）
• 需要你参与决策的任务（子智能体是自主运行的）
• 代码重构等需要精细控制的任务（建议自己完成）

任务描述的艺术

子智能体看不到你的对话历史，task 参数是它收到的唯一指令。

关键要素：

1. 明确的目标 - 要做什么，产出什么
2. 清晰的范围 - 操作哪些文件/目录
3. 具体的交付物 - 生成什么文件，放在哪里
4. 完成标准 - 什么算完成

好的示例：

# 信息搜集任务
分析项目的前后端认证与鉴权实现：
1. 查找所有与认证相关的代码文件（login, auth, jwt, session 等关键词）
2. 分析前端如何存储和传递认证信息
3. 分析后端如何验证和管理用户权限
4. 整理成一份技术文档（auth_analysis.md），包含流程图和代码位置

# 网络调研任务
搜索并整理英伟达2025年的财报信息：
1. 搜索英伟达2025年Q1-Q4财报
2. 提取关键财务数据（营收、利润、增长率）
3. 分析主要业务板块表现
4. 生成结构化报告（nvidia_2025_report.md）

# 系统信息收集
收集当前计算机的硬件和系统信息：
1. CPU 架构、型号、核心数
2. GPU 型号、显存、驱动版本
3. 内存大小、系统版本
4. 保存为 system_info.md

避免：

• ❌ "帮我分析一下认证代码" - 太模糊
• ❌ "如果发现问题请告诉我" - 子智能体无法与你交互
• ❌ "先做 A，然后等我确认再做 B" - 子智能体是一次性执行的

交付目录设计

deliverables_dir 必须是不存在的新目录，子智能体会把所有成果放在这里。

命名建议：

sub_agent_results/task_description/  # 清晰描述任务
sub_agent_results/module_a_docs/     # 按模块组织
sub_agent_results/refactor_auth/     # 按功能组织

避免：

• ❌ 使用已存在的目录（会报错）
• ❌ 使用绝对路径（必须是相对于项目根目录的相对路径）
• ❌ 使用通用名称如 "output" "result"（多个子智能体会冲突）

并行执行模式

创建多个子智能体时，确保它们的任务完全独立：

# ✅ 好的并行：各自独立
create_sub_agent(agent_id=1, task="生成模块 A 的文档", deliverables_dir="docs/module_a", ...)
create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="docs/module_b", ...)

# ✅ 好的并行：信息搜集
create_sub_agent(agent_id=1, task="搜索并整理 Claude 最新模型信息", deliverables_dir="research/claude", ...)
create_sub_agent(agent_id=2, task="搜索并整理 ChatGPT 最新模型信息", deliverables_dir="research/chatgpt", ...)
# 等两个都完成后，你再对比整合

# ✅ 好的并行：系统调研
create_sub_agent(agent_id=1, task="分析前端认证实现", deliverables_dir="analysis/frontend_auth", ...)
create_sub_agent(agent_id=2, task="分析后端鉴权实现", deliverables_dir="analysis/backend_auth", ...)

# 等待所有完成
wait_sub_agent(agent_id=1)
wait_sub_agent(agent_id=2)

# ❌ 不好的并行：需要协作
create_sub_agent(agent_id=1, task="收集数据", ...)
create_sub_agent(agent_id=2, task="分析数据", ...)  # 依赖子智能体1的结果
# 子智能体2不知道子智能体1什么时候完成，无法协调

常见陷阱

1. 期望子智能体协作

❌ 错误：

create_sub_agent(agent_id=1, task="实现功能 A，完成后通知子智能体2")
create_sub_agent(agent_id=2, task="等待子智能体1完成，然后实现功能 B")

子智能体之间无法通信。如果任务有依赖，应该：

• 方案1：顺序执行（等第一个完成后再创建第二个）
• 方案2：让一个子智能体完成整个流程

2. 忘记子智能体看不到对话历史

❌ 错误：

# 你在对话中说："我们要重构认证模块，使用 JWT 替代 Session"
create_sub_agent(task="按照我们讨论的方案重构认证模块")

✅ 正确：

create_sub_agent(task="""
重构 src/auth/ 目录的认证模块：
- 移除基于 Session 的认证
- 实现基于 JWT 的认证
- 保持 API 接口不变
- 更新相关测试
""")

3. 超时时间设置不当

子智能体超时后会被强制终止，已完成的工作可能丢失。

经验值：

• 文档生成：600-900 秒
• 信息搜集/网络调研：900-1800 秒
• 大规模分析：1800-3600 秒

宁可设置得长一些，也不要让子智能体因超时而前功尽弃。

4. agent_id 重复使用

同一对话中，每个 agent_id 只能使用一次。如果子智能体失败需要重试，必须使用新的 agent_id。

create_sub_agent(agent_id=1, ...)  # 失败了
# ❌ create_sub_agent(agent_id=1, ...)  # 会报错
# ✅ create_sub_agent(agent_id=2, ...)  # 使用新的 ID

检查结果

子智能体完成后，检查 success 字段和 deliverables_dir：

result = wait_sub_agent(agent_id=1)

if result["success"]:
    # 读取交付目录中的文件
    deliverables = result["deliverables_dir"]
    # 处理生成的文件...
else:
    # 检查失败原因
    if result["status"] == "timeout":
        # 考虑增加 timeout_seconds 重试
    else:
        # 查看 result["message"] 了解失败原因
        # 检查交付目录中是否有部分结果

thinking_mode 选择

• fast：常规任务（文档生成、信息搜集、数据分析）
• thinking：需要深度推理的任务（架构设计、复杂算法分析、安全审计）

大多数情况下使用 fast 即可。

总结

子智能体的本质是并行执行完全独立的任务。如果你发现自己在设计子智能体之间的协作流程，那可能不应该使用子智能体，而应该自己顺序执行这些步骤。