SubAgent 用法学习

参考：Cursor 官方 - 子代理 | Cursor 官方 - Agent Skills

在 Cursor 中，子代理（Subagent） 是主 Agent 可以委派任务给的专业化 AI 助手。每个子代理在自己的上下文窗口里运行，处理特定类型的工作，把结果返回给父代理。用子代理可以：拆解复杂任务、并行开展工作、在主对话里保留上下文（减少主 Agent 的上下文占用和噪音）。

可在编辑器、CLI、Cloud Agents 中使用子代理。

---

一、子代理带来的好处

方面	说明
上下文隔离	每个子代理有独立上下文窗口，耗时的调研/探索不会占满主对话
并行执行	可同时启动多个子代理，在代码库不同部分并行工作
专门领域能力	通过自定义提示词、工具权限、模型，为子代理配置特定领域任务
可复用	自定义子代理可在多个项目间复用

---

二、内置子代理（无需配置，自动使用）

Cursor 内置三个子代理，用于自动处理上下文占用较大的操作：

子代理	用途	为何做成子代理
Explore	搜索并分析代码库	探索会生成大量中间结果，主上下文容易臃肿；用更快模型并行执行大量搜索
Bash	运行一系列 Shell 命令	命令输出冗长，隔离后父代理专注决策而非日志
Browser	通过 MCP 工具控制浏览器	浏览器交互产生噪声较多的 DOM 快照/截图，子代理过滤为更相关的结果

你不需要配置这些，Agent 会在合适的时候自动使用。

---

三、运行方式：前台 vs 后台

模式	行为	适合场景
前台	阻塞直到子代理完成，然后立即返回结果	需要其输出的串行任务
后台	立即返回，子代理独立运行	长时间运行的任务或并行工作流

后台子代理的输出会写入 ~/.cursor/subagents/，父代理可读取以检查进度。

---

四、子代理 vs Skill（详细对比）

Skill 文档：Cursor 官方 - Agent Skills

4.1 Skill 是什么（简要）

Agent Skills 是为 AI 智能体扩展专门能力的开放标准。一个 Skill 是：

• 可移植：适用于任何支持该标准的 Agent
• 受版本控制：以文件形式存在（如 .cursor/skills/），可进仓库或从 GitHub 安装
• 可操作：可包含脚本、模板、参考资料，Agent 用现有工具去执行
• 渐进式：按需加载资源（如 references/、scripts/），上下文更省

每个 Skill 是一个文件夹，内含 SKILL.md（YAML frontmatter + 指令）。Agent 启动时发现并加载所有技能，根据当前上下文决定何时调用；你也可以输入 / + 技能名 手动调用。Skill 没有独立上下文窗口，是在主 Agent 的同一对话里按指令和资源执行。

4.2 核心差异一览

维度	子代理（Subagent）	技能（Skill）
运行位置	自己的上下文窗口，独立于主对话	主 Agent 的上下文中，无单独窗口
上下文与 token	独立上下文 → 隔离噪音，但每个子代理单独耗 token；可并行多份	与主对话共享上下文；按需加载 Skill 内容，通常更省 token
典型形态	一个“专门干一类事”的 AI 助手（可多步推理、用工具）	一份“说明书 + 可选脚本/资料”，主 Agent 照着做
调用方式	主 Agent 自动委派，或你用 /子代理名 / 自然语言指定	Agent 根据描述自动选用，或你用 /技能名 显式调用（含 disable-model-invocation: true 时类似 slash 命令）
并行	可同时启动多个子代理并行工作	不涉及“多份 Agent”，只是主 Agent 按技能指令执行
适用任务	耗时调研、多步推理、需要隔离或独立校验、并行多工作流	单一用途、快速可重复、一次性可完成、不需要单独上下文

4.3 何时用子代理、何时用 Skill（对照表）

更适合用子代理的场景……	更适合用 Skill的场景……
需要为耗时的调研/探索隔离上下文（避免主对话被刷屏）	任务是单一用途：如“生成 changelog”“格式化 import”“写 commit message”
需要并行跑多个工作流（如同时审代码 + 更新文档）	希望有一个快速、可重复的操作，每次步骤类似
任务在多步骤中需要专业知识（如先方案再实现再验证）	任务可以一次性完成，不需要多轮独立推理
希望对工作成果做独立校验（如专门的 Verifier 子代理）	不需要单独上下文窗口，在主对话里完成即可
操作本身会产生大量中间结果（如大量搜索、长命令输出、浏览器快照）	主要是固定流程 + 少量资源（脚本、模板、参考文档）

