定制 Sub-agent
Trellis 原生带有 3 个 sub-agent（trellis-implement、trellis-check、trellis-research）。你可以修改它们或新增自己的。本章以 Claude Code 格式作为主要例子，再列出其他平台的 frontmatter 差异。
Sub-agent 在 13 个配置平台里有 10 个可用：Claude Code、Cursor、OpenCode、Codex、Kiro、Gemini CLI、Qoder、CodeBuddy、Copilot、Droid。agent 文件格式按平台分 Markdown / TOML / JSON；没有 sub-agent PreToolUse hook 的平台，sub-agent 自己通过 pull-based prelude Read 自己的 implement.jsonl / check.jsonl，不靠 hook 注入。Kilo、Antigravity、Windsurf 没有 sub-agent 原语——implement / check 在主会话里内联完成。
Sub-agent 定义（Claude Code 示例）
Sub-agent 定义文件在 .claude/agents/{name}.md，使用 YAML frontmatter：
---
name: agent-name
description: |
这个 sub-agent 做什么的一句话说明，平台据此决定何时 spawn。
tools: Read, Write, Edit, Bash, Glob, Grep
---
# Agent Name
Sub-agent 的指令写在这里。把它当成 sub-agent 的 system prompt。
| 字段 | 含义 |
|---|
name | Sub-agent 标识，在 Task(subagent_type="...") 调用里使用 |
description | 主会话据此决定何时 spawn 该 sub-agent |
tools | 用逗号分隔的 sub-agent 可调用工具列表 |
model | 可选的模型覆盖。省略则继承会话模型（0.5.0-beta.5 起推荐省略，避免 Cursor 等用户被强制按 Opus 计费） |
Sub-agent 文件格式按平台不同
文件扩展名、frontmatter 形状、工具声明语法各平台不一样：
| 平台 | 文件 | 工具 / 权限字段 | 示例 |
|---|
| Claude Code | .claude/agents/{name}.md | tools:（逗号列表） | Read, Write, Edit, Bash, Glob, Grep, Task, Skill |
| Claude Code | （MCP 工具） | 同字段、加前缀 | mcp__exa__web_search_exa、mcp__chrome-devtools__* |
| Cursor | .cursor/agents/{name}.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
| OpenCode | .opencode/agents/{name}.md | permission:（对象） | { read: allow, write: allow, bash: allow, "mcp__exa__*": allow } |
| Codex | .codex/agents/{name}.toml | TOML sandbox_mode + 工具开关 | sandbox_mode = "workspace-write" |
| Kiro | .kiro/agents/{name}.json | JSON tools:（小写数组） | ["read", "write", "bash"] |
| Gemini CLI | .gemini/agents/{name}.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
| Qoder | .qoder/agents/{name}.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
| CodeBuddy | .codebuddy/agents/{name}.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
| Copilot | .github/agents/{name}.agent.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
| Droid | .factory/droids/{name}.md | CC 风格 tools: 逗号列表 | Read, Write, Edit, Bash |
packages/cli/src/templates/claude/agents/ 作为规范版，packages/cli/src/configurators/ 里各平台适配把 frontmatter 翻译成原生语法。原生的 trellis-implement / trellis-check / trellis-research 就是这么做的。
修改原生 sub-agent
示例：给 trellis-check 加 timeout 和更严的工具预算。
---
name: trellis-check
description: |
代码质量检查专家。对 diff 比对 spec，跑 lint/typecheck/test，自修复。
tools: Read, Write, Edit, Bash, Glob, Grep
timeout: 600000
---
.trellis/spec/backend/（或你团队约定的位置）里，让 sub-agent 的行为通过 spec 注入改变，而不是 fork agent 定义。
新建 sub-agent
示例：一个 trellis-test sub-agent，为当前 diff 写测试。
---
name: trellis-test
description: |
为当前 diff 写全面的测试，跑测试并汇报通过 / 失败。
tools: Read, Write, Edit, Bash, Glob, Grep
---
# trellis-test
你在 Trellis 工作流里是 trellis-test sub-agent。
## 职责
1. 分析当前 diff，识别可测单元。
2. 为新函数和组件写单元测试。
3. 为跨模块交互写集成测试。
4. 跑测试套件并汇报结果。
## 流程
#### 拿变更
```bash
git diff --name-only HEAD
```
#### 识别可测代码
对每个变更文件，找出需要测试的函数或组件。
#### 写测试
沿用仓库已有的测试模式，不要自创风格。
#### 跑测试
```bash
pnpm test
```
上下文注入
如果希望你的 sub-agent 像原生 sub-agent 那样拿到 spec 上下文：
- 约定一个 JSONL 命名（如
test.jsonl）放在每个 task 目录下。
- 在有 sub-agent
PreToolUse hook 的平台（Claude Code、Cursor、OpenCode、CodeBuddy、Droid）上，编辑 inject-subagent-context，让它处理这个新 sub-agent 类型。
- 在没有该 hook 的平台（Codex、Kiro、Gemini、Qoder、Copilot）上，参照原生 sub-agent 的”pull-based prelude”模式：在 agent 文件头部加一段要求 sub-agent 动手前先
Read 自己的 JSONL。
详细走查见第 11 章的 hook 部分。
