Claude Code 核心概念详解：代理、子代理、代理团队、工具、技能、插件、钩子本文基于Claude Code官方文

本文基于 Claude Code 官方文档整理，结合实际使用经验，系统梳理 Claude Code 的七大核心概念。无论你是刚开始使用还是想深入定制，这篇文章都能帮你建立完整的认知框架。

前言

Claude Code 是 Anthropic 推出的 CLI 编程工具，它不是简单的 AI 聊天框，而是一个具备自主行动能力的编程代理。理解它的核心概念，才能真正发挥它的能力。

本文将覆盖以下七个概念：

概念	一句话	谁来创建
代理	Claude Code 本身，负责与你对话并执行任务	Anthropic 内置
子代理	独立完成特定任务的专家助手	Anthropic 内置 + 可自定义
代理团队	多个独立 Claude 实例协同工作，适合大型并行任务	你发起，代理协调
工具	代理能做的具体动作（读文件、改文件等）	Anthropic 内置 + MCP 扩展
技能	预设好的专业工作流，可用 `/命令` 或自然语言触发	Anthropic 内置 + 可自定义
插件	打包好的扩展包，可包含子代理、技能、钩子等	你自己创建
钩子	特定事件发生时自动执行的命令	你自己配置

一、代理（Agent）—— Claude Code 的大脑

代理就是你正在交互的 Claude Code 本身。你在终端里跟它说话，它理解你的意图，然后调用各种工具、子代理和技能来完成任务。

它的职责：

理解你说的话
决定用哪些工具完成任务
决定要不要启动子代理协助
最终把结果返回给你

它的特点：

始终在运行，你不需要手动启动
拥有对话记忆（当前会话内）
统一协调工具、子代理、技能的使用

你 ←→ 代理（Claude Code）
         ↓  ↓  ↓
        工具 子代理 技能

你只需要跟代理对话，剩下的事情它会自己安排。

二、子代理（Sub-agent）—— 派出去的专家

子代理是代理派出去独立完成特定任务的「专家助手」。它们在后台独立运行，不占用主对话的注意力，完成后把结果返回。

内置子代理

Claude Code 内置了 3 个主要子代理和若干辅助子代理：

主要子代理：

子代理	使用模型	专长	什么时候启动
Plan	继承主对话	Plan mode 下的代码库研究和上下文收集（只读）	进入 plan mode 时
Explore	Haiku（快速）	搜索和分析代码库（只读）	需要定位代码时
General-purpose	继承主对话	复杂多步任务（全工具权限）	需要独立调研时

辅助子代理（自动调用，通常不需要你关注）：

子代理	用途
Bash	在独立上下文中执行终端命令
statusline-setup	配置状态栏
Claude Code Guide	回答 Claude Code 功能相关的问题

自定义子代理

有三种方式创建自定义子代理：

方式一：/agents 交互命令（推荐）

在 Claude Code 中输入 /agents，按引导式界面操作即可。

方式二：Markdown 文件（持久化，可提交到项目仓库）

# 项目级
.claude/agents/<名称>.md

# 用户级
~/.claude/agents/<名称>.md

文件内容示例：

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

你是高级代码审查员，关注代码质量、可读性和安全性...

Markdown 文件还支持更多可选字段：disallowedTools（禁用工具）、permissionMode（权限模式）、skills（可用技能）、hooks（子代理作用域钩子）、memory（持久内存，可跨会话积累知识）等。

方式三：--agents CLI 参数（临时，仅当前会话）

