| name | explore |
| description | Explore codebases, repositories, or topics and collect key information for later phases. Use for code exploration, architecture analysis, and information gathering before implementation. |
Explore Skill
使用 ai serve 派生 独立子 agent 探索代码库、仓库或主题，收集关键信息供后续阶段使用。
⚠️ MANDATORY: 必须使用子 agent 执行
当用户触发 explore 技能时，你（调度 agent）必须通过 ai serve 派生子 agent 执行探索。禁止你自己直接用 bash/read/grep 探索。
原因：
- 子 agent 作为独立进程运行，不阻塞主对话
- 每个 agent 有独立的上下文窗口（context firewall），不污染主 agent 的对话历史
- 可以并行派生多个子 agent 同时探索不同目标
- explorer.md persona 指导子 agent 按标准格式输出
子 agent 操作详见 subagent 技能。
⚠️ MUST：在执行任何子 agent 操作前，确认 subagent 技能已加载到当前上下文。如果未加载，先调用 find_skill 工具（参数 name="subagent", load=true）加载它。未加载时不要凭猜测操作子 agent。
⛔ CONCURRENCY LIMIT: 最多 2 个子 agent 同时运行
主 agent + 子 agent 同时运行总数不得超过 3（即最多 2 个子 agent）。
原因：LLM 提供商在并发稍高时即触发 rate limit，导致子 agent 卡住或失败。
规则：
- 单次 spawn 上限：2 个子 agent
- 需要探索 3+ 个目标时，必须分批：先 spawn 2 个 → wait → cleanup → 再 spawn 下一批
你的角色（调度 agent）：解析用户意图 → 构造 input → 派生子 agent → 等待 → 汇总结果
子 agent 角色（explorer）：按 explorer.md persona 执行实际探索，写入文件
执行流程（强制）
Step 1: 准备
TARGET_PROJECT="/path/to/project"
mkdir -p "$TARGET_PROJECT/explorer"
Step 2: 派生子 agent
遵循 subagent 技能 Spawn 阶段。参数：
单目标探索：
| 参数 | 值 |
|---|
| system-prompt | @$HOME/.ai/skills/explore/explorer.md |
| input | 'Explore the authentication module. Focus on: how auth works, middleware chain, token handling. Write findings to: $TARGET_PROJECT/explorer/auth.md' |
| name | explore-auth |
| timeout | 15m |
多目标并行探索（最多 2 个 agent 同时）：
| Agent | system-prompt | input | name | timeout |
|---|
| 1 | @$HOME/.ai/skills/explore/explorer.md | 'Explore the authentication module. Write findings to: $TARGET_PROJECT/explorer/auth.md' | explore-auth | 15m |
| 2 | @$HOME/.ai/skills/explore/explorer.md | 'Explore the RPC handling layer. Write findings to: $TARGET_PROJECT/explorer/rpc.md' | explore-rpc | 15m |
spawn、等待 ID、watch 的完整代码见 subagent 技能 Spawn/Watch 阶段。本技能只定义参数。
Step 3: 等待并收集
遵循 subagent 技能 Watch 阶段，等待所有子 agent 完成。
结果由 explorer agent 写入 $TARGET_PROJECT/explorer/<target>.md。
Step 4: 清理
遵循 subagent 技能 Cleanup 阶段（ai kill + rm -f $ID_FILE）。
Step 5: 汇总
读取 $TARGET_PROJECT/explorer/ 下的文件，向用户展示关键发现。
输入构造指南
给子 agent 的 --input 应包含：
- 探索目标：要探索什么（代码库路径、模块名、主题）
- 关注点：用户特别想了解的方面（可选）
- 输出路径：
Write findings to: <绝对路径>（必须使用绝对路径）
示例 input：
Explore the project at /Users/me/project/myapp. Focus on:
- Overall architecture and module boundaries
- How authentication is implemented
- Database layer and ORM usage
Write findings to: /Users/me/project/myapp/explorer/architecture.md
特殊场景
架构约束探索
当用户提到架构变更或重构时，input 中追加：
This is an architecture exploration. You MUST also include:
- Layer/package boundaries and dependency directions
- Existing patterns for similar functionality
- Integration points: who uses this code and how
Output an "Architecture Constraints" section with a checklist.
大型仓库
对大型仓库，按模块拆分为多批探索（每批最多 2 个 agent）。每批遵循 subagent 技能完整生命周期（Spawn → Watch → Cleanup），然后再 spawn 下一批。
Batch 示例参数：
| Batch | Agent | system-prompt | input | name |
|---|
| 1 | 1 | explorer.md | 'Explore the auth module under src/auth/. Write findings to: $TARGET_PROJECT/explorer/auth.md' | explore-auth |
| 1 | 2 | explorer.md | 'Explore the API layer under src/api/. Write findings to: $TARGET_PROJECT/explorer/api.md' | explore-api |
| 2 | 3 | explorer.md | 'Explore the storage module under src/storage/. Write findings to: $TARGET_PROJECT/explorer/storage.md' | explore-storage |
| 2 | 4 | explorer.md | 'Explore the infrastructure layer. Write findings to: $TARGET_PROJECT/explorer/infra.md' | explore-infra |
每批的完整 spawn/watch/cleanup 代码见 subagent 技能。
输出约定
- 目录：
explorer/（项目根目录下）或用户指定路径
- 命名：
<target>.md
- 格式：由
explorer.md persona 定义的标准 Markdown 结构
错误处理
⚠️ MANDATORY: 子 agent 失败时，停止并报告给用户
当子 agent 失败或超时时，禁止自行诊断或重试。立即向用户报告失败信息。
报告内容：展示 agent 的最后输出（通过 ai watch 已获得）
禁止的操作：
- ❌ 盲目重新 spawn（不做分析就重试）
- ❌ 自行修改参数后重试
- ❌ 自己直接用 bash/read/grep 探索（绕过子 agent）
唯一允许的操作：
- ✅ 报告失败信息给用户
- ✅ 在用户明确指示后才执行后续操作
流程定位
用户需求
↓
┌─────────────────────┐
│ explore 技能 │ ← 你在这里：用 ai serve 派生子 agent
└──────────┬──────────┘
↓
explorer/*.md
↓
┌─────────────────────┐
│ brainstorm 技能 │ ← 基于探索结果决策
└──────────┬──────────┘
↓
design.md → PGE（Orchestrator + Generator + Evaluator）
