子代理设计指南

技能文档

---
name: majiayu000-sub-agent-design
title: 子代理设计指南
description: 设计高质量子代理（subagent/agent）的解释性指南，覆盖隔离模型、与技能的职责划分、正文结构、工具选择、描述字段设计与质量检查清单，帮助避开常见陷阱。当用户要求「创建子代理」「设计 agent」「审查 subagent」「写一个子代理」时使用。触发词：子代理、subagent、agent 设计、代理编排。
category: 开发工具
---

# 子代理设计指南

本技能提供创建子代理（subagent / agent）的解释性指导，帮助你理解平台文档的含义并设计出优秀的子代理。

## 工作流导航

| 需求 | 查看 |
| ---- | ---- |
| 理解子代理隔离模型 | [基本原理](#基本原理) |
| 决定知识放子代理还是放技能 | [子代理与技能的关系](#子代理与技能的关系) |
| 组织子代理正文结构 | [子代理正文结构](#子代理正文结构) |
| 子代理自动加载技能 | [`skills` 字段（最佳实践）](#skills-字段最佳实践) |
| 编写技能使用章节 | [技能使用章节模式](#技能使用章节模式) |
| 内联校验清单 | [内联质量清单](#内联质量清单) |
| 选择工具 | [工具选择哲学](#工具选择哲学) |
| 编写描述字段 | [描述字段设计](#描述字段设计) |
| 避开常见错误 | [常见陷阱](#常见陷阱) |
| 完成前校验 | [质量检查清单](#质量检查清单) |

## 基本原理

**核心约束：子代理运行在隔离上下文中，执行完成后只返回结果。它无法向用户提问。**

设计子代理的一切决策都由此推导：它必须能从任务描述和上下文中自主推断，做出合理假设并继续执行。

## 快速上手

子代理文件结构：

```markdown
---
name: my-agent
description: 当 Y 时做 X。涉及 Z 时必须使用。
tools: Read, Grep, Glob
---

# 我的代理

本子代理用于[目的]。

## 流程

1. [步骤一]
2. [步骤二]

## 约束

- 禁止出现「询问用户」类表述（子代理无法与用户交互）
```

## 技能工作流

### 步骤 1：组织子代理正文结构

正文（frontmatter 之后的内容）即子代理的系统提示词。

**必备章节：**

| 章节 | 用途 |
| ---- | ---- |
| H1 标题 | 代理身份，仅允许一个 H1 |
| 流程 | 代理执行的编号步骤 |

**可选章节：**

| 章节 | 何时加入 |
| ---- | -------- |
| 开场句 | H1 后用一句话说明目的 |
| 前置条件 | 开始前必须满足的技能或环境条件 |
| 技能使用 | 代理通过 `skills` 字段加载技能时（见下） |
| 约束 | 执行期间的行为规则 |
| 异常处理 | 边界情况与响应方式（通常为表格） |

**最小代理示例：**

```markdown
# 代理名称

## 流程

1. **步骤一**
2. **步骤二**
```

**完整代理示例（加载技能时）：**

```markdown
# 代理名称

本子代理用于[目的]。

## 前置条件

以下技能必须可用；若不可用，报告失败并停止：

- skill-one
- skill-two

## 技能使用

按各技能的「工作流导航」表定位所需指导。

**skill-one** —— 用于查询：

- [方面 A]（该技能的章节名）
- [方面 B]（该技能的章节名）

## 流程

1. **理解调用方需求**
2. **借助技能完成设计**：[具体决策] 查 skill-one，[其他决策] 查 skill-two
3. **执行任务**
4. **校验**——全部通过才算完成：
   - [ ] 清单项一
   - [ ] 清单项二
   **任何一项失败：修复后再报告结果。**
5. **报告结果**

## 异常处理

| 情况 | 处理 |
| ---- | ---- |
| 所需技能未加载 | 报告失败，不要强行执行 |
| 需求不清晰 | 做出合理假设并记录 |
```

**该结构有效的原因：**

- 「技能使用」告诉代理去哪查（导航指针，不复制内容）
- 流程步骤明确「哪个决策查哪个技能」
- 校验清单内联在流程中，无法被跳过

### 步骤 2：用好 `skills` 字段（最佳实践）

`skills` 字段在子代理启动时自动加载技能，适合领域固定、每次都需要同一技能的代理。

| 方式 | 适用 | 避免用于 |
| ---- | ---- | -------- |
| `skills` 字段 | 领域固定，总是需要同一技能 | 所需技能随上下文变化 |
| 正文中按需加载 | 领域多变，技能取决于运行时判断 | 总是需要同一技能 |
| 不加载技能 | 没有相关技能 | 存在代理需要的指导性技能 |

**注意：** `tools` 列表中仍保留技能加载工具——代理执行中可能需要加载额外技能。

**按条件加载技能的示例：**

```markdown
# 组件校验器

## 流程

1. **根据文件结构识别组件类型**
2. **加载对应设计技能**：
   - 插件 → 插件设计技能
   - 子代理 → 子代理设计技能
   - 技能 → 技能设计技能
3. **按所加载技能的模式进行校验**
```

无法预先声明单一技能时（所需技能取决于运行时发现的组件类型），采用此模式。

### 步骤 3：编写技能使用章节

代理通过 `skills` 字段加载技能时，加入「技能使用」章节，教它**如何**遍历技能，而不仅是知道加载了。

**结构：**

```markdown
## 技能使用

按各技能的「工作流导航」表定位指导。

**技能名** —— 用于查询：

- [查什么]（技能中的章节名）
- [另一样]（另一章节名）
```

**关键原则：**

| 原则 | 原因 |
| ---- | ---- |
| 给导航指针，不给内容 | 避免重复；技能保持唯一事实来源 |
| 引用章节名 | 指针稳定，章节名很少变动 |
| 每个技能列出具体方面 | 代理知道哪个问题查哪个技能 |
| **禁止跨组件内部文件路径** | 技能内部结构对代理是实现细节 |

**关键禁令：** 代理引用所加载的技能时，用**间接引用**（章节名、概念名），不用技能内部文件路径。

- ✅ 「（快速上手）」——技能章节名
- ✅ 「（该技能关于工具选择的指导）」——间接引用
- ❌ 「（gotchas.md）」——技能内部文件
- ❌ 「（skill-structure.md）」——技能内部文件

**可省略场景：** 代理不加载技能、或通过运行时判断按条件加载时，无需此章节。

### 步骤 4：内联质量清单

关键校验必须把清单内联到流程章节中，不能只写「参照某技能的清单」——代理可能跳过引用。

**模式：**

```markdown
4. **校验**——全部通过才算完成：

   - [ ] 清单项一
   - [ ] 清单项二
   - [ ] 清单项三

   **任何一项失败：修复后再报告结果。**
```

| 应内联 | 应引用（不内联） |
| ------ | ---------------- |
| 校验清单（阻塞项） | 指导与背景（信息性） |
| 完成前必做检查 | 决策框架（用于理解） |
| 绝不能跳过的条目 | 示例与模式（用于学习） |

**平衡：** 只内联清单条目本身（每条 1-2 行），解释与理由留在技能里，兼顾唯一事实来源与校验强制性。

### 步骤 5：按哲学选择工具

**总原则：** 工具匹配子代理的职责。评审类只读；构建类需要写权限。

**禁止交互工具：** 子代理在隔离环境运行，无法与用户交互。凡向用户提问的工具都会静默失败或引发异常行为。若子代理需要澄清，必须从上下文推断或做合理假设。

**构建类代理要有 Shell 工具：** 凡有创建职责的子代理都需要 shell 操作，即使只产出 Markdown：

| 操作 | 为什么需要 Shell |
| ---- | ---------------- |
| 目录脚手架 | 创建嵌套目录（文件写入工具通常不建父目录） |
| 文件组织 | `mv`、`cp` 重构结构 |
| 写后格式化 | 格式化器、linter |
| 结构查看 | `ls` 了解现有布局 |
| Git 操作 | `git mv` 重命名已跟踪文件 |

**经验法则：** 子代理要创建文件，就带上 Shell。写文件工具负责内容，Shell 负责周边文件系统编排。

**文档抓取与技能搭配验证：** 技能承载的是「文档之外」的解释性知识，但底层规范会演进。代理流程应包含一步：「对当前规范不确定时，抓取官方文档核实」——技能提供稳定指导，文档抓取兜住规范漂移。

### 步骤 6：设计描述字段

`description` 字段决定主代理何时把任务委派给你的子代理，是自动触发的关键。

- 写明**何时使用**（触发条件），不只是做什么
- 上下文与用例要具体
- 实测验证——若子代理没被自动调用，修改描述
- 避免过于宽泛、匹配过多场景的描述

## 常见陷阱

- ❌ 正文中出现「询问用户」「与用户确认」类表述
- ❌ 加载了技能却不在流程中引用（技能白加载）
- ❌ 把技能章节内容复制进子代理（双重维护、上下文浪费、可能冲突）
- ❌ 校验清单只引用不内联（容易被跳过）
- ❌ 描述字段过于宽泛，导致触发不可靠
- ❌ 工具集与职责不匹配（评审代理带写权限、构建代理缺 Shell）
- ❌ 硬编码版本相关的细节，很快过时

## 质量检查清单

完成子代理前逐项检查：

1. **核对平台文档**——对照所用平台的最新子代理规范
2. **检查结构**——frontmatter 合法、必备字段齐全
3. **扫描禁用表述**——无任何用户交互类措辞
4. **校验工具**——匹配自主职责，不含交互类工具
5. **测试描述**——触发条件具体，不宽泛
6. **审查系统提示词**——单一 H1、结构清晰、指令可执行
7. **确认无硬编码**——无会过时的版本细节
8. **若通过 `skills` 字段加载技能：**
   - 有「技能使用」章节且为导航指针
   - 指针使用间接引用（章节名），不暴露内部文件路径
   - 流程步骤引用了具体技能章节
   - 质量清单已内联在校验步骤中（而非仅引用）

使用说明

# 子代理设计指南

设计高质量子代理的解释性指南：理解隔离模型、划分知识与流程的归属、组织正文结构、按职责选工具、写可靠的触发描述，并附完成前质量检查清单。

## 使用场景

- 新建子代理时的设计参考
- 审查/重构已有子代理的质量
- 排查子代理不被自动触发的问题

## 用法示例

```text
帮我设计一个代码评审子代理
审查这个 subagent 的设计有没有问题
```

核心原则：子代理在隔离上下文中运行、无法向用户提问——一切设计决策由此推导。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。