claude --agents '{
  "code-reviewer": {
    "description": "专门负责代码审查",
    "prompt": "你是高级代码审查员，关注代码质量和安全性",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

子代理运行流程：

主代理判断任务复杂 → 派出子代理
        ↓
子代理独立完成工作（后台运行）
        ↓
结果返回给主代理
        ↓
主代理整合结果给你

三、代理团队（Agent Teams）—— 多人协作的项目组

⚡ 这是一个实验性功能，需要手动开启。

代理团队是 Claude Code 最新推出的高级协作模式。与子代理不同，代理团队让多个完全独立的 Claude Code 实例组成团队并行工作。

子代理 vs 代理团队

先搞清楚它们的本质区别：

维度	子代理	代理团队
上下文	共享主代理的上下文窗口	每个队友独立上下文窗口
通信	只能和主代理通信	队友之间可直接通信
适合场景	单步/有限步骤任务	大型并行任务
Token 消耗	较少	较多（多个独立实例）
稳定性	稳定	实验性

简单理解：

子代理 = 主代理派出去的助手，做完就回来汇报
代理团队 = 组建了一个项目组，每个成员独立工作，还能互相沟通

启用方式

代理团队默认关闭，需要在 settings.json 中开启：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或通过环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

团队角色

角色	说明
团队领导（Team Lead）	主 Claude Code 会话，负责创建团队、分配任务、协调工作、汇总结果
队友（Teammates）	独立的 Claude Code 实例，认领和执行任务，可彼此直接通信

协调机制

团队不是各干各的，有一套完整的协调机制：

机制	说明
共享任务列表	团队成员通过任务列表协调工作
任务依赖	被阻塞的任务在依赖完成后自动解锁
消息邮箱	队友间可通过 `message`（一对一）或 `broadcast`（广播）通信
文件锁	防止多个队友同时认领同一任务

如何启动团队

用自然语言告诉 Claude Code 就行：

我在设计一个 CLI 工具，帮开发者追踪代码中的 TODO 注释。
创建一个代理团队从不同角度探索：
一个队友负责用户体验，一个负责技术架构，一个扮演"魔鬼代言人"。

也可以指定团队规模和模型：

创建一个 4 人团队并行重构这些模块。每个队友使用 Sonnet 模型。

显示模式

{
  "teammateMode": "in-process"
}

模式	说明	要求
in-process	队友在主终端运行，`Shift+Down` 切换	任何终端都能用
tmux	分屏显示每个队友	需要安装 tmux
auto（默认）	在 tmux 中时分屏，否则 in-process	自动适配

常用快捷键（in-process 模式）：

快捷键	作用
`Shift+Down`	切换到下一个队友
`Enter`	查看队友会话
`Escape`	中断队友当前任务
`Ctrl+T`	切换任务列表

最佳实践

给队友充足的上下文（队友不继承领导的对话历史）
避免文件冲突：每个队友负责不同的文件
每个队友分配 5-6 个任务为最佳平衡点
先从研究/审查类任务开始，再做并行实现
提前配置好权限设置，减少权限确认弹窗

当前限制

不支持 /resume 恢复 in-process 队友
每个会话最多一个团队，不能嵌套
团队领导固定，不能切换
分屏模式不支持 VS Code 集成终端和 Windows Terminal
Token 消耗显著增加（每个队友独立消耗）

四、工具（Tools）—— 大脑的双手

工具是代理（和子代理）能执行的具体操作能力。你不直接调用工具，代理自动判断并调用。

常用内置工具

工具	作用	使用规则
Read	读取文件内容	修改文件前必须先 Read
Write	创建新文件	直接创建，无需先 Read
Edit	修改已有文件	必须先 Read 再 Edit
Bash	执行终端命令	npm、git 等操作
Glob	按模式查找文件	支持 `*/.tsx` 等模式
Grep	搜索文件内容	支持正则表达式
WebFetch	获取和处理网页内容	读取网页信息
WebSearch	搜索网页	搜索互联网信息
NotebookEdit	编辑 Jupyter Notebook	修改 `.ipynb` 文件
Task	启动子代理	代理内部调用

MCP 扩展工具

MCP（Model Context Protocol）是 Anthropic 制定的标准协议，让 Claude Code 通过工具接入外部服务（数据库、API 等）。

比如你可以通过 MCP 接入 MySQL 数据库，Claude Code 就能直接帮你查询和操作数据。MCP 工具的名称格式为 mcp__<server>__<tool>。

限制工具

启动时可以限制代理能使用的工具：

# 禁止使用某些工具
claude --disallowedTools "Edit,Write"

# 只允许使用指定工具
claude --tools "Bash,Edit,Read"

五、技能（Skills）—— 预设的工作模板

技能是预设好的专业工作流，一个指令带动整套流程自动执行。

触发方式

方式一：斜杠命令（明确触发）
  你: /commit
  → 技能直接启动

方式二：自然语言（代理根据 description 字段匹配）
  你: "帮我提交代码"
  → 代理判断意图匹配 → 可能自动触发 /commit 技能

自然语言触发的可靠性取决于技能文件的 description 字段写得是否清晰。技能可以设置 disable-model-invocation: true 来禁止自然语言触发，也可以设置 user-invocable: false 让技能仅由 Claude 自动调用。

常用内置技能

技能命令	作用	适合场景
`/commit`	自动生成 Git 提交信息并提交	代码改完要提交时
`/pdf`	PDF 的创建、合并、加密等全流程	处理 PDF 文件时
`/xlsx`	Excel 表格的读写、格式化	处理 Excel 时
`/pptx`	演示文稿的创建和编辑	做 PPT 时
`/frontend-design`	创建高质量 UI 组件和页面	做前端界面时
`/doc-coauthoring`	协作文档编写工作流	写文档、规范时
`/mcp-builder`	构建 MCP 服务器	接入外部 API 时

自定义技能

技能文件存放位置：

位置	作用范围
`.claude/skills/<技能名>/SKILL.md`	当前项目
`~/.claude/skills/<技能名>/SKILL.md`	你的所有项目

示例（.claude/skills/deploy/SKILL.md）：

---
name: deploy
description: Deploys the project to production. Use when user asks to deploy or release.
allowed-tools: Bash
context: fork
agent: Explore
---

执行以下部署步骤：
1. npm run build
2. 上传到服务器
3. 重启服务

主要 frontmatter 字段

字段	作用
`name`	技能名称，成为 `/命令名`
`description`	Claude 根据此字段判断是否自动触发
`allowed-tools`	技能激活时可免权限确认使用的工具
`context`	设为 `fork` 则在隔离的子代理中运行
`agent`	`context: fork` 时指定使用哪种子代理类型
`model`	指定技能使用的模型
`disable-model-invocation`	设为 `true` 则只能手动 `/命令` 触发
`user-invocable`	设为 `false` 则从 `/` 菜单隐藏

`/commit` 技能执行流程示例

你: /commit
  ↓
技能启动
  ↓
工具(Bash): git diff 查看变更内容
  ↓
分析改动类型（fix / feat / chore 等）
  ↓
生成规范的提交信息
  ↓
工具(Bash): git commit 执行提交
  ↓
告诉你提交结果

六、插件（Plugins）—— 打包的扩展包

插件是一个完整的扩展包，把子代理、技能、钩子、MCP 工具等打包在一起，便于团队共享和复用。

没有团队协作或复杂定制需求时不需要使用。

插件能包含什么

插件可包含	对应文件
技能	`skills/<名称>/SKILL.md`
子代理	`agents/<名称>.md`
钩子	`hooks/hooks.json`
MCP 工具	`.mcp.json`
LSP 语言服务器	`.lsp.json`
默认设置	`settings.json`

插件目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件清单（必需）
├── skills/
│   └── deploy/
│       └── SKILL.md         # 自定义 /my-plugin:deploy 技能
├── agents/
│   └── qa-expert.md         # 自定义 QA 子代理
├── hooks/
│   └── hooks.json           # 事件钩子配置
├── .mcp.json                # MCP 工具配置
├── .lsp.json                # LSP 语言服务器配置
└── settings.json            # 默认设置

插件中的技能名称带命名空间前缀，避免冲突，例如 /my-plugin:deploy。

使用方式

# 加载插件
claude --plugin-dir ./my-plugin

# 加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

插件 vs 单独配置

不用插件（单独配置）：
  自定义子代理  → .claude/agents/*.md
  自定义技能   → .claude/skills/*/SKILL.md
  钩子配置    → .claude/settings.json

用插件（打包配置）：
  一个目录 → 子代理 + 技能 + 钩子 + MCP 全部打包
  团队共享：一行命令加载所有能力
  版本化管理：可发布到 GitHub 等代码仓库

七、钩子（Hooks）—— 自动触发的守卫

钩子是在特定事件发生时自动执行的命令，可以独立使用，不需要插件。

配置位置

位置	作用范围
`~/.claude/settings.json`	你的所有项目
`.claude/settings.json`	仅当前项目（可提交 git）
`.claude/settings.local.json`	仅当前项目（不提交 git）

也可以在交互模式中用 /hooks 命令通过引导式界面管理，不需要手动编辑 JSON。

常用事件

官方共支持 17 种事件，以下为常用的：

事件	触发时机
`PreToolUse`	代理使用工具前
`PostToolUse`	代理使用工具后
`PostToolUseFailure`	工具调用失败时
`UserPromptSubmit`	你提交消息时
`PermissionRequest`	权限确认对话出现时
`Stop`	Claude 完成回复时
`SubagentStart` / `SubagentStop`	子代理启动/结束时
`SessionStart` / `SessionEnd`	会话开始/结束时
`PreCompact`	上下文压缩前
`ConfigChange`	配置文件变更时

钩子的三种类型

类型	说明	适用场景
`type: "command"`	执行 Shell 命令	运行 lint、格式化等
`type: "prompt"`	使用 LLM 评估是否允许/阻止操作	智能判断是否放行
`type: "agent"`	启动有工具权限的子代理来验证	需要读取文件等复杂验证

配置示例

每次代理修改文件后自动运行 lint 检查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  }
}

