建立自訂 subagents

• 保留上下文，將探索和實現保持在主要對話之外
• 強制執行約束，限制 subagent 可以使用的工具
• 跨專案重複使用配置，使用使用者層級的 subagents
• 專門化行為，針對特定領域使用專注的系統提示
• 控制成本，將任務路由到更快、更便宜的模型，如 Haiku

​

內建 subagents

• 若要封鎖特定的內建類型，請將其新增至 permissions.deny，如停用特定 subagents 中所示。
• 若要防止 Claude 委派給任何 subagent，請使用 permissions.deny 拒絕 Agent 工具本身。
• 若要僅移除內建的 Explore 和 Plan subagents，請設定 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1。Claude 會直接讀取和探索檔案，而不是委派給它們。需要 Claude Code v2.1.198 或更新版本。
• 在非互動式模式和 Agent SDK 中，設定 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 以移除所有內建類型，並僅提供您自己的。

​

快速入門：建立您的第一個 subagent

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

設定子代理

​

選擇子代理範圍

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

• prompt：代理的系統提示，等同於檔案型子代理中的 markdown 主體。prompt 可能為空。如果您使用 --agent 選擇一個具有空 prompt 且沒有 memory 欄位的代理作為工作階段的代理，工作階段的系統提示保持不變。空 prompt 需要 Claude Code v2.1.281 或更新版本。
• Frontmatter 欄位：description、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、autoCompactWindow、skills、initialPrompt、memory、effort、background、omitClaudeMd 和 isolation。
• 忽略的欄位：color 和 experimental 在此不被接受，被忽略而不是拒絕。

​

編寫子代理檔案

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

• 它阻止將 git 重定向到主簽出的命令。
• 當它無法從命令文字驗證命令執行的任何 git 都保留在 worktree 內時，它拒絕命令，例如當命令名稱在執行時計算時。

​

Frontmatter 參考

• 若要找出已載入之 subagent 中拼錯的欄位，請在 shell 中執行 claude --debug，並在位於 ~/.claude/debug/<session-id>.txt 的除錯日誌中搜尋 does not recognize or apply。除錯日誌會列出 subagent 檔案中最多五個 Claude Code 無法識別的頂層欄位，並在有相近的支援欄位時提供可能想要的名稱。需要 Claude Code v2.1.296 或更新版本。
• 若要找出 subagent 檔案未載入的原因，請參閱Claude Code 跳過的 subagent 檔案。