简单自检：若你发现自己在为「生成 changelog」「格式化 import」「按模板生成某类文件」这类简单、单一、可重复的任务建子代理，更适合改成 Skill；若任务耗时长、多步、要隔离或并行，用子代理更合适。

4.4 Skill 的存放与调用（便于和子代理对比）

• 存放：项目级 .cursor/skills/ 或 .agents/skills/，用户级 ~/.cursor/skills/；每个技能一个文件夹，内含 SKILL.md，可带 scripts/、references/、assets/。
• 调用：Agent 根据 description 自动判断是否使用；或你在对话里输入 / 搜索技能名手动调用。若在 frontmatter 里设 disable-model-invocation: true，则只有显式 /技能名 时才会加载，行为类似传统 slash 命令。

4.5 小结：选子代理还是 Skill？

• 子代理：独立上下文、可并行、适合“交给另一个 Agent 专门跑完一块复杂/耗时/需要校验的工作”，代价是额外 token 和启动开销。
• Skill：在主对话里“教主 Agent 怎么做某类事”，用脚本和资料按需加载，适合单一用途、快速、可重复的任务。

两者可以一起用：例如用 Skill 定义“如何写 commit message”，用子代理做“探索代码库 + 并行更新文档”或“Verifier 独立验证实现”。

---

五、用户如何“启动”子代理

1. 自动委派（无需你操作）

主 Agent 会根据任务复杂度、项目中子代理的 description、当前上下文和工具自动决定是否委派。你只要正常提需求即可，例如：

• “帮我整体看看这个项目的代码结构和入口”
• “查一下仓库里所有 API 路由是在哪定义的”
• “在项目根目录执行 git status 并拉取最新代码”

2. 显式调用（指定用哪个子代理）

用 /子代理名称 语法直接指定要用的子代理：

/verifier confirm the auth flow is complete
/debugger investigate this error
/security-auditor review the payment module

也可以自然语言提及：

使用 verifier 子代理来确认身份验证流程已完成
Have the debugger subagent investigate this error

3. 并行执行

在同一句里让多个子代理并行工作，例如：

Review the API changes and update the documentation in parallel

Agent 可能在一次里发出多个子代理任务，让它们并行跑。

---

五 旁支问题不想污染主上下文时怎么办？

场景：你和主 Agent 在聊一个主话题，突然有一个旁支问题——需要基于当前讨论的背景才能回答，但你又不想让这段旁支对话塞进主上下文（避免 token 和话题被带偏）。

推荐做法一：用子代理“兜住”旁支问题（后续介绍简单方式）

• 做法：直接对主 Agent 说清楚意图，例如：
  • “我有个旁支问题，不想污染当前对话。请用子代理在独立上下文里处理：把当前讨论里和这个问题相关的要点作为背景传给子代理，让子代理回答 [你的旁支问题]，最后把子代理的结论带回来就行。”
• 原理：子代理有独立上下文，主 Agent 会在启动子代理的 prompt 里注入当前讨论的相关摘要，所以子代理是“基于当前上下文”的；旁支的多轮问答都发生在子代理里，主对话只收到最终结论，主上下文不会被旁支对话污染。
• 适用：希望答案回到当前会话、主 Agent 能基于该结论继续主线程时。

嫌每次说一长句太麻烦？ 可以做成自定义子代理，以后只需显式调用即可（见下方「旁支问题子代理」示例）。主 Agent 会按该子代理的 description 和提示词，自动把当前相关背景塞进 prompt、在独立上下文里回答并带回结论；你只需说 /旁支问题 你的具体问题 或自然语言“用旁支问题子代理：xxx”。

可选做法二：新开一个对话

• 做法：新开一个 Chat，在首条消息里粘贴一段简要背景（从主对话里摘的要点）+ 你的旁支问题。
• 优点：主对话完全不被占用；不依赖子代理。
• 缺点：需要你手动复制背景和（若需要）把答案抄回主对话；主 Agent 不会自动“看到”旁支的结论。

常见疑问

• 子代理会自动拿到主 Agent 的上下文吗？
  不会。 子代理是在全新上下文里启动的，无法访问主对话历史。当前讨论的内容必须由主 Agent 在启动子代理时写进 prompt（摘要或摘录）才会被子代理看到。也就是说：没有“自动继承”，只有“主 Agent 传什么，子代理才有什么”。

• 把当前上下文传给子代理，会不会耗很多 token？
  取决于主 Agent 传多少。 传进子代理 prompt 的那一段，会占用子代理的上下文（子代理单独计 token）。主 Agent 通常不会整段复制全文，而是提炼与旁支问题相关的要点/摘要再写入，这样既能满足“基于当前上下文”，又能控制 token。若主 Agent 传的是全文，就会明显更耗 token。可以口头约定：“只传与问题相关的简要背景，控制在 xxx 字内。”