matcher 字段用于匹配工具名称，支持 | 分隔多个工具。

它们之间的关系

层级关系图

┌─────────────────────────────────────────┐
│              你（用户）                  │
└───────────────────┬─────────────────────┘
                    │ 对话 / 命令
                    ↓
┌─────────────────────────────────────────┐
│           代理（Agent）                  │
│        Claude Code 主体                 │
│   ┌──────────┬──────────┬───────────┐   │
│   │  工具    │  子代理   │   技能    │   │
│   │  Read   │  Plan    │ /commit   │   │
│   │  Edit   │  Explore │ /pdf      │   │
│   │  Bash   │  自定义   │  自定义   │   │
│   │  Glob   │  ...     │  ...      │   │
│   │  Grep   │          │           │   │
│   │  MCP... │          │           │   │
│   └──────────┴──────────┴───────────┘   │
│                                         │
│   钩子（自动触发，监听各类事件）          │
└────────────┬────────────────────────────┘
             │ 可扩展
     ┌───────┴───────┐
     ↓               ↓
┌──────────┐  ┌───────────────────────────┐
│  插件    │  │    代理团队（Agent Teams） │
│ 打包扩展 │  │  领导 ←→ 队友1            │
│          │  │        ←→ 队友2            │
│          │  │        ←→ 队友3            │
│          │  │  （独立实例，并行工作）      │
└──────────┘  └───────────────────────────┘

