以下將說明每款工具的查找位置、各欄位的功能、一個可從單一來源寫入這三種檔案的測試腳本,以及導致子代理靜默載入失敗的陷阱。
子代理(Subagent)還是技能(Skill)?技能會將指令新增到您目前的對話中。子代理則是一個獨立的工作者,它會以全新的上下文開始工作,完成任務後返回摘要,因此搜尋結果、日誌和檔案傾印(file dumps)不會佔用您的主執行緒。
Claude Code 的文件建議,當「次要任務會用您不會再次參考的搜尋結果、日誌或檔案內容淹沒您的主要對話」時,應使用子代理;當您「不斷生成具有相同指令的同類型工作者」時,則應使用客製化子代理。Cursor 的文件也做了同樣的區分:子代理用於長時間研究、平行工作和獨立檢查;技能則用於快速、單一目的的動作。
這三款工具都已內建輔助功能(Claude Code 的 Explore 和 Plan、Cursor 的 explore 和 browser、Codex 的 default、worker 和 explorer)。只有當您需要不同的指令或限制時,才應撰寫客製化的子代理。好的初始候選者包括無法編輯的審閱者、只報告失敗的測試執行器,以及只閱讀文件的研究員。
每款工具的查找位置:
專案:
Claude Code: .claude/agents/*.md
Cursor: .cursor/agents/*.md,以及 .claude/agents/ 和 .codex/agents/
Codex: .codex/agents/*.toml
個人:
Claude Code: ~/.claude/agents/
Cursor: ~/.cursor/agents/,~/.claude/agents/,~/.codex/agents/
Codex: ~/.codex/agents/
檔案格式:
Claude Code: Markdown,YAML 前置資料,主體 = 系統提示詞
Cursor: Markdown,YAML 前置資料,主體 = 提示詞
Codex: TOML,提示詞在 developer_instructions 中
相同名稱的處理方式:
Claude Code: 專案設定優先於個人設定;最接近工作目錄的巢狀 .claude/agents/ 勝出
Cursor: 專案設定優先於個人設定;.cursor/ 優先於 .claude/ 和 .codex/
Codex: 客製化代理若與內建代理同名(例如 explorer),則會取代內建代理
執行方式:
Claude Code: 在提示詞中命名,使用 @ 提及,或 claude --agent name
Cursor: 在提示詞中命名,或 name
Codex: 要求 Codex 以名稱生成;CLI 中的 /subagents 顯示執行緒
Claude Code 也會掃描 .claude/agents/ 的子資料夾,以及從工作目錄到儲存庫根目錄的所有 .claude/agents/,並透過 name 欄位而非檔案名稱來識別代理。Codex 也將 name 欄位作為事實的來源。當 name 遺失時,Cursor 會回退到使用檔案名稱。
每款工具讀取的欄位:
您想要的功能:
Claude Code:
必要欄位: name, description
何時委派: description
模型: model: sonnet, opus, haiku, fable, 完整的模型 ID, 或 inherit
不編輯檔案: tools 允許清單 (例如 Read, Grep, Glob) 或 disallowedTools: Write, Edit
在背景執行: background: true
額外功能: permissionMode, skills, mcpServers, hooks, memory, isolation: worktree, maxTurns, effort 等
Cursor:
必要欄位: 無 (name 預設為檔案名稱)
何時委派: description
模型: model: inherit (預設) 或模型 ID
不編輯檔案: readonly: true (不編輯檔案,不執行改變狀態的 shell 指令)
在背景執行: is_background: true
額外功能: 括號中的模型參數,例如 claude-opus-5[effort=high];features.shell_tool = false 和其他 features.* 開關;skills.config 關閉技能
Codex:
必要欄位: name, description, developer_instructions
何時委派: description (但請參閱下面的觸發條件)
模型: model 和 model_reasoning_effort;兩者都省略則使用父級設定
不編輯檔案: 無此欄位。沙盒來自父級會話
在背景執行: 非每個代理的欄位
額外功能: 無
這三款工具唯一共享的欄位是 name 和 description,以及提示詞本身。模型名稱也無法通用:sonnet 是 Claude Code 的別名,而 Cursor 接受 inherit 或模型 ID。在 Claude Code 和 Cursor 都可能讀取的 Markdown 檔案中,model: inherit 是兩者都支援的值。
陷阱一:唯讀功能在各工具中定義不同。Claude Code 透過工具清單強制執行唯讀。tools: Read, Grep, Glob 會讓子代理無法寫入檔案。若新增 Bash,它又可以透過 shell 更改檔案,因此請使用 permissions.deny 規則或 PreToolUse hook 來阻擋重要操作。
請注意,disallowedTools: Bash(git push *) 會移除整個 Bash 工具,而不僅僅是該指令。當您的主會話處於 bypassPermissions、acceptEdits 或 auto 模式時,permissionMode 會被忽略:子代理將以相同的模式執行。
Cursor 只有一個開關:readonly: true 會限制檔案編輯和改變狀態的 shell 指令。Codex 無法針對每個代理設定唯讀。子代理會繼承父級回合的沙盒和批准設定,而自訂代理檔案中的 sandbox_mode、approval_policy 或 mcp_servers 不會覆寫這些設定。
用文件中的話來說,自訂代理指令「可以要求代理避免編輯,但它們不會建立單獨的唯讀沙盒。」如果審閱者絕對不能寫入,請在委派之前以唯讀沙盒模式執行會話。
陷阱二:Cursor 也會讀取 Claude Code 的資料夾。Cursor 會載入 .claude/agents/ 以實現相容性,因此一個僅包含 Claude Code 子代理的儲存庫,其子代理也會在 Cursor 中可用。但 Cursor 的文件僅列出 name、description、model、readonly 和 is_background 這些欄位。
文件沒有說明 Cursor 如何處理僅限 Claude 的欄位(例如 tools),因此不要指望 Claude 的工具允許清單能讓代理在 Cursor 中變成唯讀。請在 .cursor/agents/ 中放置一個同名且設定 readonly: true 的 Cursor 副本:當名稱衝突時,Cursor 會使用 .cursor/ 檔案。
Cursor 也列出了 .codex/agents/,但其文件僅將子代理描述為 Markdown 檔案,並未說明是否讀取 Codex 的 TOML 檔案。我們無法確認這點,因此下面的腳本無論如何都會寫入一個 Cursor 檔案。
陷阱三:Codex 需要被明確要求。當任務與子代理的 description 相符時,Claude Code 和 Cursor 會自行委派,兩者的文件都建議使用「主動使用」等詞語來鼓勵這種行為。Codex 的文件指出,目前的本地版本會在「您直接要求或適用的 AGENTS.md 或技能指令提出請求」時生成子代理。
因此,對於 Codex,請將觸發條件新增到您的指令中,例如在 AGENTS.md 中加入:「更改程式碼後,在更改的檔案上生成 code-reviewer 代理,並在完成前修復其 Critical 發現。」
每個子代理都會執行自己的模型和工具工作,因此這三份文件都警告說,子代理比單一代理使用更多的 token。建議從兩三個子代理開始;Cursor 的文件將 50 個以上模糊的子代理稱為反模式,而 Claude Code 則會在啟動時,當所有客製化子代理的 description 總和超過 15,000 token 時發出警告。
陷阱四:Claude Code 會靜默跳過損壞的檔案。Claude Code 會「不報告錯誤」地忽略它不認識的前置資料欄位,因此 disallowed-tools 或 maxturns 等設定將不起作用。它還會在以下情況下跳過整個檔案,且會話中不會顯示任何訊息:沒有 name(它會將檔案視為文件),或者有 name 但沒有 description;開頭的 --- 不在第一行;name 以 - 開頭、包含 : 或超過 256 個字元;YAML 解析失敗。
執行 claude --debug 並搜尋日誌,或者使用 claude plugin validate .claude/agents 檢查資料夾(v2.1.233 或更高版本;它不會標記缺少 name 的情況)。如果您剛建立 agents 資料夾,請重新啟動:正在運行的會話只會監控啟動時已存在的資料夾。
單一來源,三種檔案。將每個子代理只保留一份在 agents-src/ 中,僅包含在所有地方都意義相同的欄位,然後生成三種原生檔案。來源格式刻意設計得很小:name、description 和一個可選的 readonly,然後是提示詞。
agents-src/code-reviewer.md:
---
name: code-reviewer
description: 審閱更改的程式碼是否存在錯誤、安全問題和缺少測試,不進行任何編輯。在程式碼更改後主動使用,或當使用者要求審閱當前差異時使用。
readonly: true
---
您是一位資深程式碼審閱者。您只負責審閱,絕不修改。
1. 閱讀父代理指定的所有檔案,以及每個更改所呼叫的程式碼。
2. 尋找錯誤、未處理的錯誤、安全問題(機密資訊、注入攻擊、缺少身份驗證檢查)以及沒有測試的行為更改。
3. 跳過樣式註解,除非它們隱藏了真正的錯誤。請將發現的問題分為「嚴重(Critical)」、「警告(Warning)」和「建議(Suggestion)」三組回覆。針對每個問題提供檔案:行號,並說明如何修復。如果沒有發現任何問題,請用一行文字說明。
scripts/sync_agents.py (Python 3,無需額外套件):
#!/usr/bin/env python3
"""從 agents-src/*.md 生成 Claude Code、Cursor 和 Codex 子代理檔案。
python3 scripts/sync_agents.py write .claude/agents, .cursor/agents, .codex/agents
python3 scripts/sync_agents.py --check 如果任何生成的檔案遺失或過期則退出並回傳 1
"""
import json, pathlib, re, sys
ROOT = pathlib.Path(__file__).resolve().parent.parent # repo root (script lives in scripts/)
SRC = ROOT / "agents-src"
KEYS = {"name", "description", "readonly"}
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
CLAUDE_READONLY_TOOLS = "Read, Grep, Glob"
CODEX_READONLY_NOTE = "Do not edit files or run commands that change files, git state or anything outside the repo."
def parse(path):
text = path.read_text(encoding="utf-8")
m = re.match(r"---
(.*?)
---
(.*)", text, re.S)
if not m:
sys.exit(f"{path}: must start with a --- frontmatter block")
meta = {}
for line in m.group(1).splitlines():
if not line.strip():
continue
key, sep, value = line.partition(":")
key, value = key.strip(), value.strip()
if not sep or key not in KEYS:
sys.exit(f"{path}: unknown or malformed line {line!r} (allowed keys: {', '.join(sorted(KEYS))})")
meta[key] = value.strip('"')
for key in ("name", "description"):
if not meta.get(key):
sys.exit(f"{path}: missing {key}")
if not NAME_RE.match(meta["name"]):
sys.exit(f"{path}: name must be lowercase letters, digits and single hyphens")
if meta.get("readonly", "false") not in ("true", "false"):
sys.exit(f"{path}: readonly must be true or false")
meta["readonly"] = meta.get("readonly") == "true"
meta["body"] = m.group(2).strip() + "
"
return meta
def q(s): # a double-quoted string that is valid in both YAML and TOML
return json.dumps(s, ensure_ascii=True)
def claude(a):
lines = [
"---",
f"name: {a['name']}",
f"description: {q(a['description'])}",
"model: inherit",
]
if a["readonly"]:
lines.append(f"tools: {CLAUDE_READONLY_TOOLS}")
return "
".join(lines + ["---", "", a["body"]])
def cursor(a):
lines = [
"---",
f"name: {a['name']}",
f"description: {q(a['description'])}",
"model: inherit",
]
if a["readonly"]:
lines.append("readonly: true")
return "
".join(lines + ["---", "", a["body"]])
def codex(a):
body = (CODEX_READONLY_NOTE + "
" if a["readonly"] else "") + a["body"]
instr = f"'''
{body}'''" if "'''" not in body else q(body)
return f"name = {q(a['name'])}
description = {q(a['description'])}
developer_instructions = {instr}
"
TARGETS = [
(".claude/agents", ".md", claude),
(".cursor/agents", ".md", cursor),
(".codex/agents", ".toml", codex),
]
def main():
check = "--check" in sys.argv[1:]
agents = [parse(p) for p in sorted(SRC.glob("*.md"))]
if not agents:
sys.exit(f"no agents in {SRC}")
names = [a["name"] for a in agents]
if len(set(names)) != len(names):
sys.exit("duplicate agent names in agents-src/")
stale = 0
for folder, ext, render in TARGETS:
out = ROOT / folder
out.mkdir(parents=True, exist_ok=True)
for a in agents:
f, want = out / (a["name"] + ext), render(a)
have = f.read_text(encoding="utf-8") if f.exists() else None
if have == want:
continue
stale += 1
if check:
print(f"out of date: {f.relative_to(ROOT)}")
else:
f.write_text(want, encoding="utf-8")
if check and stale:
sys.exit(1)
if __name__ == "__main__":
main()