小结

需求	更合适的做法
旁支要基于当前上下文，且希望结论回到主对话、不污染主上下文	用子代理，让主 Agent 把相关背景塞进子代理 prompt，子代理在独立上下文里回答并只把结果带回
旁支可以自己说清背景，或不需要把答案带回主对话	新开对话 + 粘贴背景与问题

实战：自定义「旁支问题」子代理（少说废话、一次配置）

方式 A：用 Skill创建子代理（ /create-subagent 向导创建）

用 Skill创建子代理还真是一个天才的想法啊！哈哈哈！这也能从一定程度上看出他们之间的区别！！

在 Agent 对话里输入 /create-subagent，并说明意图，例如：

/create-subagent  我想创建一个 side-question 的子代理，比如和 AI 讨论的时候会遇到一些旁支问题，不想污染上下文，但是又需要当前的一些上下文作为提问基础。

Agent 会引导你选择作用域（项目 / 用户）、填写 name 与 description、编写提示词，并在对应目录下生成 side-question.md。生成后可按需微调内容。

方式 B：手写文件

在 .cursor/agents/（项目级）或 ~/.cursor/agents/（用户级）下新建 side-question.md，内容示例：

---
name: side-question
description: 处理基于当前讨论背景的旁支问题，在独立上下文中回答并只把结论带回主对话，避免污染主上下文。当用户提到旁支问题、不想污染当前对话、或显式调用 /side-question 时使用。
model: fast
---

你是主对话派出的**旁支问题处理者**。你会在**独立上下文**中收到主 Agent 提供的「当前讨论相关背景」和用户的「旁支问题」。

## 你的职责

1. **仅基于传入的背景和旁支问题作答**，不臆造主对话中未提供的内容。
2. **回答简洁、结论明确**；若需要多轮澄清，在子代理内完成，不要拖回主对话。
3. **结束时给出一段可直接贴回主对话的结论摘要**，供主 Agent 带回，方便用户继续主线程讨论。

## 约束

- 不要复述主对话内容。
- 只输出对旁支问题的答案和结论，避免冗长铺垫。
- 若背景不足无法回答，在结论中简要说明缺少哪类信息，便于主 Agent 补全后再问。

项目级 vs 用户级、如何“全项目可用”

存放位置	适用范围
项目级 项目/.cursor/agents/side-question.md	仅当前项目可用；适合纳入 Git，团队共享
用户级 ~/.cursor/agents/side-question.md	当前用户下所有项目都可调用，无需每个项目各放一份

若希望在任何项目里都能用 /side-question，可把已在项目里建好的 side-question.md 复制一份到 ~/.cursor/agents/。名称冲突时 Cursor 的规则是：项目优先于用户——即某项目若也有同名子代理，会优先用项目里的那份。

完整流程小结：创建子代理（/create-subagent 或手写）→ 保存到 .cursor/agents/side-question.md → 可选：再复制到 ~/.cursor/agents/side-question.md 以在全部项目中可用。

使用方式

之后只需说：/side-question 你的具体旁支问题，或“用 side-question 子代理：xxx”。主 Agent 会调用该子代理，把当前相关背景写入 prompt，子代理在独立上下文里回答并带回结论。

---

六、自定义子代理（你创建的专用代理）

创建方式（用 Skill创建子代理）

• 方式一（设置里）：在 Cursor Settings → Subagents 里点 「+ New」 或 「New Subagent」，会触发与 /create-subagent 相同的创建流程，由 Agent/Skill 一步步带你建子代理。
  

• 方式二（对话里）：在 Agent 对话里输入 /create-subagent（当前版本 Cursor 已默认集成），同样触发上述创建流程。

• 方式三（手写文件）：直接在 .cursor/agents/ 或 ~/.cursor/agents/ 下用文件定义（官方推荐用于版本控制和团队共享）。

也就是说：用 Skill 创建 Subagent —— 设置里的「New」和对话里的 /create-subagent 都是同一条“向导式”能力的不同入口；想完全自己掌控时再用手写 .md 文件。

文件位置与优先级

类型	路径	适用范围
项目子代理	.cursor/agents/	仅当前项目
	.claude/agents/、.codex/agents/	仅当前项目（兼容 Claude/Codex）
用户子代理	~/.cursor/agents/	当前用户所有项目

名称冲突时：项目优先于用户；同一项目内 .cursor/ 优先于 .claude/ / .codex/。

若希望某个子代理在所有项目里都能用（例如旁支问题子代理），可先写在项目 .cursor/agents/ 下，再复制同一文件到 ~/.cursor/agents/；这样任意打开一个项目都能用 /子代理名 调用，同时项目内仍可保留一份用于版本管理与团队共享。