调用关系一览

代理                    →  使用  →  工具（直接调用）
代理                    →  派出  →  子代理（独立运行，共享上下文）
代理（作为领导）         →  组建  →  代理团队（独立实例，并行工作）
你（/命令 或自然语言）   → 经代理  →  触发技能
技能                    →  依赖  →  工具（技能内部用工具完成工作）
子代理                  →  也用  →  工具（子代理有自己的工具权限）
队友                    →  彼此  →  直接通信（不需经过领导）
钩子                    →  监听  →  事件（自动执行，无需手动触发）
插件                    →  打包  →  子代理 + 技能 + 钩子 + MCP + LSP

谁是"指挥官"

你（提需求）
  ↓
代理（理解需求，统一协调）
  ├─ 简单任务    → 直接用工具
  ├─ 复杂任务    → 派出子代理
  ├─ 大型并行任务 → 组建代理团队
  ├─ 专业任务    → 触发技能
  └─ 后台监控    → 钩子自动执行

实战场景

场景 1：修复简单 Bug

你: "帮我修复 src/auth.ts 里 login 函数的 bug"

Claude Code 内部：
  工具 Glob  → 找到 auth.ts 文件
  工具 Read  → 读取文件内容
  工具 Edit  → 修复 bug
  工具 Bash  → 运行测试验证
  → 告诉你修复完成

用到： 代理 + 工具

场景 2：添加新功能

你: "给用户管理模块添加批量导出功能"

Claude Code 内部：
  子代理 Explore → 搜索现有用户管理代码
  工具 Read      → 读取相关文件
  工具 Write     → 创建新的导出功能文件
  工具 Edit      → 修改现有文件加入导出入口
  工具 Bash      → 运行测试
  技能 /commit   → 提交代码

