Back to Details

subagent-dispatch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Subagent Dispatch Protocol

子代理调度协议

This skill governs how to correctly dispatch custom agents in this project. Its primary purpose is to ensure each agent runs with its intended model — declared in the agent's own YAML frontmatter — rather than a platform default.
本技能规定了本项目中如何正确调度自定义Agent。其核心目的是确保每个Agent使用其预期的模型运行——该模型在Agent自身的YAML frontmatter中声明——而非平台默认模型。

Why This Matters

为何重要

Each agent in 
.github/agents/
declares a 
model
in its YAML frontmatter. That choice is deliberate: different agents are optimized for different models based on their role (e.g., the UI Composer on Gemini for creative work, the Compliance Reviewer on GPT-5.4 for analytical rigor). Calling the 
task
tool without passing 
model
ignores that intent entirely.
.github/agents/
目录下的每个Agent都在其YAML frontmatter中声明了
model
参数。这个选择是经过深思熟虑的：不同的Agent根据其角色适配不同的模型（例如UI Composer使用Gemini来完成创意工作，合规审核员使用GPT-5.4来保证分析严谨性）。调用
task
工具时不传递
model
参数会完全忽略这个预设意图。

Model Resolution Protocol

模型解析协议

Follow these steps before every custom agent dispatch:
每次调度自定义Agent之前都请遵循以下步骤：

Step 1 — Identify the agent file

步骤1——确定Agent文件

Custom agents live at 
.github/agents/<agent-name>.agent.md
. The 
agent_type
value maps directly to the filename (e.g., 
ui-composer
→ 
ui-composer.agent.md
).
自定义Agent存放在 
.github/agents/<agent-name>.agent.md
路径下。
agent_type
值与文件名直接对应（例如 
ui-composer
→ 
ui-composer.agent.md
）。

Step 2 — Look up the model

步骤2——查询模型

Use the Agent Registry below for the four known agents. If the agent isn't listed (a new one was added), read its 
.agent.md
file and extract the 
model
field from the YAML frontmatter at the top.
使用下方的Agent注册表查询4个已知Agent的模型。如果Agent未在列表中（即新增的Agent），请读取其
.agent.md
文件，从顶部的YAML frontmatter中提取
model
字段。

Step 3 — Map to the task tool's model ID

步骤3——映射为任务工具的模型ID

Agent frontmatter 
model
value
task
tool 
model
parameter		Model Fallback
Gemini 3.1 Pro (Preview) (copilot)
gemini-3.1-pro-preview
Claude Opus 4.6
Gemini 3 Pro (Preview) (copilot)
gemini-3-pro-preview
Claude Opus 4.6
Gemini 3 Flash (Preview) (copilot)
gemini-3-flash-preview
Claude Opus 4.6 (copilot)
claude-opus-4.6
GPT-5.4
Claude Sonnet 4.6 (copilot)
claude-sonnet-4.6
GPT-5.4
Claude Haiku 4.5 (copilot)
claude-haiku-4.5
GPT-5.4 (copilot)
gpt-5.4
GPT-5.4 mini (copilot) 
gpt-5.4-mini
Claude Haiku 4.5
GPT-5.3-Codex (copilot)
gpt-5.3-codex
Pattern: strip 
 (copilot)
, lowercase, replace spaces with hyphens.
Fallbacks: If the intended model isn't available, use the fallback. Otherwise, default to the platform's default for that agent type.
Some built-in agent types (
task
, 
code-review
) have no 
.agent.md
file. Skip model resolution for these — use platform defaults or override manually based on task complexity.
Important: Prefer 
GPT-5.4 mini
and 
GPT-5.3-Codex
for 
explore
and 
general-purpose
built-in agents respectively.
Agent frontmatter 
model
value
task
tool 
model
parameter		Model Fallback
Gemini 3.1 Pro (Preview) (copilot)
gemini-3.1-pro-preview
Claude Opus 4.6
Gemini 3 Pro (Preview) (copilot)
gemini-3-pro-preview
Claude Opus 4.6
Gemini 3 Flash (Preview) (copilot)
gemini-3-flash-preview
Claude Opus 4.6 (copilot)
claude-opus-4.6
GPT-5.4
Claude Sonnet 4.6 (copilot)
claude-sonnet-4.6
GPT-5.4
Claude Haiku 4.5 (copilot)
claude-haiku-4.5
GPT-5.4 (copilot)
gpt-5.4
GPT-5.4 mini (copilot) 
gpt-5.4-mini
Claude Haiku 4.5
GPT-5.3-Codex (copilot)
gpt-5.3-codex
规则：去掉
 (copilot)
后缀，转为小写，空格替换为连字符。
降级方案：如果预期模型不可用，请使用降级方案。否则，使用该Agent类型对应的平台默认值。
部分内置Agent类型（
task
、
code-review
）没有对应的
.agent.md
文件。这类Agent无需进行模型解析——使用平台默认值，或根据任务复杂度手动覆盖即可。
重要提示：
explore
和
general-purpose
类的内置Agent分别优先使用
GPT-5.4 mini
和
GPT-5.3-Codex
。

Step 4 — Pass 
model
to the task tool

步骤4——向任务工具传递
model
参数

Always include the resolved model ID as the 
model
parameter:
task({
  agent_type: "ui-composer",
  model: "gemini-3.1-pro-preview",   // resolved from frontmatter
  description: "Build patient card component",
  prompt: "..."
})
始终将解析后的模型ID作为
model
参数传入：
task({
  agent_type: "ui-composer",
  model: "gemini-3.1-pro-preview",   // resolved from frontmatter
  description: "Build patient card component",
  prompt: "..."
})

Core Dispatch Principles

核心调度原则

  1. One agent per problem domain. Dispatch independent agents concurrently — don't serialize work that can run in parallel.
  2. Subagents are stateless. They have zero memory of the current conversation. The prompt must be entirely self-contained with all the context needed.
  3. Review before accepting. Evaluate subagent output critically and request revisions when quality or relevance falls short.
  1. 每个问题域对应一个Agent。可并发调度独立的Agent——不要将可并行运行的工作串行处理。
  2. 子代理是无状态的。它们没有当前对话的任何记忆。提示词必须完全自包含，包含所需的全部上下文。
  3. 验收前先审核。批判性评估子代理的输出，当质量或相关性不足时请求修订。

Prompting Checklist

提示词检查清单

A subagent prompt should answer all of these before you send it:
  • Context: What is the project? What stack/conventions are relevant? Which files matter?
  • Task: What exactly needs to be done? What are the constraints and requirements?
  • Direction: Where should the agent look first? What references or docs should it consult?
  • Success criteria: What does "done" look like? What's the expected output format?
Thin prompts produce thin results. If a subagent fails or produces something off-target, the root cause is almost always an underspecified prompt — not the agent's capability.
发送子代理提示词之前，应确保其涵盖以下所有内容：
  • 上下文：项目是什么？有哪些相关的技术栈/规范？哪些文件是相关的？
  • 任务：具体需要完成什么工作？有哪些约束和要求？
  • 方向：Agent应该首先从哪里入手？需要参考哪些资料或文档？
  • 成功标准：怎样才算「完成」？期望的输出格式是什么？
简陋的提示词只会得到简陋的结果。如果子代理运行失败或输出偏离目标，根本原因几乎都是提示词不够明确，而非Agent的能力不足。