subagent-creator

用途

Subagent Creator 是一个指南类工具，用于帮助用户创建有效的子代理（自定义代理）。当用户想要创建一个可以通过 Task 工具派发、用于自主工作的新子代理时，可参考本指南。

子代理与技能的区别

指南以对比方式说明了两种机制的差异：

调用方式：子代理通过 Task 工具显式调用；技能由上下文自动触发。
上下文：子代理使用隔离的全新上下文窗口；技能与父级共享上下文。
复杂度：子代理为单个 .md 文件；技能是包含资源的文件夹。
使用场景：子代理用于自主的离散任务；技能用于指导和流程。
嵌套能力：子代理不能生成其他子代理；技能可以引用其他技能。

适合使用子代理的情形：任务是离散且自主的、全新上下文窗口有益、任务可与其他工作并行运行、需要专门限制工具。

适合使用技能的情形：整个对话过程都需要指导、上下文共享很重要、需要多种资源（脚本、参考资料）。

子代理结构

子代理位于 agents/ 目录下，每个代理为一个 .md 文件，包含 YAML frontmatter（元数据）与 Markdown 正文（系统提示词）：

agents/
└── agent-name.md
    ├── YAML frontmatter (metadata)
    └── Markdown body (system prompt)

Frontmatter 字段：

name（必填）：小写、仅含连字符，例如 code-reviewer。
description（必填）：何时使用——用于触发派发决策。
tools（可选）：逗号分隔，如 Bash, Glob, Grep, Read, Edit, Write。
model（可选）：sonnet、opus、haiku 或 inherit（默认 inherit）。
permissionMode（可选）：default、acceptEdits、bypassPermissions、plan。
skills（可选）：逗号分隔的、可自动加载的技能。

工具参考

只读：Glob, Grep, Read, WebFetch, WebSearch
写入：Edit, Write, NotebookEdit
执行：Bash
全部：*（或省略该字段）

权限模式

default：常规权限提示。
acceptEdits：自动接受文件编辑。
bypassPermissions：跳过所有权限提示。
plan：计划模式——仅探索但不修改。

编写有效提示词

结构模板：

---
name: agent-name
description: When to use this agent. Be specific about triggers.
tools: Tool1, Tool2
model: sonnet
---

# Agent Name

One-line role description.

## Input Required
What the agent expects to receive.

## Process
Step-by-step what the agent does.

## Output Format
Exact format of the response.

## Rules
- Constraints and boundaries
- What to avoid

最佳实践：明确角色（首行定义身份）、定义清晰输入（必须提供什么）、结构化流程（编号步骤）、指定输出格式（模板用代码块）、设定边界（不要做什么）。

description 字段的编写准则：该字段在代理被建议使用时触发，应包含主要用例、必需输入、预期输出类型。

示例（好）：

description: Use after completing a task to review code changes. Provide BASE_SHA, HEAD_SHA, and requirements. Returns issues with file:line references.

示例（差）：

description: Reviews code.

示例：最小子代理

---
name: summarizer
description: Use to summarize long documents or conversations. Provide the content to summarize.
tools: Read
model: haiku
---

# Summarizer

Summarize the provided content in 3-5 bullet points.

Focus on: key decisions, action items, conclusions.
Skip: greetings, filler, obvious context.

完整示例参见 references/subagent-examples.md。

创建流程

定义任务——该代理执行什么自主工作？
选择工具——最少必要（倾向限制性）。
选择模型——简单任务用 haiku，复杂用 sonnet，关键用 opus。
编写提示词——角色、流程、输出、规则。
测试——通过 Task 工具派发并迭代。

初始化脚本

scripts/init_subagent.py <agent-name> --path <output-directory>

创建带有正确结构的模板代理文件。

反模式

范围过宽——代理试图做所有事情。
工具过多——应给出最少必要工具。
输出模糊——始终指定确切格式。
缺少边界——必须定义不要做什么。
模型选择不当——简单任务不要用 opus。

限制

关于具体价格、收费、平台支持范围等事实，资料中暂未提供。