它到底是什么

/agents 是 Claude Code 的会话内 slash 命令，用于创建和管理自定义 subagent。

重要事实更正（v2.1.198）：v2.1.198 移除了 /agents 的交互式向导面板（此前那个带 Running / Library 两个标签页的可视化向导已不复存在）。现在 /agents 的作用是让 Claude 帮你创建 / 管理 subagent——你用自然语言描述需要什么 agent,Claude 生成对应的 .md 定义文件；当然你也可以直接编辑 .claude/agents/ 下的文件（见下文字段说明），两条路径等价。若你看到旧文档描述"打开面板、切 Running/Library 标签页"，那是被移除的旧向导口径。

关键区别：/agents（会话内命令）与 CLI 命令 claude agents 是两个独立的东西。官方文档原文特别指出："Despite the similar name, this is separate from claude agents."
claude agents 打开的是监控后台独立会话的全局 Agent View（标注为 "Research preview"），而 /agents 只管理当前会话内可用的 subagent 定义。

怎么触发 / 怎么使用

1. 创建 / 管理 subagent

会话中直接输入：

/agents

随后用自然语言告诉 Claude 你要什么 subagent（名字、职责、可用工具、模型），Claude 会生成并写入对应的 .claude/agents/<name>.md 定义；要改已有 agent，同样描述改动即可。等价地，你可以直接创建或编辑 .claude/agents/（项目级）或 ~/.claude/agents/（用户级）下的 .md 文件——格式见下方端到端示例。

2. 项目初始化时配置 subagent

官方文档将 /agents 列为新项目第一次会话的标准步骤之一，位于 /init 和 /memory 之后：

"Use /mcp and /agents to set up any servers or subagents the project needs, and /permissions to set the approval rules you want."

subagent 并发治理（环境变量）

subagent 的嵌套深度与并发数由一组环境变量管控，近几个版本默认值有过翻转，以 v2.1.219 为准：

默认翻转注意：v2.1.217 曾把"默认不允许嵌套"（深度 1）作为默认，v2.1.219 又改回"默认可嵌套到深度 3"。以最新的 v2.1.219 口径为准：默认能嵌套，要禁用得显式设 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1。

官方文档未列出向导内的键位绑定（该向导已于 v2.1.198 移除）。

保存 / 配置 / 集成

Subagent 以 .md 配置文件形式存储，分两个作用域：

每个 subagent 配置文件定义其：

• 系统提示（文件正文）
• 可用工具（官方文档原文："specific tool access"；编程式 AgentDefinition 通过 tools 字段限制工具范围）
• 独立权限（"independent permissions"）
• 可指定的模型（官方示例：路由到 Haiku 等更轻量的模型以控制成本）

与 Agent SDK 的关系：/agents 依赖交互式终端，不在 SDK system/init 消息的 slash_commands 列表中，无法通过 query() 分发调用。SDK 中可调度的命令是出现在该 slash_commands 列表中的命令（官方示例输出含 clear、compact、context、usage，以及自定义命令如 refactor、security-check，并非固定穷举）。

端到端示例：一份 .claude/agents/code-reviewer.md

下面是一份可直接落地的 subagent 文件。前两个字段 name、description 是仅有的必填项，其余可选（官方 sub-agents 文档）：

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY after code changes to review quality, security, and best practices.
tools: Read, Glob, Grep
model: haiku
---

You are a senior code reviewer. When invoked:

1. Run `git diff` against the base branch to see what changed.
2. Review only the changed lines for: correctness bugs, security issues
   (injection, secrets, authz), and clear readability/maintainability wins.
3. For each finding, output: file:line, severity (high/medium/low), the
   problematic snippet, and a concrete fix.
4. Do NOT modify files — you have read-only tools. Return a concise summary;
   the main session will apply fixes.

Skip nitpicks. Prefer a few high-confidence findings over an exhaustive list.

字段语义：name 用小写字母+连字符（hooks 的 SubagentStart 把它作为 agent_type 收到）；tools 省略则继承主会话全部工具，这里限定为只读三件套以强制"只评审不改"；model: haiku 把这个高频侧任务路由到便宜模型（详见下面成本路由小节）。文件正文即该 subagent 的完整 system prompt。

description 的措辞如何决定自动委派

官方明确："Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it." —— 也就是说是否自动触发完全由 description 这句话决定，而非文件名或正文。

• 写成被动的"Reviews code for quality"，Claude 多半只在你点名时才用它；
• 写成带触发时机+主动语气的"Use PROACTIVELY after code changes"（官方示例正是这种措辞），等于告诉 Claude"代码一改完就该委派给我"，于是 Claude 会在编辑动作后自动调用，无需你手动 @code-reviewer。

所以 description 既是"做什么"也是"什么时候自动用我"的开关——把触发条件（after X / when Y）和 PROACTIVELY/MUST BE USED 这类强度词写进去，是让 subagent 自动接管的关键。

与 hooks 的 SubagentStart / SubagentStop 联动

subagent 的生命周期会触发 hooks 事件 SubagentStart / SubagentStop，name 字段以 agent_type 形式传入，可据此做"某个 agent 启动/结束时自动跑脚本"。例如代码评审 agent 一结束就自动收集它的输出：

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "code-reviewer",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/on-review-done.sh" }
        ]
      }
    ]
  }
}

matcher 走 hooks 那套正则/精确匹配规则（注意 v2.1.195 后连字符标识符 code-reviewer 改为精确匹配，详见 hooks 指南）。也可以把 hooks 直接写进 subagent frontmatter 的 hooks 字段，作用域仅限该 subagent。

跟同类原语对比

经典使用场景

• 隔离上下文污染：将搜索日志、文件探索等会"淹没"主会话上下文的侧任务委托给 subagent，主会话只收到汇总结果
• 项目初始化：新仓库第一次会话时，用 /agents 让 Claude 快速生成项目专属 subagent（如 code-reviewer、test-runner），或直接在 .claude/agents/ 建文件
• 跨项目复用：将通用 subagent 存入用户级目录（~/.claude/agents/），一次配置，所有项目共享
• 成本控制：修改 subagent .md 里的 model 字段，将不需要高能力的侧任务路由到更轻量的模型

常见坑

1. /agents 与 claude agents 混淆：名字相似但功能截然不同。/agents 是会话内创建/管理 subagent 定义的入口（v2.1.198 起不再是可视化向导面板）；claude agents 是 CLI 入口，打开的是用于监控后台独立会话的 Agent View（实验性功能）。官方文档在 "Check on running work" 一节明确区分了两者。

2. SDK 中无法调度：/agents 需要交互式终端，在 Agent SDK 中无法通过 query() 发送，不会出现在 slash_commands 列表中。

来源

• Commands — Claude Code Docs
• Run agents in parallel — Claude Code Docs
• Create custom subagents — Claude Code Docs
• Slash Commands in the SDK — Claude Code Docs