文件格式

每个子代理一个 Markdown 文件，用 YAML frontmatter 写配置，后面跟提示内容：

---
name: security-auditor
description: 安全专家。在实现身份验证、支付或处理敏感数据时使用。
model: inherit
---

你是一位代码安全审计专家，负责审查代码漏洞。

调用时:
1. 识别安全敏感代码路径
2. 检查常见漏洞(注入、XSS、身份验证绕过)
3. 验证密钥未被硬编码
4. 按严重程度报告发现

配置字段

字段	必填	说明
name	否	唯一标识，小写+连字符。默认用文件名（无扩展名）
description	否	何时使用此子代理；Agent 靠它决定是否委派。写清楚场景
model	否	fast、inherit 或具体模型 ID，默认 inherit
readonly	否	true 时子代理以受限写入权限运行
is_background	否	true 时在后台运行，不等待完成

在 description 里写 “use proactively” 或 “always use for …” 可以鼓励 Agent 更主动地委派给该子代理。

/create-subagent 是什么？怎么用？

/create-subagent 用于在对话里向导式创建自定义子代理（生成 .cursor/agents/xxx.md 等子代理文件）。

• 当前 / 较新版本 Cursor：该命令已默认集成，无需单独安装，在 Agent 对话里输入 /create-subagent 即可使用。
• 若你的版本里没有：可能是旧版或不同发行渠道，可尝试安装社区 Skill：npx skills add henriqueneves87/cursor-toolkit --skill "create-subagent"（cursor-toolkit / create-subagent）。

用法：

1. 在 Agent 对话里输入 /create-subagent（可附带说明，如“创建一个代码审查子代理”）。
2. Agent 会带你完成：选作用域（项目 / 用户）、写 name 和 description、写系统提示词，并在 .cursor/agents/ 或 ~/.cursor/agents/ 下生成对应的 .md 文件。
3. 适合不想手写 YAML 和路径时，用对话方式“向导式”创建子代理。

若当前环境没有该命令，也可以按本文档的「文件格式」和「文件位置」自己新建 .md 文件。

---

七、恢复子代理（继续之前的会话）

每次子代理执行会返回一个 agent ID。需要继续同一任务时，可以恢复该子代理：

Resume agent abc123 and analyze the remaining test failures

后台子代理在运行时会记录状态；完成后也可以恢复，在保留上下文的情况下继续对话。

---

八、常见模式（来自官方）

• 验证代理（Verifier）：在任务被标为“完成”后，用独立子代理验证实现是否真的可用、测试是否通过、有无遗漏边界情况。
• 协调器模式：父 Agent 按顺序协调多个专业子代理，例如 Planner（方案）→ Implementer（实现）→ Verifier（验证），每次交接提供结构化输出。

---

九、性能与成本（官方说明）

优点	代价
上下文隔离	启动开销（每个子代理都要自己收集上下文）
并行执行	更高 token 消耗（多个上下文同时跑）
专门化能力	延迟（对简单任务可能比主 Agent 更慢）

• 每个子代理独立消耗 token；并行跑 5 个子代理，大约相当于 5 倍 token。
• 对快速、简单的任务，主 Agent 往往更快；子代理更适合复杂、长时间或需要并行的工作。

---

十、最佳实践与需避免的做法

建议：

• 每个子代理职责单一，避免泛用型“万能助手”。
• 认真写 description，它决定 Agent 何时委派；可写几句提示测试是否触发正确子代理。
• 提示简洁、具体；过长会削弱聚焦。
• 将 .cursor/agents/ 纳入版本控制，方便团队共用。
• 可先让 Agent 帮你起草子代理，再自己微调。

避免：

• 创建几十个描述模糊的子代理（如“用于通用任务”），Agent 难以判断何时使用。
• 提示词过长（如几千字），只会更慢、更难维护。
• 用子代理做本可用 slash 命令 完成的单一用途任务。
• 一开始就建很多个；先从 2～3 个聚焦场景开始，有清晰区分再增加。

---

十一、小结

• 子代理 = 主 Agent 委派给“专门干一类事”的助手，独立上下文、减少主对话占用和噪音。
• 内置三个：Explore（代码库）、Bash（命令）、Browser（浏览器），自动使用。
• 你可以：在设置里或 .cursor/agents/ 下自定义子代理，用 /name 显式调用，或用自然语言/并行请求让 Agent 自动委派。
• 恢复：用返回的 agent ID 可继续同一子代理的会话。
• 子代理适合复杂、多步、需隔离或并行的任务；简单、单一用途的更适合 Skill 或主 Agent 直接做。