agent-exploration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Exploration

Agent探索

Generic parallel-research workflow. Use when a question requires deep reads across multiple distinct areas and the operator needs written artifacts (not chat output). The skill dispatches scoped-write

explorer

subagents in parallel; each invocation writes one analysis file. The parent then synthesizes a final summary.

Every slice runs as a native subagent of the current harness, inheriting the session's model and reasoning effort unless the operator pins a model. There is no agent registry, no external CLI, and nothing to install: the explorer's role, contract, and schema travel inside each slice prompt.

通用并行研究工作流。当某个问题需要跨多个不同领域深度调研，且操作者需要书面成果（而非聊天输出）时使用此技能。该技能会并行调度范围写入（scoped-write）的

explorer

子代理；每次调用会生成一份分析文件。随后由父代理合成最终总结。

每个切片都作为当前harness的原生子代理运行，继承会话的模型和推理能力，除非操作者指定了固定模型。无需代理注册表、外部CLI，也无需安装任何内容：explorer的角色、契约和架构都包含在每个切片的提示词中。

Required Reading Router

必读内容指引

Match your step to the row. Read the listed files in full before producing output. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer, not a substitute.

Step	MUST read
Step 3 — composing every slice prompt	`references/dispatch-rules.md` + `assets/explorer-prompt.md` + `assets/analysis-template.md`
Step 4 — verifying outputs	`references/checklist.md` + `assets/analysis-template.md`
Step 5 — synthesizing `summary.md`	every `<path>/analysis/NN_analysis_<slug>.md` from this round
Any contract violation, fabricated evidence, or retry	`references/dispatch-rules.md` (re-read; do not paraphrase from memory)

将你的步骤与对应行匹配。在生成输出前完整阅读列出的文件。它们不是附录——是核心内容。本SKILL.md中的内嵌内容仅为指引，不能替代原文。

步骤	必须阅读
步骤3 — 编写每个切片的提示词	`references/dispatch-rules.md` + `assets/explorer-prompt.md` + `assets/analysis-template.md`
步骤4 — 验证输出	`references/checklist.md` + `assets/analysis-template.md`
步骤5 — 合成 `summary.md`	本轮生成的所有 `<path>/analysis/NN_analysis_<slug>.md` 文件
出现任何契约违规、伪造证据或需要重试的情况	`references/dispatch-rules.md` （重新阅读；请勿凭记忆复述）

Reference Index

参考索引

