Claude Code 扩展机制：MCP、Hook、Skill、SubAgent 与 Memory

2026-06-05claude-code · mcp · hook · skill · subagent · 进阶

一、Claude Code 扩展体系全景

Claude Code 不是一个封闭的黑盒，而是一个开放的开发平台。通过 MCP（模型上下文协议）、Hook（钩子系统）、Skill（技能系统）、SubAgent（子代理）、Memory（记忆系统）和 Workflow（工作流）六大扩展机制，你可以将 Claude Code 从“对话助手”扩展为“更高效的开发工具”。

text

┌─────────────────────────────────────────────────┐

│ Claude Code │

│  ┌─────────┐  ┌──────┐  ┌──────┐  ┌──────────┐  │

│ │ MCP │ │ Hook │ │ Skill │ │ SubAgent │ │

│ │ 外部工具 │ │ 钩子 │ │ 技能 │ │ 子代理 │ │

│  └────┬────┘  └──┬───┘  └──┬───┘  └────┬─────┘  │

│ │ │ │ │ │

│  ┌────┴──────────┴─────────┴────────────┴─────┐  │

│ │ Memory + CLAUDE.md + Workflow │ │

│ │ 上下文配置底座（非独立执行引擎） │ │

│  └─────────────────────────────────────────────┘  │

└─────────────────────────────────────────────────┘

本文逐一讲解每个扩展机制，并提供可用的完整配置示例。

⚠️ 核心前提：本文介绍的所有高级功能（MCP、Hook、Skill、SubAgent 等）均依赖 Claude 原生推理引擎驱动。如果你使用了 API 协议兼容转接方案（如 CC Switch 或修改 settings.json 将模型替换为 DeepSeek 等国内模型），Claude 的核心推理引擎被替换，上述全部高级功能将一并失效。

二、MCP（模型上下文协议）— 给 Claude 装上“手脚”

什么是 MCP

MCP（Model Context Protocol）是 Anthropic 于 2026 年推出的大模型工具扩展协议，核心理念是：让大模型自己决定何时需要调用外部工具，以及调用哪个工具来完成当前任务。

与传统的 API 集成不同，MCP 下的大模型是主控者——它自己判断“这个任务需要用到浏览器”还是“这个任务需要查询数据库”，然后自主发起工具调用。你不需要在每次请求中手动指定使用什么工具。

生效前提：MCP 的整套工具调用决策由 Claude 的推理引擎完成。如果 Claude Code 本身已通过接口替换方案接入国内模型，Claude 推理引擎被绕过后，所有 MCP 服务器将无法被驱动，配置后会处于静默失效状态（无报错但不可用）。

MCP 可以连接什么

MCP 服务器	用途	典型使用场景
GitHub MCP	管理仓库、Issue、PR、Actions	自动创建 Issue、审查 PR、触发 CI/CD
PostgreSQL MCP	数据库查询与操作	直接在对话中查询和分析数据库数据
Brave Search MCP	网页搜索（Anthropic 官方推荐）	搜索最新技术文档和解决方案
Tavily MCP	技术文档搜索	搜索 API 文档、库函数的准确用法
Context7 MCP	实时编程库文档	查最新版本（非训练数据）的库文档
Chrome DevTools MCP	浏览器控制	抓取需要 JS 渲染的页面、自动化测试
Perplexity MCP	深度研究搜索	需要多轮搜索和综合分析的复杂问题

搜索方案全景对比

方案	前置条件	免费额度	搜索质量	最佳场景
内置 WebSearch	无需配置	无限制	★★★	通用搜索
Brave Search MCP	注册 Brave Search API → 获取 Key → 编辑 settings.json	2,000 次/月	★★★★	常规搜索首选
Tavily MCP	注册 Tavily → 获取 API Key → 编辑 settings.json	1,000 次/月	★★★★★	技术/API 文档搜索
Perplexity MCP	注册 Perplexity → 获取 API Key → 编辑 settings.json	按量付费	★★★★★	深度研究、多轮搜索
Context7 MCP	编辑 settings.json 即可（无需 API Key）	视版本	★★★★	查最新版本文档

建议：至少安装 Brave Search MCP（通用搜索）和 Tavily MCP（技术搜索），覆盖 90% 的日常搜索需求。

MCP 服务器安装与管理

Claude Code 的 MCP 通过 settings.json 中的 mcpServers 字段来配置。下面是一个完整的从零到可用的安装流程。

第 1 步：找到你的 settings.json

平台	路径
macOS / Linux	`~/.claude/settings.json`
Windows	`C:\Users\你的用户名\.claude\settings.json`
项目级覆盖	`.claude/settings.local.json`（放在项目根目录，优先级更高）

