它到底是什么

/agents 是 Claude Code 的会话内 slash 命令，用于打开当前会话的 subagent 管理面板。面板分两个标签页：

• Running — 列出当前会话内所有正在活跃的 subagent
• Library — 创建、查看和编辑自定义 subagent 的配置定义

关键区别：/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

面板打开后，Running 标签页显示活跃的 subagent；Library 标签页列出所有已定义的 subagent，可在此新建或修改。

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."

监控 / 控制 / 键位

/agents 是交互式面板，包含以下两个标签页：

官方文档未列出面板内的具体键位绑定。

保存 / 配置 / 集成

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，主会话只收到汇总结果
• 项目初始化：新仓库第一次会话时，通过 Library 标签页快速创建项目专属 subagent（如 code-reviewer、test-runner）
• 跨项目复用：将通用 subagent 存入用户级目录（~/.claude/ 下），一次配置，所有项目共享
• 成本控制：通过 Library 修改 subagent 的 model 字段，将不需要高能力的侧任务路由到更轻量的模型

常见坑

1. /agents 与 claude agents 混淆：名字相似但功能截然不同。/agents 是会话内的 subagent 管理面板；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