用到： 代理 + Explore 子代理 + 工具 + /commit 技能

场景 3：设计复杂系统架构

你: "我要添加支付功能，包括订单、支付、回调"

Claude Code 内部：
  进入 plan mode
  子代理 Plan    → 研究代码库，收集上下文信息
  代理           → 基于收集的信息设计支付系统架构方案
  你确认方案
  子代理 Explore → 查找现有代码中相关部分
  工具（系列）   → Write / Edit / Bash 实现各模块
  技能 /commit   → 提交完成版本

用到： 代理 + Plan 子代理 + Explore 子代理 + 工具 + 技能

场景 4：处理 PDF 报告

你: "/pdf" 或 "帮我把这几个文件合并成一个 PDF"

技能接管：
  根据技能配置，可能会进一步询问你的具体需求
  工具 Read  → 读取现有 PDF 内容
  工具 Bash  → 执行 PDF 操作命令
  工具 Write → 保存结果
  → 返回处理好的 PDF

用到： 技能 + 工具

场景 5：并行审查大型 PR（使用代理团队）

你: "这个 PR 比较大，帮我全面审查一下"

Claude Code 内部：
  代理（作为团队领导）→ 组建代理团队
  队友 1（安全审查员）→ 审查安全漏洞
  队友 2（性能审查员）→ 审查性能问题
  队友 3（测试审查员）→ 审查测试覆盖率
  三个队友并行工作，彼此通信
  领导汇总三方结果 → 给你完整审查报告

用到： 代理团队（领导 + 3 个队友）

场景 6：团队定制化工作流（使用插件）

需求: 团队统一的代码审查和部署流程

解决方案：创建团队插件

team-plugin/
├── .claude-plugin/plugin.json   # 插件清单
├── skills/deploy/SKILL.md       # 自定义 /team-plugin:deploy 技能
├── agents/qa-expert.md          # QA 子代理
├── hooks/hooks.json             # 文件修改后自动 lint
└── .mcp.json                    # 接入内部 API

加载：claude --plugin-dir ./team-plugin

用到： 插件（内含技能 + 子代理 + 钩子 + MCP）

场景 7：独立配置钩子

需求: 每次代理修改文件后自动运行代码格式化

在 .claude/settings.json 中添加：
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run format" }
        ]
      }
    ]
  }
}

用到： 钩子（独立使用，无需插件）

自定义配置速查表

你想自定义	配置方式	位置
子代理	`/agents` 命令（推荐）	交互式界面
子代理	Markdown 文件	`.claude/agents/<名称>.md`
子代理	CLI 参数（临时）	`--agents '{...}'`
代理团队	环境变量或 settings.json	`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
技能	Markdown 文件	`.claude/skills/<名称>/SKILL.md`
钩子	`/hooks` 命令（推荐）	交互式界面
钩子	JSON 配置	`.claude/settings.json`
MCP 工具	JSON 配置	`~/.claude.json`
插件	创建目录 + 清单	`--plugin-dir` 加载

你需要关注什么

概念	你需要做的	你不需要做的
代理	和它对话，给清晰的需求	不需要启动或管理
子代理	知道它存在即可，会自动调用	不需要手动触发（除非自定义）
代理团队	大型并行任务时用自然语言发起	简单任务不需要组建团队
工具	了解有哪些能力	不需要手动调用
技能	`/技能名` 触发，或自然语言描述需求	不需要了解内部实现
插件	有团队复用需求时创建	没有复用需求就不用管
钩子	有自动化需求时配置	没有自动化需求就不用管

一句话记忆法

代理     = Claude Code 本身（大脑）
工具     = 大脑的双手（Read / Edit / Bash / MCP...）
子代理   = 派出去的专家（Plan / Explore / General-purpose...）
代理团队 = 组建的项目组（多个独立 Claude 并行协作）
技能     = 预设的工作模板（/命令 或自然语言触发）
钩子     = 自动触发的守卫（事件发生时自动执行）
插件     = 打包好的扩展包（子代理 + 技能 + 钩子 + MCP + LSP）

信息来源：Claude Code 官方文档，部分内容来自实际使用观察。如有出入，以官方文档为准。

Claude Code 核心概念详解：代理、子代理、代理团队、工具、技能、插件、钩子

前言