skillful-subagent-creator

熟练的子 Agent 创建器

创建配备精选技能作为标准操作流程的 Claude 子 Agent。每个子 Agent 都是“一位配备工具包的专家”——职责范围明确、技能集精简，并拥有清晰的技能应用工作流。

---

适用场景

✅ 适用于：

• 为特定领域设计专业子 Agent
• 选择要附加到子 Agent 的技能（2-5 项核心技能）
• 编写包含 4 个部分的子 Agent 提示词（身份、技能、任务循环、约束）
• 将子 Agent 接入 DAG 编排工作流
• 定义 DAG 节点之间的输入／输出契约

❌ 不适用于：

• 创建技能本身（使用 skill-architect）
• 不使用技能的单 Agent 提示词
• Claude Code 通用功能或 MCP 设置

---

子 Agent 创建流程

flowchart TD
  A[Define the role] --> B[Select 2-5 skills]
  B --> C[Write 4-section prompt]
  C --> D[Define input/output contracts]
  D --> E[Choose DAG position]
  E --> F{Standalone or chained?}
  F -->|Standalone| G[Test with sample task]
  F -->|Chained| H[Define handoff protocol]
  H --> G
  G --> I{Works correctly?}
  I -->|No| C
  I -->|Yes| J[Deploy]

---

第 1 步：定义角色

子 Agent 的角色必须足够具体，才能成为专家；又要足够宽泛，才有实用价值。

flowchart TD
  A{How narrow?} -->|Too broad| B["Do all marketing" ❌]
  A -->|Right| C["Draft landing page copy" ✅]
  A -->|Too narrow| D["Fix typos in H1 tags" ❌]

检验方法：你能否用一个带有具体动词和名词的句子描述这个子 Agent 的工作？如果不能，就进一步缩小范围。

角色范围设定良好的示例：

角色	领域	句子
重构者	TypeScript	“在 TypeScript 单体仓库中设计并执行安全的重构”
PR 审查者	代码审查	“审查拉取请求差异，检查正确性、风格和安全性”
研究综合者	研究	“将多来源研究综合为附带引用的简报文档”
迁移规划者	数据库	“规划数据库架构迁移，并制定回滚策略”

---

第 2 步：选择技能（2-5 项）

技能是子 Agent 的标准操作流程。技能太少，它就会临场发挥；技能太多，它就会被上下文淹没。

选择标准