```
references/dispatch-rules.md
```
— the scoped-write contract: what the dispatched subagent may write, may read, may run; tool allow/forbid lists; parent responsibilities; parallelism cap; failure handling. Must be embedded verbatim in every slice prompt.
```
references/checklist.md
```
— seven-section output validation checklist (runtime, inputs, scout, dispatch, files, schema, summary). Run before authoring
```
summary.md
```
.
```
assets/analysis-template.md
```
— the canonical seven-section schema every dispatched subagent fills (Overview, Mechanisms/Patterns, Relevant Sources, Transferable Patterns, Risks/Mismatches, Open Questions, Evidence) plus a Scope header.
```
assets/explorer-prompt.md
```
— the explorer role prompt (the scoped-write contract and workflow from the dispatched subagent's perspective). Embedded verbatim at the top of every slice prompt.

```
references/dispatch-rules.md
```
— 范围写入契约：调度的子代理可写入、读取、运行的内容；工具允许/禁止列表；父代理职责；并行度上限；故障处理。必须逐字嵌入每个切片的提示词中。
```
references/checklist.md
```
— 七节输出验证清单（运行时、输入、侦察、调度、文件、架构、总结）。在撰写
```
summary.md
```
前执行检查。
```
assets/analysis-template.md
```
— 每个调度的子代理必须填写的标准七节架构（概述、机制/模式、相关来源、可迁移模式、风险/不匹配点、开放问题、证据），外加范围标题。
```
assets/explorer-prompt.md
```
— explorer角色提示词（从调度的子代理视角出发的范围写入契约和工作流）。必须逐字嵌入每个切片提示词的顶部。

Bundled Path Rule

捆绑路径规则

Resolve every bundled file relative to the directory that holds this

SKILL.md

. When a path appears below as

references/<name>

assets/<name>

, expand it to

<agent-exploration-dir>/references/<name>

— the absolute skill directory — before reading or embedding it.

所有捆绑文件的路径均相对于本

SKILL.md

所在目录。当路径显示为

references/<name>

或

assets/<name>

时，在读取或嵌入前需扩展为

<agent-exploration-dir>/references/<name>

——即技能的绝对目录。

Required Inputs

必填输入

```
--path <dir>
```
(required): Output directory. Analysis files are written under
```
<path>/analysis/
```
. Any project-relative or absolute directory works (for example
```
docs/research/<topic>/
```
,
```
tasks/<slug>/
```
, or a path outside the repo). The skill is not tied to any specific project layout.
```
--agents <num>
```
(optional, default 3, hard cap 8): Number of explorer subagents to dispatch in parallel.
```
--prompt <text>
```
(required): The research question. Quoted multi-line strings are supported. If omitted, the parent asks the operator before continuing.
```
--model <name>
```
(optional; default: inherit the session's model): Per-slice model override, forwarded through the harness's native per-subagent model parameter. If the harness exposes no such parameter, stop and tell the operator — never substitute a different model than requested.

--path

--prompt

is missing, the parent asks the operator a single clarification before continuing. Never invent defaults for either. Apply the documented defaults for

--agents

and

--model

silently when omitted.

```
--path <dir>
```
（必填）：输出目录。分析文件将写入
```
<path>/analysis/
```
下。任何项目相对路径或绝对路径均可（例如
```
docs/research/<topic>/
```
、
```
tasks/<slug>/
```
或仓库外的路径）。本技能不绑定任何特定项目布局。
```
--agents <num>
```
（可选，默认值3，上限8）：并行调度的explorer子代理数量。
```
--prompt <text>
```
（必填）：研究问题。支持带引号的多行字符串。若省略，父代理会在继续前询问操作者。
```
--model <name>
```
（可选；默认值：继承会话模型）：每个切片的模型覆盖参数，通过harness的原生子代理模型参数传递。若harness未提供该参数，请停止操作并告知操作者——绝不能替换为请求之外的其他模型。

若

--path

或

--prompt

缺失，父代理会询问操作者一次以明确信息，然后继续操作。绝不为这两个参数自行设置默认值。当

--agents

和

--model

省略时，静默应用文档中规定的默认值。

Output Layout

输出布局

<path>/analysis/
├── 01_analysis_<slug-a>.md
├── 02_analysis_<slug-b>.md
├── 03_analysis_<slug-c>.md
└── summary.md

File numbering is zero-padded to two digits (
```
01
```
,
```
02
```
, …,
```
08
```
).
Each slug is a short kebab-case identifier the parent assigns during the scout (Step 2), reflecting that slice's focus.
```
summary.md
```
is parent-authored synthesis, not a dispatched output.

<path>/analysis/
├── 01_analysis_<slug-a>.md
├── 02_analysis_<slug-b>.md
├── 03_analysis_<slug-c>.md
└── summary.md

文件编号采用两位数字补零格式（
```
01
```
、
```
02
```
……
```
08
```
）。
每个slug是父代理在侦察阶段（步骤2）分配的短横线命名标识符，反映该切片的研究重点。
```
summary.md
```
由父代理撰写合成，并非调度生成的输出。

Procedures

操作流程

Step 1: Resolve inputs

Confirm the current harness exposes a native subagent facility. If it does not, stop and tell the operator — this skill dispatches slices only as native subagents.
Parse
```
--path
```
,
```
--agents
```
,
```
--prompt
```
,
```
--model
```
from the invocation. If
```
--path
```
or
```
--prompt
```
is missing, ask the operator and stop.
Default
```
--agents
```
to
```
3
```
when omitted. Reject values below 1 or above 8 — ask the operator to choose a value in range.
Do not validate
```
--model
```
ahead of time — the harness surfaces incompatibilities at dispatch; when one does, report it to the operator and re-dispatch the slice with the model they choose.
Resolve
```
--path
```
to an absolute path. If the directory does not exist, ask the operator whether to create it before continuing; if creation fails, stop and report the filesystem error.
Create
```
<path>/analysis/
```
if absent. The dispatched subagents refuse to write into a missing directory.

Step 2: Parent-led initial scout (MANDATORY — do not skip)

The scout is the load-bearing step that prevents wasted parallel dispatch. The parent must do this work itself before any slice is launched.

Perform a brief read-only exploration of the problem space using path globs, content searches, and targeted file reads. The scout's job is to learn enough about the territory to divide it well — not to produce analysis content. Cap the scout at 8–15 tool calls; deep reading belongs to the dispatched subagents.
From the scout, identify exactly
```
--agents
```
distinct slices that are:
- Non-overlapping — two slices should not require reading the same primary files for the same purpose.
- Independently answerable — a slice's analysis must not depend on another slice's output.
- Aligned with the operator's
  --prompt
  — every slice serves the original research question.
For each slice, assign:
- A two-digit ordinal (
```
01
```
  ..
```
08
```
  ).
- A short kebab-case slug (≤ 4 words) reflecting that slice's focus (e.g.
```
state-machine
```
  ,
```
event-bus
```
  ,
```
auth-boundaries
```
  ).
- A focused per-slice prompt that names the slice question, the primary source paths/URLs to read, and any cross-references the dispatched subagent should use.
Briefly tell the operator the slice list (one line per slice:
```
NN – slug – focus
```
) before dispatching. Do not ask for approval unless the slices look thin or overlap; just announce and proceed.

If the scout reveals that fewer than

--agents

non-overlapping slices exist, reduce the dispatch count and tell the operator. Do not pad slices to hit the requested count.

Step 3: Dispatch explorer subagents in parallel

Gist tripwires — the contract items the parent must enforce in every dispatched prompt:

The prompt names three things: slice scope, slug+ordinal, exact target file path. If any is missing, the dispatched subagent must refuse and ask back.
The dispatched subagent gets exactly one file-write — at the named target path — and nothing else. No edits, no
```
git
```
/
```
make
```
/package managers, no writes outside
```
<path>/analysis/
```
.
All slices dispatch in parallel — one subagent call per slice, issued in a single batch. Wait for every slice to finish before verification.

STOP. Read
references/dispatch-rules.md
in full before composing any slice prompt. That file contains the complete scoped-write contract, tool allow/forbid lists, parent responsibilities, and failure handling. The bullets above are tripwires, not the contract — the contract must be embedded verbatim in every slice prompt.

STOP. Read
assets/explorer-prompt.md
in full before composing any slice prompt. That file is the explorer's role prompt — it must open every slice prompt verbatim so the dispatched subagent knows its contract.

STOP. Read
assets/analysis-template.md
in full before composing any slice prompt. That file is the canonical seven-section schema every dispatched subagent fills. The schema must be embedded in the prompt; do not paraphrase it.

Compose one slice prompt per slice. Every prompt MUST include, in this order:

```
assets/explorer-prompt.md
```
content embedded verbatim (the explorer's role and contract).
The operator's original
```
--prompt
```
verbatim, prefixed by a short orientation line.
The slice's focused question and the primary sources to read.
The exact target path:
```
<path>/analysis/NN_analysis_<slug>.md
```
(absolute path).
```
references/dispatch-rules.md
```
content embedded verbatim (copy-paste, do not paraphrase).
The seven-section schema from
```
assets/analysis-template.md
```
.

Write each composed prompt to its own file at

<path>/.dispatch/prompts/NN_<slug>.txt

— the round's audit trail and the exact text to re-dispatch on a slice failure. The file basename (without extension) is the slice id.

Issue one subagent call per slice — all in a single parallel batch, using whatever async/parallel subagent facility the harness exposes. Each call passes the slice prompt file content verbatim as the subagent's prompt, grants read/search access plus file-write capability (the embedded contract confines the subagent to one write), and applies a model override only when the operator pinned one. Wait for every subagent to complete before Step 4. A subagent that errors, or returns without its written-path confirmation, is a failed slice — re-dispatch it with the contract restated. Never synthesize a missing slice's analysis as if its dispatch succeeded.

Step 4: Verify outputs

Gist tripwires — the floor items that catch most failures:

Every slice finished clean — its subagent returned the written-path confirmation (path written, seven sections). Anything else is a slice failure, not a warning.
Exactly
```
N
```
files at the expected
```
NN_analysis_<slug>.md
```
paths under
```
<path>/analysis/
```
.
All seven schema sections present in each file; no empty sections without a gap-note + Open Question.
At least one cited source per file sample-checked (read local paths; check URL well-formedness).

STOP. Read
references/checklist.md
in full before declaring outputs verified. That file is the seven-section output validation checklist (runtime, inputs, scout, dispatch, files, schema, summary). Every item must pass; failing items trigger a re-dispatch of the offending slice. The bullets above are tripwires, not the contract.

If a section is empty, a file is missing, a cited path is fake, or the schema is incomplete, re-dispatch the offending slice with the schema embedded and a request to fill the gap. The parent never authors the missing analysis content — the dispatched subagent owns the write.

Step 5: Synthesize
summary.md

Read every
```
<path>/analysis/NN_analysis_<slug>.md
```
in full.
Author
```
<path>/analysis/summary.md
```
with these sections:
- Research Question — the operator's
```
--prompt
```
  , verbatim.
- Slice Map — table mapping each
```
NN – slug
```
  to its slice question and one-line finding.
- Convergences — patterns or risks that appear in two or more analyses, with cross-citations to the slice files.
- Divergences — places where slices disagree or where one slice surfaces a finding the others miss.
- Risks & Open Questions — consolidated, deduplicated list pulled from each analysis's Open Questions and Risks/Mismatches sections.
- Recommended Next Steps — short, actionable list. Each step cites the slice file(s) that support it.
- Index — bullet list of
```
<path>/analysis/NN_analysis_<slug>.md
```
  paths so a future reader can drill in.
```
summary.md
```
is parent-authored. Do not dispatch a slice for this step.

步骤1：解析输入

确认当前harness支持原生子代理工具。若不支持，停止操作并告知操作者——本技能仅能以原生子代理形式调度切片。
从调用命令中解析
```
--path
```
、
```
--agents
```
、
```
--prompt
```
、
```
--model
```
参数。若
```
--path
```
或
```
--prompt
```
缺失，询问操作者后停止操作。
若
```
--agents
```
省略，默认设置为
```
3
```
。拒绝小于1或大于8的值——请操作者选择范围内的数值。
无需提前验证
```
--model
```
——harness会在调度时暴露兼容性问题；若出现兼容性问题，向操作者报告并使用其选择的模型重新调度切片。
将
```
--path
```
解析为绝对路径。若目录不存在，询问操作者是否创建后再继续；若创建失败，停止操作并报告文件系统错误。
若
```
<path>/analysis/
```
不存在则创建该目录。调度的子代理拒绝写入不存在的目录。

步骤2：父代理主导的初始侦察（必须执行——请勿跳过）

侦察是避免并行调度浪费资源的核心步骤。父代理必须在启动任何切片前自行完成此工作。

使用路径通配符、内容搜索和定向文件读取，对问题空间进行简短的只读探索。侦察的任务是充分了解研究领域以合理划分切片——而非生成分析内容。侦察阶段的工具调用次数上限为8-15次；深度阅读属于调度的子代理的工作。
通过侦察，确定恰好
```
--agents
```
个满足以下条件的独立切片：
- 无重叠——两个切片不应因相同目的而需要读取相同的核心文件。
- 可独立解答——一个切片的分析不应依赖另一个切片的输出。
- 与操作者的
  --prompt
  一致——每个切片都服务于原始研究问题。
为每个切片分配：
- 两位数字序号（
```
01
```
  ..
```
08
```
  ）。
- 反映切片研究重点的短横线命名slug（≤4个词，例如
```
state-machine
```
  、
```
event-bus
```
  、
```
auth-boundaries
```
  ）。
- 聚焦的切片提示词，包含切片问题、需读取的核心源路径/URL，以及调度的子代理应使用的任何交叉引用。
在调度前向操作者简要告知切片列表（每个切片一行：
```
NN – slug – 研究重点
```
）。除非切片内容单薄或存在重叠，否则无需请求批准，直接告知后继续操作。

若侦察发现符合条件的无重叠切片数量少于

--agents

，则减少调度数量并告知操作者。请勿为达到请求的数量而填充无关切片。

步骤3：并行调度explorer子代理

核心规则——父代理必须在每个调度的提示词中强制执行的契约条款：

提示词需包含三项内容：切片范围、slug+序号、精确目标文件路径。若缺少任何一项，调度的子代理必须拒绝并反馈。
调度的子代理仅能进行一次文件写入——写入指定目标路径，不得进行其他操作。禁止编辑、
```
git
```
/
```
make
```
/包管理器操作，禁止写入
```
<path>/analysis/
```
之外的路径。
所有切片并行调度——每个切片对应一次子代理调用，批量发起。等待所有切片完成后再进行验证。

停止操作。在编写任何切片提示词前完整阅读
references/dispatch-rules.md
。该文件包含完整的范围写入契约、工具允许/禁止列表、父代理职责和故障处理。以上要点仅为核心提醒，而非完整契约——契约必须逐字嵌入每个切片的提示词中。

停止操作。在编写任何切片提示词前完整阅读
assets/explorer-prompt.md
。该文件是explorer的角色提示词——必须逐字作为每个切片提示词的开头，让调度的子代理了解其契约。

停止操作。在编写任何切片提示词前完整阅读
assets/analysis-template.md
。该文件是每个调度的子代理必须填写的标准七节架构。架构必须嵌入提示词中，请勿复述。

为每个切片编写一份提示词。每个提示词必须按以下顺序包含：

逐字嵌入
```
assets/explorer-prompt.md
```
的内容（explorer的角色和契约）。
逐字包含操作者的原始
```
--prompt
```
，前缀添加简短的说明行。
切片的聚焦问题和需读取的核心源。
精确目标路径：
```
<path>/analysis/NN_analysis_<slug>.md
```
（绝对路径）。
逐字嵌入
```
references/dispatch-rules.md
```
的内容（直接复制粘贴，请勿复述）。
```
assets/analysis-template.md
```
中的七节架构。

将每个编写好的提示词写入

<path>/.dispatch/prompts/NN_<slug>.txt

文件——这是本轮操作的审计记录，也是切片失败时重新调度的精确文本。文件名（不含扩展名）即为切片ID。

为每个切片发起一次子代理调用——所有调用作为单个并行批次，使用harness提供的任何异步/并行子代理工具。每次调用将切片提示词文件内容逐字作为子代理的提示词，授予读取/搜索权限和文件写入能力（嵌入的契约将子代理限制为一次写入），仅当操作者指定固定模型时才应用模型覆盖参数。等待所有子代理完成后再进入步骤4。若子代理报错或未返回写入路径确认，则视为切片失败——重新调度该切片并重述契约。绝不能假装调度成功而自行合成缺失切片的分析内容。

步骤4：验证输出

核心规则——识别大多数故障的基础检查项：

每个切片均正常完成——子代理返回写入路径确认（已写入路径、包含七节内容）。任何其他情况均视为切片失败，而非警告。
```
<path>/analysis/
```
下存在恰好
```
N
```
个符合预期路径的
```
NN_analysis_<slug>.md
```
文件。
每个文件包含所有七节架构内容；若存在空节，必须附带说明备注和开放问题。
抽样检查每个文件，确保至少包含一个引用源（读取本地路径；检查URL格式是否正确）。

停止操作。在宣布输出验证通过前完整阅读
references/checklist.md
。该文件是七节输出验证清单（运行时、输入、侦察、调度、文件、架构、总结）。所有项必须通过；若有项未通过，触发对应切片的重新调度。以上要点仅为核心提醒，而非完整契约。

若某节内容为空、文件缺失、引用路径无效或架构不完整，重新调度该问题切片，嵌入架构并要求填补空白。父代理绝不能自行撰写缺失的分析内容——调度的子代理负责写入操作。

步骤5：合成
summary.md

完整阅读所有
```
<path>/analysis/NN_analysis_<slug>.md
```
文件。
撰写
```
<path>/analysis/summary.md
```
，包含以下章节：
- 研究问题——逐字包含操作者的
```
--prompt
```
  。
- 切片映射——表格，将每个
```
NN – slug
```
  映射到其切片问题和一行核心发现。
- 趋同点——在两个或多个分析中出现的模式或风险，附带切片文件的交叉引用。
- 分歧点——切片结论不一致的地方，或某一切片发现其他切片未提及内容的地方。
- 风险与开放问题——从每个分析的“开放问题”和“风险/不匹配点”章节中提取并去重后的汇总列表。
- 建议后续步骤——简短、可执行的列表。每个步骤需引用支持该步骤的切片文件。
- 索引——
```
<path>/analysis/NN_analysis_<slug>.md
```
  路径的项目符号列表，方便后续读者深入查看。
```
summary.md
```
由父代理撰写。请勿为此步骤调度切片。

When Not To Use

不适用于以下场景

Single-file lookups ("where is X defined?", "what does function Y return?"): answer directly with the harness's search and file-reading tools. This skill is overkill.
Edits to existing code: the explorer is scoped-write — it can only create new analysis files, not modify anything else.
Tightly scoped competitor / reference-repo research in projects that already ship a more specialized variant (for example a project-local skill that mirrors a fixed competitor catalog). Use that variant when it exists; use this skill as the generic fallback.

单文件查询（“X定义在哪里？”、“函数Y返回什么？”）：直接使用harness的搜索和文件读取工具回答。使用本技能过于冗余。
编辑现有代码：explorer是范围写入型代理——仅能创建新的分析文件，无法修改其他内容。
范围狭窄的竞品/参考仓库调研，且项目已提供更专业的变体（例如项目本地技能固定映射竞品目录）。若存在该变体则使用它；本技能作为通用备选方案。

Error Handling

错误处理

Input and scout failures are handled inline where they occur — each item in Steps 1–2 names its own recovery. Contract violations, fabricated evidence, schema-incomplete analyses, and retries route through the Required Reading Router: STOP, re-read
references/dispatch-rules.md
in full, then re-dispatch the offending slice — the dispatched subagent owns the write. One round-level rule lives only here:

Network/disk error during dispatch: fail the round entirely — a half-set of analyses is unacceptable. Re-dispatch after the error is resolved.

输入和侦察阶段的故障在对应步骤中即时处理——步骤1-2中的每个项都说明了恢复方式。契约违规、伪造证据、架构不完整的分析和重试需遵循必读内容指引：停止操作，完整重新阅读
references/dispatch-rules.md
，然后重新调度问题切片——调度的子代理负责写入操作。仅在此处有一条全局规则：

调度期间出现网络/磁盘错误：终止本轮操作——不接受不完整的分析集合。错误解决后重新调度。