如果文件不存在：手动创建即可。settings.json 的 MCP 配置对 CLI 端和桌面端同时生效——两端共用同一个配置文件。

第 2 步：添加 MCP 服务器配置

将以下内容写入 settings.json（如果已有其他配置，只添加 mcpServers 部分即可）：

json

{

"mcpServers": {

"brave-search": {

"command": "npx",

"args": ["-y", "@anthropic/mcp-server-brave-search"],

"env": {

"BRAVE_API_KEY": "你的 Brave API Key"

}

获取 Brave Search API Key：

访问 api.search.brave.com 注册账号
在 Dashboard 中点击「Get Started」→ 选择 Free 套餐（2,000 次/月）
复制生成的 API Key，替换上面配置中的 你的 Brave API Key

第 3 步：验证安装

保存 settings.json 后，重启 Claude Code（完全退出再重新打开）。然后在会话中输入：

text

/mcp

如果看到 brave-search 状态为 connected ✓，说明 MCP 服务器已正确加载。

你也可以直接验证工具是否可用：

text

用 Brave Search 搜索最新的 React 19 文档

Claude 回复中引用了外部搜索结果，就说明 MCP 工作正常。

常见失败原因：

未重启 Claude Code — MCP 只在启动时加载，修改配置后必须重启
API Key 无效 — 检查是否正确复制（无多余空格/换行）
npx 超时 — 首次运行需下载 npm 包，可能需要等待 10-30 秒
网络不可达 — 部分 MCP 包的 npm registry 在国内可能较慢，可以事先用 npm install -g 包名 全局安装，然后改 command 为本地路径

多个 MCP Server 的配置示例

json

{

"mcpServers": {

"brave-search": {

"command": "npx",

"args": ["-y", "@anthropic/mcp-server-brave-search"],

"env": { "BRAVE_API_KEY": "你的 Brave API Key" }

},

"github": {

"command": "npx",

"args": ["-y", "@anthropic/mcp-server-github"],

"env": { "GITHUB_TOKEN": "你的 GitHub Personal Access Token" }

},

"context7": {

"command": "npx",

"args": ["-y", "@upstash/context7-mcp"]

}

MCP 的边界与限制

MCP 的核心理念是“扩展”而非“替换”。MCP 不会改变 Claude 的推理能力，只是给 Claude 增加了可调用的外部工具。如果你的 Claude Code 本身无法正常工作（例如因为网络限制无法连接 Anthropic API），MCP 服务器也无法挽救——因为每个工具调用都是 Claude 推理决策的结果，推理本身必须发生在 Anthropic 服务器上。

主模型替换后的影响：使用 CC Switch 或 settings.json 接口替换将 Claude 代理到第三方模型后，Claude 的推理引擎被绕过，所有 MCP 工具将静默失效——Claude Code 不会主动报错提示，但在实际任务中不会发起任何 MCP 工具调用。

Mac 版 CLI 端的额外情况：在 macOS 环境下，为保证 MCP 工具调用权限充足，建议从 Terminal.app 而非 VS Code 集成终端启动 Claude Code CLI。

三、Hook（钩子系统）— 在关键节点自动执行

什么是 Hook

Hook 允许你在 Claude Code 会话的特定生命周期节点自动执行自定义脚本。你可以把它理解为 Claude Code 的“事件监听器”——当某件事发生时，自动触发你预设的操作。

Hook 的生命周期事件

事件	触发时机	典型用途
`SessionStart`	会话开始时	加载项目配置、检查依赖、设置环境变量
`PreToolUse`	Claude 调用工具前	权限校验、操作日志记录
`PostToolUse`	Claude 调用工具后	结果处理、自动格式化
`PreMessage`	Claude 生成回复前	插入上下文信息
`Notification`	收到特定通知时	外部事件响应
`Stop`	会话结束时	清理临时文件、保存状态

实战示例：Git 提交前自动 lint

这是一个生产环境可用的 Hook 配置——在 Claude Code 执行 git commit 前自动运行 lint 检查，不通过则阻止提交。

配置文件：.claude/hooks/pre-commit.json

json

{

"hooks": [

{

"event": "PreToolUse",

"matcher": {

"tool": "Bash",

"command_pattern": "git commit.*"

},

"action": {

"type": "shell",

"command": "npm run lint && npm run test -- --passWithNoTests"

},

"on_failure": "block",

"message": "Lint 或测试未通过，提交已阻止。请修复后再提交。"

}

]

}

on_failure: “block” 的拦截范围：此设置仅拦截 bash/shell 类指令的执行。Claude Code 的原生内置工具（如文件读写、代码编辑等内置操作）不受 Hook 拦截，block 对它们无效。如果你的使用场景需要拦截内置工具调用，Hook 无法满足此需求。

实战示例：会话启动时自动加载项目信息

配置文件：.claude/hooks/session-start.json

json

{

"hooks": [

{

"event": "SessionStart",

"action": {

"type": "shell",

        "command": "echo '当前分支: $(git branch --show-current) | 最近提交: $(git log -1 --oneline) | 修改文件: $(git diff --name-only)'"

}

]

}

这样每次开启新会话时，Claude 自动获得当前的 Git 状态上下文。

Hook 配置位置

级别	路径	作用范围
项目级	`.claude/hooks/`	仅当前项目
用户级	`~/.claude/hooks/`	所有项目

Hook 编写注意事项

Hook 脚本必须可执行（Linux/macOS 下需 chmod +x）
Hook 默认超时时间为 30 秒，超时会自动取消执行。用户可在 Hook 配置中通过 timeout 字段自定义超时值（单位：秒）
Hook 的执行结果会显示在 Claude Code 的终端输出中
不要在 Hook 中执行耗时操作，否则会阻塞 Claude Code 的主流程
on_failure: “block” 会阻止原始 shell 操作，“warn” 只会提示但允许继续

四、Skill（技能系统）— 可复用的专业化指令

什么是 Skill

Skill 是可复用的、场景化的指令集。它告诉 Claude Code “在执行特定类型的任务时，应该遵循什么流程、使用什么工具、输出什么格式”。本质上，Skill 是将“最佳实践”固化为“自动响应模式”。

Skill 的类型

Claude Code 支持两类 Skill：

内置 Skill（运行环境提供）：PPT 制作 Skill、Skill Creator Skill 等

自定义 Skill（用户创建）：存放在 .claude/skills/ 目录，可在 CLAUDE.md 或会话中调用，格式为 Markdown 或 JSON。

创建你的第一个自定义 Skill

假设你经常需要 Claude 帮你按照特定模板生成 API 接口代码。

文件：.claude/skills/api-generator.md

markdown

---

name: api-generator

description: 按团队规范生成 REST API 接口代码

---

# API 接口生成器

## 适用范围

当用户要求"创建 API 接口"、"生成接口代码"

或"写一个 endpoint"时，自动激活。

## 工作流

1. **确认需求**

- HTTP 方法和路径

- 请求参数和响应格式

- 是否需要身份验证

2. **生成代码**（遵循以下规范）

- 使用 TypeScript，类型定义完整

- 输入校验使用 Zod

- 错误处理使用统一的错误码格式

- 数据库查询使用 Prisma ORM

3. **同时生成**

- 接口的主要代码文件

- 对应的单元测试（Jest）

- API 文档注释（JSDoc 格式）

## 输出格式

每生成一个接口，输出包含：

1. 接口文件路径和完整代码

2. 测试文件路径和完整代码

3. 简要的使用说明（3-5 条要点）

创建完成后，在对话中输入 /skill api-generator 即可调用。

Skill 的自动触发与手动调用

Skill 支持两种激活方式：

自动触发：Claude 根据 prompt 内容自动匹配相关的 Skill。但自动匹配机制偶有识别失误——当你的需求描述不够明确或与 Skill 的适用范围措辞不完全匹配时，Claude 可能不会自动激活 Skill，导致“明明有 Skill 但没生效”的困惑
手动调用：使用 /skill <name> 命令显式调用。对于复杂或关键任务，建议优先使用手动调用以确保 Skill 确实被加载

Skill 编写最佳实践

原则	说明
单一职责	每个 Skill 只做一类事。不要写“万能 Skill”
触发描述清晰	在“适用范围”中用具体的触发语句，帮助 Claude 准确匹配
步骤化	用编号列表描述工作流，而不是大段文字
包含示例	在 Skill 中附上典型的输入和期望输出
版本管理	Skill 文件纳入 Git 管理，团队共享

五、SubAgent（子代理）— 并行处理多任务

什么是 SubAgent

SubAgent 是 Claude Code 的并行任务执行机制。当遇到可以并行处理的任务时，Claude 会自动派发多个子代理同时工作，每个子代理独立执行一个子任务，完成后汇总结果。

何时触发 SubAgent

你不需要手动创建 SubAgent——在 prompt 中使用以下模式即可自动触发：

text

帮我同时调研 A 和 B

比对这三个方案的区别

并行检查以下 5 个文件的安全性

关键词：“同时”、“并行”、“一次性”、“一起”

自动触发的局限：与 Skill 类似，SubAgent 的自动触发机制偶有识别失误——尤其是在任务规模较小、并行收益不明显时，Claude 可能选择顺序执行而非并行。如果你明确需要并行处理，建议在 prompt 中显式使用“同时”、“并行”等措辞来提升触发概率。

SubAgent 的适用场景

场景	示例 Prompt
并行调研	“帮我同时调研 React 19 和 Vue 4 的新特性”
批量文件处理	“将这 10 个 JSON 文件一起转为 TypeScript 类型定义”
多维度审查	“并行审查这段代码的安全性、性能和可维护性”
多语言输出	“一次性生成英文、日文、韩文的 i18n 翻译文件”

SubAgent 的限制

SubAgent 有独立的上下文窗口，不会污染主会话上下文
每个 SubAgent 完成任务后将结果返回给主 Claude，主 Claude 负责汇总
SubAgent 之间不能互相通信
三重并发限制：SubAgent 的并发数量同时受制于三个因素——① 你的 Claude 订阅计划等级、② 本地硬件资源（CPU/内存/磁盘 I/O）、③ 当前会话的 token 预算。当其中任一资源紧张时，系统会自动降低并发数，这是正常现象而非故障。批量任务的实际并发数可能远低于你传入的任务数量

六、Memory 记忆系统与 CLAUDE.md

Memory 系统

Claude Code 拥有一个持久化的记忆系统，存储在 .claude/memory/ 目录下。它可以：

自动记录你的偏好（使用的技术栈、命名风格等）
记住你纠正过的问题（“上次你说这个 API 应该用 v2 版本”）
跨会话保持项目相关的上下文

记忆以 Markdown 文件形式存储，每个文件记录一个事实，带有 frontmatter 元数据。你可以手动添加/编辑记忆文件，Claude 也会自动写入重要信息。

CLAUDE.md — 项目的“说明书”

CLAUDE.md 是 Claude Code 的项目配置文件，放在项目根目录下。它在每个会话启动时被自动读取，定义了项目的技术栈、编码规范、常用命令和项目特定的约束。

架构位置的正确理解

Memory 和 CLAUDE.md 是上下文配置底座，而非独立的执行引擎。它们的作用是：为 Claude 的推理提供持久化的背景信息、在会话启动时自动注入上下文从而减少重复说明。它们本身不执行任何代码或自动化操作——这与 MCP（外部工具调用）和 Hook（事件驱动的自动脚本）有关键差异，后两者是执行机制，前者是信息供给机制。

上下文管理命令

命令	作用
`/compact`	压缩当前会话历史（保留关键信息，释放上下文空间）
`/clear`	清空当前会话历史
`/reset`	重置会话，包括所有中间状态
`/context`	查看当前上下文使用情况（已占用 token 数）

七、后台任务与 Workflow

后台任务

Claude Code 支持将耗时任务（构建、测试、部署）放到后台执行，不阻塞对话。在命令末尾加上 & 即可在后台运行。

bash

/tasks # 查看所有后台任务的状态

/task <id> # 查看特定任务的详细进度

Workflow（工作流）

预定义的自动化工作流，用于编排复杂的多步骤任务。工作流本质上是确定性的脚本（JavaScript），精确控制多个 SubAgent 的执行顺序和协作方式。

bash

claude workflow list # 列出所有可用工作流

claude workflow run <name> # 运行指定工作流

Workflow 适合的场景：发布流程（lint → test → build → deploy → notify）、代码审查（静默扫描 → 分类 → 并行验证 → 汇总报告）、数据迁移（发现 → 生成迁移脚本 → 逐个执行 → 验证 → 回滚准备）。

八、图片处理

Claude Code 支持以下图片输入方式：直接拖入终端窗口、使用文件路径引用、通过 MCP 连接图像处理工具。图片可用于 UI 审查、截图分析、图表识别、设计评审等场景。

九、自定义别名

bash
# 在 settings.json 中配置自定义别名（如支持），或使用 shell alias
# alias deploy="npm run lint && npm run build && git push origin main"

十、综合实战：搭建一个完整的开发工作站

目录结构

text

项目根目录/

├── CLAUDE.md # 项目说明书（上下文配置底座）

├── .claude/

│ ├── skills/

│ │ ├── api-generator.md # API 接口生成 Skill

│ │ └── code-review.md # 代码审查 Skill

│ ├── hooks/

│ │ ├── pre-commit.json # 提交前 lint 检查

│ │ └── session-start.json # 会话启动加载状态

│ └── memory/ # 自动记忆目录

│

└── ~/.claude/

└── settings.json # MCP 服务器配置（用户级，CLI/桌面共用）

注意：MCP 配置统一放在 ~/.claude/settings.json（Windows: C:\Users\你的用户名\.claude\settings.json）中，CLI 端和桌面端共用同一个配置文件。如果需要为某个项目单独配置 MCP，可以使用项目根目录的 .claude/settings.local.json（优先级更高）。

功能组合表

场景	涉及功能	效果
每天开始工作	CLAUDE.md + SessionStart Hook + Memory	自动加载项目上下文、Git 状态、历史偏好
创建新接口	api-generator Skill + Zod Schema	一次对话生成接口代码 + 测试 + 文档
提交代码前	PreToolUse Hook（git commit 匹配）	自动运行 lint + test，不通过则阻止提交
调研新技术	Brave Search MCP + Tavily MCP + SubAgent	并行搜索多个来源，交叉验证，生成调研报告
代码审查	code-review Skill + SubAgent	并行审查安全性、性能、可维护性
部署发布	Workflow	lint → test → build → deploy → 通知
上下文过长	/compact	压缩历史，保留关键信息

渐进式搭建建议

第 1 周：写好 CLAUDE.md（描述项目和技术栈）→ 你会立刻感受到 Claude 的理解力提升
第 2 周：安装 1-2 个 MCP 服务器（Brave Search + 项目相关的数据库/API MCP）→ 注意：如果用的是 CLI 端和桌面端两处，两处都要配置 MCP
第 3 周：添加 1-2 个 Hook（SessionStart + PreToolUse for git commit）→ 自动化重复检查
第 4 周：创建 1-2 个 Skill（高频重复任务的模板）→ 一致性提升。复杂任务建议手动 /skill 调用
之后：根据需要逐步添加更多 MCP、Hook、Skill、Workflow

十一、总结

机制	一句话	类比
MCP	让 Claude 调用外部工具	给大脑装上手脚
Hook	在关键节点自动执行 shell 指令	CI/CD 的触发器
Skill	可复用的专业模板	VS Code 的 Snippet
SubAgent	并行处理多任务（受三重限制）	多线程执行
Memory + CLAUDE.md	上下文配置底座（非执行引擎）	项目的 onboarding doc
Workflow	编排多步骤自动化	GitHub Actions

这些功能的主要用途不是单个功能有多强，而在于组合使用——一个配置合理的 Claude Code 工作站的开发效率可以高于默认配置。

但需要注意的前提是：所有高级功能的运转都依赖 Claude 原生推理引擎。一旦通过接口替换方案将模型替换为国内模型，上述机制将全部失效。

备注 1：本文基于 2026 年 6 月 Claude Code 0.9.x 版本功能编写。MCP 服务器列表、Hook 事件类型、Skill 系统等均可能随 Claude Code 版本迭代而变更，实际操作请以官方最新文档为准。

备注 2：文中所涉方案和配置仅限个人学习研究用途。如需商用，请遵守中华人民共和国相关法律法规以及各平台 API 服务协议中的商用条款。

Claude Code 扩展机制：MCP、Hook、Skill、SubAgent 与 Memory

一、Claude Code 扩展体系全景

二、MCP（模型上下文协议）— 给 Claude 装上“手脚”

什么是 MCP

MCP 可以连接什么

搜索方案全景对比

MCP 服务器安装与管理

第 1 步：找到你的 settings.json

第 2 步：添加 MCP 服务器配置

第 3 步：验证安装

多个 MCP Server 的配置示例

MCP 的边界与限制

三、Hook（钩子系统）— 在关键节点自动执行

什么是 Hook

Hook 的生命周期事件

实战示例：Git 提交前自动 lint

实战示例：会话启动时自动加载项目信息

Hook 配置位置

Hook 编写注意事项

四、Skill（技能系统）— 可复用的专业化指令

什么是 Skill

Skill 的类型

创建你的第一个自定义 Skill

Skill 的自动触发与手动调用

Skill 编写最佳实践

五、SubAgent（子代理）— 并行处理多任务

什么是 SubAgent

何时触发 SubAgent

SubAgent 的适用场景

SubAgent 的限制

六、Memory 记忆系统与 CLAUDE.md

Memory 系统

CLAUDE.md — 项目的“说明书”

架构位置的正确理解

上下文管理命令

七、后台任务与 Workflow

后台任务

Workflow（工作流）

八、图片处理

九、自定义别名

十、综合实战：搭建一个完整的开发工作站

目录结构

功能组合表

渐进式搭建建议

十一、总结

有疑问？来这里找答案