flowchart TD
  A{For each candidate skill} --> B{Needed for >50% of tasks?}
  B -->|Yes| C[Preload into context]
  B -->|No| D{Needed for 10-50%?}
  D -->|Yes| E[Add to dynamic catalog]
  D -->|No| F[Don't include]

三个加载层级

层级	技能	加载方式	Token 开销
预加载	2-5 项核心技能	将完整的 SKILL.md 注入系统提示词	每项技能约 2-5k 个 token
目录	5-20 项可用技能	在提示词中列出名称和一行描述；按需加载	每项技能约 50 个 token
无	其他所有技能	不提及；Agent 使用通用推理	0 个 token

技能选择示例

角色：TypeScript/React 的 PR 审查者

层级	技能	原因
预加载	code-review-skill	每项任务的核心技能
预加载	react-server-components	能发现 RSC 反模式
目录	typescript-strict-mode	有时相关
目录	testing-patterns	仅适用于测试文件审查
无	database-migration	不在范围内

---

第 3 步：编写包含 4 个部分的提示词

每个子 Agent 提示词都恰好包含四个部分。此结构可确保子 Agent 了解自身角色、工具、工作流和约束。

第 1 部分：身份

You are the **[Role Name]** subagent for this system.
You handle [narrow domain of tasks].
When a task is outside this scope, explicitly say so and
ask the orchestrator for a different agent.

控制在 2-4 句话以内。明确具体领域，并清楚说明职责边界。

第 2 部分：技能使用规则

You have access to the following skills, which define your methods:
- `skill-a`: [1-line purpose]
- `skill-b`: [1-line purpose]
- `skill-c`: [1-line purpose]

These are your standard operating procedures, not optional hints.
When tackling a task:
1. Decide which skill(s) apply
2. Follow their step-by-step workflow
3. Use their output formats and checklists
4. Reference skill steps by number as you work

第 3 部分：任务处理循环

For each task you receive:
1. Restate the task in your own words
2. Select one or more skills that fit. If none fit well, say so.
3. If needed, ask 2-5 clarifying questions
4. Produce a short internal plan
5. Execute the skill workflow step by step
6. Run any validation/QA steps from the skill
7. Return:
   (a) Final artifacts
   (b) Which skills you used (and which steps)
   (c) Assumptions and remaining risks

第 4 部分：约束

Quality bar: [e.g., "Never knowingly leave tests failing"]
Safety: [e.g., "No destructive operations without confirmation"]
Tie-breaking: [e.g., "If speed vs robustness conflict, pick robustness"]
Output format: [e.g., "Always return valid JSON matching the output contract"]

---

第 4 步：定义输入／输出契约

每个子 Agent 都必须有明确的契约，以便编排器和下游 Agent 与其协作。

输入契约

{
  "task": "string — description of what to do",
  "files": ["string — paths to relevant files"],
  "context": "string — prior agent output or user requirements",
  "constraints": {
    "time_budget": "string — e.g., '5 minutes'",
    "quality_bar": "string — e.g., 'production-ready'"
  }
}

输出契约

{
  "status": "pass | warn | fail",
  "artifacts": ["string — files created or modified"],
  "summary": "string — 1-3 sentence description of what was done",
  "skills_used": ["string — skill names and step numbers"],
  "risks": ["string — remaining risks or assumptions"],
  "metadata": {
    "duration_ms": "number",
    "tokens_used": "number"
  }
}

---

第 5 步：接入 DAG 工作流

编排模式

flowchart TD
  subgraph "Single Specialist"
    O1[Orchestrator] --> S1[Specialist]
    S1 --> O1
  end

  subgraph "Chain"
    O2[Orchestrator] --> C1[Designer]
    C1 --> C2[Implementer]
    C2 --> C3[Tester]
    C3 --> O2
  end

  subgraph "Fan-out / Fan-in"
    O3[Orchestrator] --> P1[Auth Agent]
    O3 --> P2[Billing Agent]
    O3 --> P3[UI Agent]
    P1 --> M[Merger]
    P2 --> M
    P3 --> M
    M --> O3
  end

模式选择

模式	适用场景	技能要求
单个专家	任务对应一个领域	Agent 有 2-5 项预加载技能
链式	顺序转换流水线	每个 Agent 使用不同技能；A 的输出作为 B 的输入
扇出／扇入	独立并行工作	Agent 并发工作；合并器解决冲突
循环	迭代优化	同一个 Agent 根据反馈重新运行，直到达到质量标准
人在环路中	需要审批	Agent 生成草稿；由人工审查；Agent 再进行修订

DAG 节点定义

DAG 中的每个节点都是一个子 Agent，包含：

node:
  id: review-pr
  agent: pr-reviewer
  skills: [code-review-skill, react-server-components]
  input_from: [parse-diff]
  output_to: [merge-decision]
  retry: 2
  timeout: 300s
  on_failure: escalate-to-human

---

第 6 步：测试

测试协议

1. 顺利路径：给子 Agent 一项与其技能完全匹配的任务
2. 边界情况：给它一项处于其职责范围边界的任务
3. 职责范围之外：给它一项超出其领域的任务——它应该拒绝并说明原因
4. 技能覆盖：确认它使用附加的技能，而非临时推理
5. 输出契约：确认输出与 JSON 架构完全一致

危险信号

• Agent 不遵循技能，而是自行编造流程 → 技能使用规则不够明确
• Agent 尝试处理职责范围之外的任务 → 身份说明不够清晰
• 输出不符合契约 → 在约束中明确指定输出格式
• Agent 提前加载所有参考资料 → 在提示词中添加延迟加载指令

---

完整示例：PR 审查子 Agent

配置

name: pr-reviewer
role: "Reviews TypeScript/React pull requests for correctness, style, and security"
skills:
  preloaded:
    - code-review-skill
    - react-server-components
  catalog:
    - typescript-strict-mode
    - testing-patterns
tools: [Read, Grep, Glob]
input_from: [diff-parser]
output_to: [merge-decision]

提示词

You are the **PR Reviewer** subagent. You review TypeScript and React
pull request diffs for correctness, readability, performance, and security.
You do NOT implement features, fix bugs, or write new code. If asked to do
so, say "This is outside my scope — route to the Implementer agent."

Your skills define your standard process:
- `code-review-skill`: Structured review methodology (correctness → style → perf → security)
- `react-server-components`: Catches RSC anti-patterns ('use client' overuse, async component errors)

For each PR you receive:
1. Restate what the PR changes and why
2. Select applicable skills (always code-review-skill; add react-server-components if React files changed)
3. Follow the skill's review steps in order
4. Produce findings in the output contract format
5. Summarize: approve, request changes, or block

Quality bar: Never approve a PR with failing tests or security vulnerabilities.
Tie-breaking: If unsure whether something is a bug or style preference, flag it as "suggestion" not "required."
Output: Always return JSON matching the output contract schema.

---

反模式

不具备技能的子 Agent

错误：创建的子 Agent 只有角色描述，没有技能。 原因：它每次都会临时编造新的流程，而不是遵循一致的方法。 修正：附加 2-5 项技能作为标准操作流程。

技能过载

错误：给一个子 Agent 附加 15 项技能。 原因：占用上下文窗口；Agent 会花费 Token 选择技能，而非执行任务。 修正：最多预加载 5 项，其余放入目录。让编排器预先筛选。

缺少输出契约

错误：子 Agent 返回下游 Agent 无法解析的自由格式文本。 原因：DAG 会因此中断，因为下一个节点无法使用该输出。 修正：定义明确的 JSON 输出契约，并在测试中进行验证。

职责范围膨胀

错误：子 Agent 试图处理所有事情，而不是拒绝职责范围之外的任务。 原因：身份说明没有足够清楚地阐明边界。 修正：添加“你不处理 X、Y、Z。如果有人提出此类要求，请说明并建议合适的 Agent。”