第五章 四大扩展系统（Skills MCP Hooks Subagents）

一、为什么 Claude Code 需要"扩展"

我们先把一件事搞清楚：大模型自己其实什么都做不了。

Claude Sonnet 4.5、Opus 4.7、GPT、DeepSeek，哪怕是最贵的模型，本质上只会做一件事——接收一段文字，吐出一段文字。它不会自动打开你的浏览器，不会自动读你的邮箱，不会自动改你的文件。它就像一个关在小黑屋里的大脑，没有眼睛、没有手、没有腿。

如果只把它关在屋里，最多就是一个聊天机器人——你问一句它答一句，问完合上电脑，什么都没改变。

但现实里你需要的不是聊天，是结果。你需要它：

• 真的去打开那份 PDF，把它转成 Markdown；
• 真的去 GitHub，把今天的 issue 都列出来；
• 真的在你写完代码之后，自动跑一遍测试；
• 真的派一个"小弟"去爬竞品的官网，自己专心干主线任务。

要做到这些，大模型必须长出"五官"和"工具"。Claude Code 就是 Anthropic 给这个大模型装五官、装工具的"骨架"，而四大扩展系统就是这副骨架上四个最关键的器官。

来一个一目了然的类比：

读完这一章，你应该能对着任何一个新需求脱口而出："这个用 Skill"、"这个走 MCP"、"这个挂个 Hook 就行"、"这个派个 Subagent"。

二、四大扩展系统总览（一张大表）

在深入每个系统之前，先把它们摆在一张桌子上对比一下。下面这张表打印出来贴显示器旁边，第一周天天看一眼。

这张表里有四个关键词需要先解释一下，否则后面会反复打架。

关键词 1：触发方式

• "模型自己判断" = Claude 在每轮对话里自己决定要不要用，你不需要专门提"用某个 Skill"。
• "模型主动调用" = Claude 看到合适的工具就会主动调，但你也可以指名道姓："用 GitHub MCP 帮我看看……"
• "事件触发" = 完全不经过模型，是 Claude Code 引擎在某个生命周期点直接执行的脚本。
• "主 Agent 派发" = Claude Code 主进程根据任务复杂度自动决定要不要分派子代理。

关键词 2：项目级 vs 个人级

• 个人级（在 ~/.claude/ 下）：所有你打开的项目都生效。适合放"通用能力"。
• 项目级（在项目根目录的 .claude/ 下）：只在这个项目里生效。适合放"团队规范、项目特化能力"。

关键词 3：YAML frontmatter

后面你会反复看到这种东西：

---
name: pdf-to-markdown
description: 把 PDF 转成 Markdown
---

--- 和 --- 之间的部分叫做 frontmatter，是给 Claude Code 看的"元信息"。三个减号必须单独成行，里面用 key: value 的格式写。这是 Skills、Subagents、Plugins 共用的写法。

关键词 4：JSON 配置

JSON 是机器可读的"对象格式"，长这样：

{
  "key1": "value1",
  "key2": ["item1", "item2"],
  "key3": {
    "nestedKey": true
  }
}

它的几条铁律：

• 键必须用双引号包起来；
• 字符串值也必须用双引号；
• 逗号不能多也不能少——最后一项后面不能有逗号；
• 大括号 / 中括号 / 引号 必须配对。

90% 的 MCP / Hooks 配置失败，都是 JSON 写错了。后面我们会反复用 JSON，你现在记住这四条就行。

好，热身完毕，开始进每个系统的细节。

三、Skills 详解：教 Claude 一项手艺

1. Skills 到底是什么

我们先用一个生活化的类比。

你刚招了一个实习生小张。第一天你教他怎么做"周报模板"——开头怎么写、字数多少、必须有"本周完成 / 下周计划 / 风险与求助"三段。教完一次，以后小张每周自己就会按这个模板做，你不用每周都重新讲一遍。

这件"教过一次以后他就永远记得"的事，在 Claude Code 里就是一个 Skill。

技术上讲，一个 Skill = 一个文件夹 + 一个 SKILL.md。文件夹的名字就是这个 Skill 的名字，比如 pdf-to-markdown、weekly-report。文件夹里至少有一个 SKILL.md（必需），可以再放一些辅助脚本（可选）。

完整路径：

~/.claude/skills/<skill-name>/SKILL.md       ← 个人级（任何项目都生效）
.claude/skills/<skill-name>/SKILL.md         ← 项目级（只在这个项目生效）

2. 一个 SKILL.md 长什么样

我们来看一个最小可运行的 Skill。把下面这段文字保存到 ~/.claude/skills/pdf-to-markdown/SKILL.md，重启 Claude Code，它就会"长出"这个能力：

---
name: pdf-to-markdown
description: 把 PDF 转换成结构清晰的 Markdown，保留标题、列表、表格。当用户给一个 .pdf 文件并希望转成可编辑文本时使用。
tools:
  - Bash
  - Read
  - Write
---

# PDF 转 Markdown 的标准流程

当用户给你一个 PDF 文件，按以下步骤处理：

## 第 1 步：提取原始文本
用 `pdftotext -layout 输入.pdf -` 提取文本（保留版式）。
如果用户没装 `pdftotext`，用 `brew install poppler` 提示一下。

## 第 2 步：识别标题层级
- 全大写、字号最大的行 → 一级标题（#）
- 居中、有数字编号的行 → 二级标题（##）
- 行末以冒号结尾、字数 < 20 → 三级标题（###）

## 第 3 步：转换列表
- 行首是 `•`、`·`、`-`、`*` → Markdown 无序列表 `-`
- 行首是 `1.`、`(1)`、`①` → Markdown 有序列表 `1.`

## 第 4 步:转换表格
通过列对齐识别表格，转成 Markdown 表格语法。

## 第 5 步:删除页眉页脚
扫描所有页面，找出在每页相同位置出现的短行 → 大概率是页眉页脚 → 删除。

## 第 6 步：输出
保存到与 PDF 同名的 .md 文件，例如 report.pdf → report.md。
完成后告诉用户输出路径，并展示前 30 行预览。

整个文件分两部分：

(1) Frontmatter（黄色高亮的部分）：三个减号包起来的元信息。

(2) 正文（Markdown 教程）：你怎么教实习生，就怎么写。可以分步骤、可以用列表、可以贴示例代码。Claude 读完会照着做。

3. Skills 的"省 token"机制

这是一个让很多人惊讶的设计：Claude 在对话开始时只读 frontmatter，不读正文。

为什么？你想想：如果你装了 50 个 Skill，每个正文 1000 字，启动对话时一次性塞 5 万字进去——光装载就把 context 撑爆了，更别说真正干活。

所以 Anthropic 的设计是：

对话开始
   │
   ▼
扫描所有 SKILL.md 的 frontmatter（每个只占几十 token）
   │
   ▼
把所有 description 缓存为"可用技能列表"
   │
   ▼
等用户提需求
   │
   ▼
模型判断"这个需求和哪个 Skill 的 description 匹配？"
   │
   ▼
匹配上 → 完整加载那个 SKILL.md 的正文
   │
   ▼
按 SKILL.md 的步骤执行

这就意味着两件事：

1. description 是 Skill 的灵魂。写得越精确、越具体，Claude 越能在合适的时机激活它。
2. 正文可以放心写长。500 字、2000 字都没关系，只有真用到的时候才会被加载。

一个常见错误：description: 一个有用的工具——Claude 永远不会激活它，因为它和任何用户问题都"有点关系，但又没那么关系"。好的 description 应该精确到能让模型判断"这次用 / 不用"。

4. 哪里能找现成 Skills

你不必自己从零写，Claude 社区已经积累了大量开源 Skill。三个最值得先逛一遍的地方：

安装方式只需三步：

$ cd ~/.claude/skills
$ git clone https://github.com/anthropics/skills.git
$ ls
skills/   # 把里面你想要的 Skill 文件夹挪到 ~/.claude/skills/ 顶层即可

或者更直接：

$ cd ~/.claude/skills
$ git clone https://github.com/某个作者/某个 Skill 仓库.git my-new-skill

重启 Claude Code，/skills 命令就能看到它已经装好了。

5. 10 个普通人最值得装的 Skill

下面这 10 个 Skill 我反复推荐给非程序员朋友。每一个都解决一类高频痛点。

Skill 1：pdf-to-markdown（PDF 转 Markdown）

能干嘛：把任何 PDF（合同、论文、产品手册、研报）转成结构清晰的 Markdown，可以直接编辑、复制、再发给别人。

为什么必装：PDF 是知识工作者绕不开的格式，但它几乎不能编辑。装了这个 Skill，你扔一份 PDF 进去，Claude 自动给你一份 .md，标题层级、列表、表格全在。

怎么装：从 anthropics/skills 仓库的 pdf 目录拷过来，或者用本章上面那个最小示例。

Skill 2：excel-analyzer（Excel 数据分析）

能干嘛：你扔一个 .xlsx 进去，它自动分析表头、数据类型、缺失值、分布，给你一份"数据健康报告"。再让它做透视、画图、找异常都行。

为什么必装：Excel 是办公室通用语言，但 90% 的人只用了 5% 的功能。这个 Skill 让 Claude 帮你做剩下的 95%。

怎么装：搜 awesome-claude-code-skills 里的 excel 关键词，多个版本可选。

Skill 3：meeting-notes（会议纪要整理）

能干嘛：把会议录音的字幕（或速记草稿）整理成 5 段式标准纪要：会议信息 / 关键决议 / 讨论摘要 / 待办事项 / 未决问题。

为什么必装：每个上班族每周至少 3 个会，每次手动整理要 30 分钟，全交给它，每周省 90 分钟。

怎么装：自己写一个，参考第四章的"会议纪要模板"，把它从 commands/ 挪到 skills/ 改个 frontmatter 就行。

Skill 4：email-classifier（邮件分类）

能干嘛：扔一堆邮件进去，按"紧急 / 重要 / 待回复 / 可归档 / 垃圾"五类分好，并给每封紧急邮件起草回信。

为什么必装：每天 100 封邮件里只有 10 封需要你看，但你要用 30 分钟手动筛选。这个 Skill 把它压到 5 分钟。

怎么装：搜 obra/skills 的 inbox 系列，或自己写。

Skill 5：image-organizer（图片按 EXIF 整理）

能干嘛：扫描某个目录下所有图片，根据每张图的 EXIF 元数据（拍摄时间、地点、设备），自动按"年/月/事件"分文件夹整理。

为什么必装：手机相册导出的 5000 张照片堆在一个文件夹里，谁都看不下去。装了它，一句话整理完。

怎么装：社区有现成的，搜 image-organizer 关键字。

Skill 6：weekly-report（周报起草）

能干嘛：你给它本周的 git commit / 飞书消息 / 待办列表，它生成一份结构化周报。

为什么必装：周报是上班族最讨厌的事之一。装了它周五下午十分钟解决。

怎么装：自己写。把"周报模板"放到 ~/.claude/skills/weekly-report/SKILL.md 即可。

Skill 7：code-explainer（代码白话解释）

能干嘛：扔一段代码进去，用大白话讲清"它是干嘛的、为什么这么写、有没有坑"。即使你不懂代码也看得懂。

为什么必装：你接手了同事留下的烂摊子项目、想看懂网上抄来的脚本、想理解 GPT 给你的代码——它就是你的"代码翻译机"。

怎么装：参考 awesome-claude-code-skills 的 code-review 系列。

Skill 8：data-cleaner（数据清洗）

能干嘛：扔一份脏 CSV 进去（缺失值、重复行、格式不一致、异常值），它自动给你一份干净的版本和一份"清洗日志"。

为什么必装：所有数据分析的 80% 时间都花在清洗上。这个 Skill 让 Claude 替你干这 80%。

怎么装：搜 data-cleaning 或 csv-cleaner。

Skill 9：web-summarizer（网页内容摘要）

能干嘛：你给它一个网页 URL（或一份 .html），它提取正文、去广告、做 5 段式摘要。

为什么必装：每天看到 20 篇"必看"长文，时间只够看 2 篇——剩下 18 篇全交给它做摘要，5 分钟掌握全部要点。

怎么装：通常需要配合 WebFetch 工具，社区有现成版本。

Skill 10：commit-message（Git commit 信息生成）

能干嘛：你 git diff 之后让它写 commit message，它会按 Conventional Commits 规范（feat/fix/docs/refactor）输出，既简洁又规范。

为什么必装：哪怕你不是程序员，只要你用 Git 管笔记 / 文档 / 配置，写 commit 都是日常。这个 Skill 让你的 git 历史"看着就专业"。

怎么装：自己写一个 30 行的 SKILL.md 即可。

6. Skill 的两个进阶技巧

技巧 1：在 Skill 里调外部脚本

Skill 文件夹里除了 SKILL.md，还可以放任何脚本。比如：

~/.claude/skills/pdf-to-markdown/
├── SKILL.md
└── scripts/
    └── extract.py

然后在 SKILL.md 里写：

执行 `python ${CLAUDE_SKILL_DIR}/scripts/extract.py 输入.pdf` 来提取文本。

${CLAUDE_SKILL_DIR} 是 Claude Code 自动注入的变量，指向当前 Skill 所在文件夹。这样你的脚本可以跟着 Skill 一起被 Git 管理、被分享。

技巧 2：限制 Skill 的工具权限

frontmatter 的 tools 字段是个白名单。比如某个 Skill 只该读不该写：

---
name: code-reviewer
description: 评审代码但绝不修改
tools:
  - Read
  - Grep
  - Glob
---

这样即使模型"手贱"想 Edit，也会被引擎拒掉，比口头叮嘱靠谱得多。

7. 写好 description 的四条铁律

description 是 Skill 唯一被"始终加载"的部分，它的好坏直接决定这个 Skill 一辈子被激活几次。我见过太多人写完 SKILL.md 兴冲冲地用，结果半年它一次都没被自动调起来——99% 的原因是 description 写得不对。

下面是我反复打磨出的"四条铁律"。

铁律 1：以"做什么 + 何时用"为主语。

铁律 2：包含"触发关键词"。

把用户最可能说的词写进 description：

description: 整理会议纪要。当用户说"整理会议""做纪要""会议总结""把这段录音整理一下"时使用。

这样用户随便用哪个说法，Claude 都能匹配上。

铁律 3：写明"不该用"的情况。

description: 把 .docx 转成 .md。注意：仅处理 Word 文档，PDF 请走 pdf-to-markdown，纯文本不需要转换。

显式排除可以防止误激活。

铁律 4：保持在 50–150 字之间。

太短信息量不够，太长 Claude 自己读起来也费劲。50–150 字是甜点区间。

8. Skill 的命名艺术

命名规则总结：

1. 全英文小写 + 中划线
2. 用"动词 + 宾语"或"宾语 + 动作"
3. 简短但具体（建议 2–4 个单词）
4. 同类 Skill 用统一前缀（pdf- / excel- / git-）方便归组

四、MCP 详解：让 Claude 出门干活

1. MCP 到底是什么

我们继续打实习生的比方。

实习生小张已经被你教会了周报模板（Skill）。但有一天你说："小张，把上周客户在 Notion 上提的所有 Bug 整理成清单。"

小张坐那儿一脸懵：他没有 Notion 的访问权限，怎么去看？

这时候你给他一张 Notion 的工作账号，配上权限，告诉他"以后客户问 Notion 的事，你都能进去看"。这张通行证 + 一组操作权限，就是 MCP。

技术上讲，MCP（Model Context Protocol）= Anthropic 在 2024 年提出的一个开放标准，定义了"AI 模型怎么和外部工具通信"。

它的官方类比是：

MCP 之于 AI = USB-C 之于电脑——一个统一的接口标准，让任何"工具"都能即插即用。

在 MCP 出现之前，每家 AI 工具要接 GitHub / Notion / 数据库都要单独写一套对接代码，互不兼容。MCP 出现之后，一套协议大家都遵守，写一次 GitHub MCP Server，所有支持 MCP 的客户端（Claude、Cursor、Windsurf、未来还会有更多）都能用。

到 2026 年初，MCP 已经事实上成了行业标准——OpenAI、Anthropic、Google 的 AI 产品都已经原生支持 MCP。学会 MCP 配置，等于一次学会了未来 5 年所有 AI 工具的扩展方式。

一个 MCP Server 是一个独立运行的小程序（通常是 Node.js 或 Python 写的），它对外提供一组工具（比如"搜 issue"、"创建 PR"）。Claude Code 在启动时会"连"上这些 Server，把它们提供的工具注册到自己的工具栏里，遇到合适的需求就调用。

2. 主流 MCP Server 名单

下面这张表列了 2026 年初最常用、最稳定的 MCP Server。打勾的是我个人推荐普通用户优先装的。

完整列表可以去 modelcontextprotocol/servers 仓库看，每周都在长。

3. 怎么装一个 MCP（GitHub MCP 完整演练）

我们以"装 GitHub MCP"为例，从头到尾走一遍。其他 MCP 的安装方式大同小异。

第 1 步：在 GitHub 创建 Personal Access Token

1. 登录 GitHub，右上角头像 → Settings
2. 左侧最下面：Developer settings
3. Personal access tokens → Tokens (classic) → Generate new token (classic)
4. 起个名字（"Claude Code MCP"），勾选权限：repo、read:org、read:user
5. 生成后立刻复制，关掉就再也看不到了。Token 长这样：ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

第 2 步：写 MCP 配置

打开（或创建）下面两个文件之一：

• 项目级：<项目根目录>/.mcp.json（团队共享，提交到 Git）
• 个人级：~/.claude/settings.json 的 mcpServers 字段（只对你生效）

我们这里以项目级为例。在项目根目录创建 .mcp.json，填入：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890"
      }
    }
  }
}

逐字解释这段配置：

安全警告：Token 千万不要直接写在提交到 Git 的 .mcp.json 里！更安全的做法：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

${env:GITHUB_TOKEN} 会从你的系统环境变量里读 GITHUB_TOKEN。然后在 ~/.zshrc（Mac）或 ~/.bashrc（Linux）加一行：

export GITHUB_TOKEN="ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890"

这样 .mcp.json 里就没有 Token，可以放心提交到 Git。

第 3 步：重启 Claude Code，验证连接

$ claude

进入对话框，输入：

/mcp

你应该看到类似下面的输出：

MCP Servers:
  github       ✓ connected   18 tools

✓ connected 就是成功了。如果是 ✗ failed，往下翻能看到具体错误（多半是 Token 错或网络挡了 npm）。

第 4 步：开始用

直接用人话说：

你: 帮我列一下 anthropics/claude-code 仓库今天创建的 issue。

Claude Code 会自动选择 github__list_issues 工具，调用之后把结果整理成表格给你。你完全不用知道工具叫什么，模型自己会判断。

第一次使用时，Claude Code 会弹出权限确认："允许调用 github__list_issues 吗？" 选"始终允许"以后就不再问。

4. 项目级 vs 个人级 MCP 怎么选

优先级：项目级 > 个人级。如果两边都配了同名 Server，项目级会覆盖个人级。

5. 6 个普通人最值得装的 MCP

MCP 1：filesystem（安全访问文件）

能干嘛：让 Claude 在你指定的目录范围内读写文件，超出范围一律拒绝。比 Claude Code 默认的 Read/Write 多了"沙箱"边界。

为什么必装：你想让 Claude 操作 ~/Documents/客户资料/，但绝不碰 ~/Desktop/秘密/——filesystem MCP 给你这个边界。

配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/cassius/Documents/客户资料",
        "/Users/cassius/Downloads"
      ]
    }
  }
}

args 里从第三项起，每一项都是允许访问的目录。Claude 操作其他目录会被拒。

MCP 2：github（管理代码仓库）

能干嘛：见上一节"完整演练"，是开发者和"用 GitHub 管文档/笔记"的人的必装项。

MCP 3：notion 或 obsidian（知识管理）

能干嘛：让 Claude 直接读写你的 Notion 页面或 Obsidian 笔记库。"帮我查上周'客户访谈'的笔记并总结"、"把这次会议纪要存到我的 Notion'会议'数据库" 这种话能直接执行。

Notion 配置示例：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "${env:NOTION_KEY}"
      }
    }
  }
}

Notion API Key 在 https://www.notion.so/my-integrations 创建。

MCP 4：playwright（浏览器自动化）

能干嘛：让 Claude 操控一个真正的浏览器——打开网页、填表单、点按钮、截图、爬数据。

典型场景：

• "每天早上 8 点打开淘宝，搜'蓝牙耳机'，把前 20 个商品的价格记到 CSV"
• "登录我的某个后台，把昨天的订单导出"
• "比对竞品官网的定价页，找出他们这周改了什么"

配置：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

第一次用会自动下载浏览器（约 200MB，耐心等）。

MCP 5：gmail 或 outlook（邮件）

能干嘛：让 Claude 收发邮件、搜旧邮件、起草回信。配合 Skill 可以做"每天 7 点把昨夜邮件分类并起草回信"这种自动化。

Gmail 配置：需要 Google 应用专用密码或 OAuth，详见 modelcontextprotocol/servers 的 gmail 子目录文档。

MCP 6：slack / 飞书（团队沟通）

能干嘛：读频道历史、搜消息、@ 发消息。"把'产品讨论'频道这周的关键讨论汇总成一份决议清单"——这种话以前要 30 分钟手动翻，现在 30 秒。

Slack 配置（飞书类似，需要企业管理员开放接口）：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${env:SLACK_TOKEN}",
        "SLACK_TEAM_ID": "T0XXXXXX"
      }
    }
  }
}

6. MCP 排错三板斧

新手装 MCP 80% 的报错都是同一类。三步搞定：

第 1 板斧：跑 /mcp 看连接状态

/mcp

绿色 ✓ 是好的，红色 ✗ 旁边会有错误码。

第 2 板斧：看日志

$ claude --debug

终端会打印每个 MCP Server 的启动日志。Token 错、网络挡 npm、依赖缺失，都能看到具体原因。

第 3 板斧：手动跑命令验证

把 .mcp.json 里的 command + args 拼起来手动跑一次：

$ npx -y @modelcontextprotocol/server-github

能直接看到错误堆栈，比从 Claude 的报错猜要快得多。

7. MCP 的安全检查清单

MCP 把 Claude 接到了你的真实世界——这是它最强大的地方，也是最危险的地方。一个写歪的 MCP 配置可能让 Claude 误删你的数据库、误发你的邮件、误下你的订单。装任何 MCP 之前，过一遍下面 6 条检查清单：

特别警惕一类 MCP："它说自己能做 100 件事"。MCP 的工具数量越多，潜在风险越大。理想情况是一个 MCP 只暴露你真正会用的 5–10 个工具，超出的部分能关就关。

8. 让 MCP 进入"只读模式"

很多 MCP 支持环境变量切换"只读模式"，这是新手最该开的开关。

GitHub MCP 的只读模式：

{
  "mcpServers": {
    "github-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}",
        "GITHUB_READ_ONLY": "1"
      }
    }
  }
}

数据库 MCP 通常用只读用户实现：在数据库里专门建一个 readonly_user，只授 SELECT 权限，把这个用户的密码喂给 MCP——根本不可能写。

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://readonly_user:xxx@localhost:5432/mydb"
      }
    }
  }
}

一句话原则：所有"写权限"都默认关闭，需要时再单独开。

五、Hooks 详解：自动反射神经

1. Hooks 到底是什么

继续实习生比方。

小张现在能做周报（Skill）、能上 Notion（MCP）。但你发现一件烦人的事：每次他改完代码，你都得提醒他"跑一下测试再提交"。提醒过 10 次，他还是会忘。

终于你受不了了，给他装了一个"反射机制"——任何时候他保存了 .py 文件，电脑自动弹出测试结果。他不用记，也不用你提醒，到点自动发生。

这个"自动发生"在 Claude Code 里就是 Hook。

技术上讲，Hook = 在 Claude Code 生命周期的某个事件上挂一段 Shell 命令。事件触发，命令就跑，完全不经过模型决策。

这是 Hook 和 Skill / MCP 最本质的区别：

2. 7 个生命周期事件

Claude Code 暴露了 7 个 Hook 事件。下面这张表是核心：

3. Hook 配置长什么样

Hooks 配置写在 .claude/settings.json（项目级）或 ~/.claude/settings.json（个人级）的 hooks 字段下。一个完整结构：

{
  "hooks": {
    "<事件名>": [
      {
        "matcher": "<匹配规则>",
        "hooks": [
          {
            "type": "command",
            "command": "<要执行的 Shell 命令>"
          }
        ]
      }
    ]
  }
}

四个字段需要解释：

Hook 触发时，Claude Code 会注入几个环境变量，命令里可以读：

下面我们看几个真实可用的例子。

4. 配置示例 1：写完代码自动跑测试

文件：.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npm test --silent || echo '[WARN] 测试失败，请检查改动'"
          }
        ]
      }
    ]
  }
}

逐字解释：

• PostToolUse：在工具调用完成后触发。
• matcher: "Edit|Write"：只匹配 Edit 和 Write 这两个工具（用 | 分隔，正则语法）。
• cd $CLAUDE_PROJECT_DIR：先切到项目根目录。
• npm test --silent：跑测试，安静模式。
• || echo '[WARN] ...'：如果测试失败（返回非 0），打印一条警告。

效果：每次 Claude 改了文件，自动跑一遍测试，失败立刻在终端看到。

5. 配置示例 2：阻止危险命令

文件：~/.claude/settings.json（个人级，全局生效）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -E 'rm -rf /|rm -rf ~|sudo |mkfs|dd if='; then echo 'BLOCKED: 危险命令被 Hook 拦截' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

逐字解释：

• PreToolUse：在工具调用之前触发，这个时间点的 exit 1 会阻止工具真的执行。
• matcher: "Bash"：只在 Claude 想跑 Bash 命令时触发。
• if echo "$CLAUDE_TOOL_INPUT" | grep -E '危险模式'：用 grep 检查命令里有没有危险关键字。
• exit 1：返回非 0，Claude Code 引擎会取消这次工具调用。

效果：哪怕 Claude "脑抽"想跑 rm -rf /，也会被你的反射神经拦截。这是真正可靠的安全护栏，不依赖模型自己"觉得"安全。

注意 JSON 里写双引号要用 \" 转义，单引号不用。

6. 配置示例 3：长任务完成桌面通知（Mac）

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 已完成任务\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

效果：每次 Claude 一轮回答结束，Mac 右上角"叮"地弹出通知。开会时你可以放心切走，做完了它会喊你。

Linux 用户把 osascript -e ... 换成 notify-send "Claude Code" "已完成"。

Windows 用户用 PowerShell 的 New-BurntToastNotification，或者用 msg、echo 系列。

7. 5 个高价值 Hook 案例

下面 5 个是我个人和团队里最常用的 Hook，每一个都解决一类高频痛点。

Hook 1：自动 Format（写完代码自动 Prettier / Black）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r .file_path); case \"$FILE\" in *.js|*.ts|*.tsx|*.jsx) prettier --write \"$FILE\" ;; *.py) black \"$FILE\" ;; *.go) gofmt -w \"$FILE\" ;; esac"
          }
        ]
      }
    ]
  }
}

作用：保存任何代码文件后自动按语言对应的格式化器跑一遍。jq 用来从 JSON 输入里取 file_path 字段。

Hook 2：自动 Lint（写完后跑 ESLint）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r .file_path); case \"$FILE\" in *.js|*.ts) eslint --fix \"$FILE\" ;; esac"
          }
        ]
      }
    ]
  }
}

作用：写完 JS/TS 文件自动 lint 并修可修的问题。

Hook 3：会话备份（每次退出打包备份）

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "tar -czf ~/claude-backups/$(date +%Y%m%d-%H%M%S)-$CLAUDE_SESSION_ID.tar.gz $CLAUDE_PROJECT_DIR/.claude"
          }
        ]
      }
    ]
  }
}

作用：每次退出 Claude Code，把项目的 .claude/ 目录打包到 ~/claude-backups/，按时间戳归档。万一改坏了配置随时恢复。

Hook 4：审计日志（所有 Bash 命令写入日志）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date '+%F %T')] $CLAUDE_SESSION_ID $CLAUDE_TOOL_INPUT\" >> ~/.claude/audit.log"
          }
        ]
      }
    ]
  }
}

作用：每次 Claude 想跑 Bash 命令，命令本身被写到 ~/.claude/audit.log。哪天发现"咦，我电脑上多了个奇怪文件"，翻日志能查到是谁、什么时候、跑了什么。

Hook 5：自动注入今日日期 / 周次

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"---\\n[环境信息] 今天是 $(date '+%Y-%m-%d %A')，第 $(date +%V) 周\\n---\""
          }
        ]
      }
    ]
  }
}

作用：每次你提问，Claude 拿到的 prompt 前面自动加一段"今天是 2026-04-19 星期日，第 16 周"。这样你说"整理本周的事"，Claude 就有"本周"是哪一周的概念，再也不会出现"我不知道今天是几号"这类错误。

8. Hook 调试小贴士

新写的 Hook 不生效？走下面三步：

1. 在命令最前面加 echo "Hook fired: $CLAUDE_TOOL_NAME" >&2 && ——能在终端看到有没有触发。
2. 用 claude --debug 启动，能看到每个 Hook 的执行日志。
3. JSON 文件用在线 JSON 校验器（jsonlint.com）查一遍语法。多一个逗号就可能让整个文件失效。

9. Hook 的输出协议

Hook 不光能"做事"，还能"对 Claude Code 说话"——通过 stdout / stderr 和 exit code 这三条通道。

举例：让 Hook 在每次提交命令前自动注入项目状态：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[当前 Git 状态]'; cd $CLAUDE_PROJECT_DIR && git status --short"
          }
        ]
      }
    ]
  }
}

效果：你每次按回车，Claude 看到的 prompt 前面会自动加一段你当前的 git status——它就有了"哪些文件改了"的实时上下文，再说"提交这次改动"它就知道在说哪些。

10. 5 个新手最容易栽的 Hook 坑

六、Subagents 详解：派"小弟"干活

1. Subagents 到底是什么

最后一个比方。

实习生小张现在能做周报、能上 Notion、有反射神经。但你接了个大项目——要同时调研 5 家竞品、整理 30 份合同、写 10 份文档。就一个小张干，干到下个月也干不完。

这时候你雇了 5 个临时工，每人专攻一项，并行干。每个临时工有自己独立的笔记本、独立的桌面、独立的注意力——他们之间不互相打扰，只在干完之后把结果汇报给你。

这 5 个临时工，在 Claude Code 里就是 Subagents。

技术上讲，Subagent = 一个独立 context window 的子代理，由主 Agent（你正在对话的那个 Claude）派发任务。

它和主 Agent 的关键区别：

为什么需要 Subagent？三个核心场景：

1. 并行：5 个独立的调研任务，串行要 5 小时，并行 5 个 Subagent 1 小时搞定。
2. 隔离 context：主对话已经塞了很多上下文，再加一段长材料会爆。派给 Subagent 处理，主 context 干净。
3. 省钱：粗活让 Subagent 用便宜模型（Haiku），主线分析用贵模型（Sonnet/Opus），同样质量，成本可能砍一半。

2. 在哪定义 Subagent

和 Skills 一样，分项目级和个人级：

.claude/agents/<name>.md          ← 项目级，团队共享
~/.claude/agents/<name>.md        ← 个人级，所有项目都用

也可以用斜杠命令交互式管理：

/agents

3. 一个 Subagent 长什么样

文件：.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 资深代码评审员。当用户要求 review、检查、审视一段代码或一个目录时调用。重点关注安全、性能、可读性。
model: claude-sonnet-4-5
tools:
  - Read
  - Grep
  - Glob
---

你是一位资深的 Code Reviewer，有 15 年代码评审经验。

# 评审标准（优先级从高到低）

## 1. 安全性（Block 级）
- SQL 注入、XSS、CSRF
- 密钥 / Token 硬编码
- 任何 eval、exec、危险反序列化
- 权限校验缺失

## 2. 正确性（Block 级）
- 边界条件遗漏（空数组、null、负数）
- 并发 / 竞态问题
- 资源未释放（文件句柄、连接、锁）

## 3. 性能（Warn 级）
- N+1 查询
- 不必要的同步等待
- 无界缓存 / 内存泄漏

## 4. 可读性（Nit 级）
- 命名是否清晰
- 函数长度（建议 < 50 行）
- 注释是否解释"为什么"而非"做了什么"

## 5. 测试覆盖（Warn 级）
- 关键路径有没有测试
- 边界条件有没有测试

# 输出格式（严格遵守）

## 一、Block 级问题（必须修，否则别合并）
- [文件:行号] 问题描述
- 修改建议

## 二、Warn 级建议（强烈建议改）
- [文件:行号] 问题描述

## 三、Nit 级优化（可选）
- [文件:行号] 问题描述

## 四、整体评价
（一段话，给出"可以合并 / 需修改后再审 / 需重写"的结论）

逐字解释这个 Subagent：

正文部分是给 Subagent 的系统提示词——它一启动，看到的就是这段。等于你把"评审标准"刻在它的 DNA 里。

4. 主 Agent 怎么派活

你完全不需要自己调用 Subagent，主 Agent 会自己判断。

例子：

你: 帮我评审一下 src/api/ 目录下的所有代码。

主 Agent 内部决策流程：

用户说要"评审" + 涉及多个文件
   │
   ▼
扫描已有 Subagents 的 description
   │
   ▼
找到 code-reviewer 匹配
   │
   ▼
派一个 code-reviewer Subagent
传入任务："评审 src/api/ 目录"
   │
   ▼
Subagent 在自己的 context 里读完所有文件、按 SKILL.md 输出结论
   │
   ▼
把结论返回给主 Agent
   │
   ▼
主 Agent 加一段总结，呈现给你

整个过程你看到的就是"我提了需求 → Claude 给了我评审报告"，Subagent 的存在是透明的。

5. 5 个高价值 Subagent

下面 5 个是我个人最常用的 Subagent，覆盖了大部分"派活"场景。

Subagent 1：researcher（网上调研）

典型任务：「调研一下 2026 年向量数据库的 Top 5 选型」

配置要点：

---
name: researcher
description: 网上调研专家。当用户要求"调研""对比""找资料""做市场分析"时调用。
model: claude-sonnet-4-5
tools:
  - WebSearch
  - WebFetch
  - Write
---

为什么独立 Subagent：调研会读 20+ 网页，全塞主 context 会爆。Subagent 在自己的 context 里读完，只返回精炼报告。

Subagent 2：code-reviewer（代码评审）

见上一节完整示例。为什么独立：评审需要严格的标准化输出，独立的系统提示词比"临时叮嘱"稳定得多。

Subagent 3：test-writer（写测试）

---
name: test-writer
description: 测试代码生成专家。当用户要求"写测试""补测试""TDD"时调用。
model: claude-haiku-4
tools:
  - Read
  - Write
  - Edit
  - Bash
---

你是测试代码生成器。

规则：
- 用项目现有测试框架（jest / pytest / go test）
- 每个公开函数至少 1 个 happy path + 2 个边界
- 测试名格式："测试 X 在 Y 条件下应该 Z"
- 不要测试私有函数
- 不要 mock 不必要的东西

为什么用便宜模型：写测试是"机械活"，Haiku 完全够用，单次成本可能是 Sonnet 的 1/10。

Subagent 4：documenter（写文档）

---
name: documenter
description: 文档撰写专家。当用户要求"写文档""更新 README""补充注释"时调用。
model: claude-haiku-4
tools:
  - Read
  - Write
  - Edit
---

写文档铁律：
- 先写"用户能干嘛"，再写"怎么做"，最后才写"为什么"
- 每段不超过 4 行
- 代码示例必须可运行
- 不写"这个函数返回 X"——这种废话从签名就能看出

为什么独立：文档风格需要全局一致，独立 Subagent 用同一份系统提示词能保证统一风格。

Subagent 5：db-explorer（数据库探索）

---
name: db-explorer
description: 数据库探索专家。当用户问"数据库里有什么""查一下表结构""统计 X"时调用。
model: claude-sonnet-4-5
tools:
  - Read
  - Bash
---

工作模式：
- 先用 SHOW TABLES / SHOW SCHEMAS 看结构
- 用 EXPLAIN 分析查询计划
- 永远只读，绝不 INSERT/UPDATE/DELETE/DROP
- 大表查询前必须 LIMIT 100 试探

为什么独立：数据库操作需要"只读"的强约束，工具白名单加上系统提示词的双重保险，比"在主对话里口头告诉它别删"安全 10 倍。

6. Subagent 的"省钱大法"

把"主 Agent 用贵模型 + Subagent 用便宜模型"组合起来，是 Claude Code 最重要的成本优化。

实际省多少取决于你的任务结构。一个粗略的经验：合理使用 Subagent，整体成本可降 30%–50%。

7. 显式派活 vs 隐式派活

Subagent 的派发有两种风格：

隐式派活（推荐 90% 场景）

你完全不提 Subagent，主 Agent 看 description 自己决定派不派：

你: 评审一下 src/api/user.ts 的安全性。

主 Agent 看到"评审" + "安全性"，匹配上 code-reviewer 的 description，自动派发。

显式派活（特殊场景）

你直接点名"用某个 Subagent"：

你: 用 code-reviewer 这个 Subagent 评审 src/api/user.ts。

或者更直接的语法（部分版本支持）：

你: @code-reviewer 评审 src/api/user.ts

什么时候用显式派活？

• 主 Agent 总是"自己干"不派活时——可能是 description 写得不够清晰，先用显式硬派一次试试
• 一个任务可能匹配多个 Subagent，你想指定某个
• 调试阶段，你要确定某个 Subagent 真的被启用了

8. 并行多个 Subagent 的真实例子

这是 Subagent 最性感的能力。一句话派 5 个小弟同时干：

你: 同时调研下面 5 家公司的最新动态，每家用一个 researcher Subagent：
  1. Anthropic
  2. OpenAI
  3. Google DeepMind
  4. Mistral AI
  5. Cohere

每家产出 200 字摘要，最后我要一份对比表。

主 Agent 会并行派 5 个 researcher，每个独立联网搜索、读官网、总结。5 个任务串行可能要 30 分钟，并行只要 5–8 分钟。最后主 Agent 把 5 份报告整合成一张对比表给你。

这就是为什么 Subagent 是"团队"——它本质上是把"AI 的并行能力"暴露给你的接口。

七、Plugins：把四大扩展打包分享

1. Plugin 是什么

到这里你应该已经发现：Skills、MCP、Hooks、Subagents 这四样，单独装一个不难，但要给团队 / 朋友 / 家人复制一整套就麻烦了——你得让对方在他自己的电脑上每个都重新装一遍。

Plugin 就是为解决这个问题诞生的——把 Skills + MCP + Hooks + Subagents + 自定义斜杠命令打成一个包，分享给别人，对方一行命令就能装好整套。

它和 npm 包、VSCode 插件是一个概念。

2. Plugin 的目录结构

一个标准 Plugin 长这样：

my-marketing-pack/
├── .claude-plugin/
│   └── plugin.json          ← 元信息（必需）
├── skills/                   ← 这个 Plugin 自带的 Skills
│   ├── weekly-report/
│   │   └── SKILL.md
│   └── email-classifier/
│       └── SKILL.md
├── commands/                 ← 自定义斜杠命令
│   ├── draft-tweet.md
│   └── content-calendar.md
├── agents/                   ← 自带的 Subagents
│   ├── copywriter.md
│   └── data-analyst.md
├── hooks.json                ← Hooks 配置（可选）
├── mcp.json                  ← MCP 配置（可选）
├── README.md                 ← 装完之后给用户看的说明
└── LICENSE

最关键的是 .claude-plugin/plugin.json，它告诉 Claude Code "这是一个 Plugin，叫什么，作者是谁"。

3. plugin.json 长什么样

最小可运行示例：

{
  "name": "my-marketing-pack",
  "version": "1.0.0",
  "description": "营销人员一键开箱：写稿 / 排版 / 数据分析",
  "author": {
    "name": "Cassius",
    "email": "cassius@example.com",
    "url": "https://example.com"
  },
  "license": "MIT",
  "homepage": "https://github.com/cassius/marketing-pack",
  "repository": {
    "type": "git",
    "url": "https://github.com/cassius/marketing-pack.git"
  },
  "keywords": ["marketing", "content", "social"]
}

逐字解释：

4. 怎么装别人的 Plugin

最朴素的方式：

$ cd ~/.claude/plugins
$ git clone https://github.com/某作者/某 Plugin.git
$ cd 某 Plugin
$ cat README.md   # 看一下说明，可能需要配 Token

更现代的方式（Claude Code 2.5+ 内置的 plugin 命令）：

$ claude plugin install github:cassius/marketing-pack
$ claude plugin list
$ claude plugin update marketing-pack
$ claude plugin remove marketing-pack

社区还有第三方包管理器（如 claude-plugin-manager），用法类似 brew install。

5. Plugin 的两个公共市场

发布自己的 Plugin 到官方市场需要走一个 PR 审核流程，社区市场则是开放的，第十二章我们会专门讲"如何发布自己的 Plugin"。

八、四大扩展什么时候用什么？决策树

学了一大堆概念，真正用起来你脑子里可能还会乱。下面这棵 ASCII 决策树打印出来贴墙上，遇到任何新需求按它走一遍。

                  我有一个新需求
                       │
                       ▼
      ┌────────────────────────────────────┐
      │ 这个需求会"反复出现"吗？           │
      └────────────────────────────────────┘
              │ Yes               │ No
              ▼                   ▼
   ┌─────────────────┐   单次任务，不需要扩展
   │ 它需要调用       │   直接对话即可
   │ "外部服务" 吗？  │
   └─────────────────┘
       │ Yes      │ No
       ▼          ▼
   ┌─────┐   ┌─────────────────────┐
   │ MCP │   │ 它是"Claude 主动决   │
   └─────┘   │ 定何时用" 还是       │
             │ "事件触发自动跑" ？  │
             └─────────────────────┘
                    │              │
              主动决定         事件触发
                    │              │
                    ▼              ▼
            ┌─────────────┐    ┌──────┐
            │ 它是一段     │    │ Hook │
            │ "知识 / 流程"│    └──────┘
            │ 还是一个     │
            │ "独立小弟"？ │
            └─────────────┘
                │       │
              知识     小弟
                │       │
                ▼       ▼
            ┌──────┐ ┌──────────┐
            │Skill │ │ Subagent │
            └──────┘ └──────────┘

                想分享给团队 / 社区？
                       │
                       ▼
                把上面打包成 Plugin

按这棵树走，几乎没有"该用哪个"的纠结。

下面再用人话翻译一遍：

一些常见混淆的对比

Q：Skill 和 Subagent 都能"教 Claude 做某件事"，区别在哪？

A：Skill 是主 Agent 自己学会的能力，激活时还在主 context 里；Subagent 是派给独立 context 的小弟，干完只返回结论。

简单判断：

• 这件事几句话能干完，不会读太多东西 → Skill
• 这件事会读很多东西、产出长输出，污染主 context 不值 → Subagent

Q：Hook 和 Skill 都能"自动做事"，区别在哪？

A：Skill 是模型判断要不要做（智能但不一定每次都做）；Hook 是引擎强制做（必然但不智能）。

• "我希望写完代码时模型考虑要不要跑测试" → Skill
• "我希望写完代码时必然跑测试" → Hook

Q：MCP 和 Skill 都能扩展能力，区别在哪？

A：MCP 提供工具（数据库连接、API 调用），Skill 提供知识（怎么用工具的方法论）。

• "Claude 怎么连上 PostgreSQL" → MCP
• "Claude 连上数据库后该怎么写 SQL 才安全高效" → Skill

最强的组合是 MCP（提供能力）+ Skill（教会方法论）+ Subagent（独立干活）+ Hook（自动触发），四者一起用。

九、避坑：扩展装多了怎么办

1. Skills 装太多怎么办

虽然 Claude 启动时只读 frontmatter，每个 Skill 占的 token 很少（约 50–100 token），但累积效应是真实的。

应对策略：

1. 常用 Skill 控制在 30 个以内。不常用的搬到"按需启用"目录。
2. 按场景分组：把"工作必装"放 ~/.claude/skills/，"项目特化"放 .claude/skills/，"临时玩玩"放别的目录用软链接。
3. 定期清理：每月跑一次 /skills，看看哪些三个月没用过，删掉或归档。
4. 写得精确的 description 比短的 description 重要——一个 50 token 但能精准激活的，比一个 20 token 但永远不被激活的有用得多。

2. MCP 装太多怎么办

MCP 的成本主要是：

• 启动时间：每个 Server 都要起一个进程（npx 启动通常 1–3 秒）。装 10 个 MCP，启动 Claude Code 要 10–30 秒。
• 工具数量：每个 MCP 暴露 5–30 个工具，全部注册到模型的工具栏，模型决策时间会变长。
• 网络依赖：有些 MCP（如 GitHub、Notion）需要网络，离线时会报连接错误。

应对策略：

1. 常用 MCP 控制在 5–10 个以内。
2. 按项目装：每个项目根据实际需要在 .mcp.json 配，不要全堆在 ~/.claude/settings.json。
3. 不用的就停：.mcp.json 里临时不用的 Server 注释掉（JSON 不支持注释，可以挪到 disabled_mcpServers 字段下手动管理）。

3. Hooks 装太多怎么办

Hook 是同步执行的——每个 Hook 不跑完，工具调用会卡住。

应对策略：

1. 每个 Hook 命令尽量在 1 秒内完成。超过 5 秒的考虑用 & 后台跑。
2. 复杂逻辑写成单独的脚本，Hook 只负责调用：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "~/scripts/claude-after-tool.sh" }
        ]
      }
    ]
  }
}

然后在 ~/scripts/claude-after-tool.sh 里写所有逻辑。脚本里有错改起来比 JSON 里改方便 10 倍。

3. 写错 Hook 比没装更糟——一个永远 exit 1 的 Hook 会让你完全用不了 Claude Code。新写的 Hook 先在终端跑一遍，确保正常退出再加进配置。

4. Subagents 装太多怎么办

Subagent 多了的问题不是性能（它们都是按需启动），而是主 Agent 的"派活困难症"——description 写得不够区分时，主 Agent 会派错小弟，或者干脆自己干。

应对策略：

1. 每个 Subagent 的 description 必须在第一句明确"我是干什么的"。
2. Subagent 之间的职责不要重叠。如果 code-reviewer 和 security-checker 的描述都包含"找问题"，主 Agent 会困惑。
3. 常用 Subagent 控制在 5–10 个。冷门的删掉，需要时再加。

5. 一张终极对照表

定期跑一遍 /skills、/mcp、/hooks、/agents 四个命令做"健康检查"，比装新的更重要。

十、协同实战：用四大扩展做"每天早报"

讲了这么多概念，最后我们用一个真实的例子把四件套都串起来——每天早上 7 点自动生成一份"个人早报"。这个场景同时涉及 Skill、MCP、Hook、Subagent，跑通它你对四大扩展的理解会立刻上一个台阶。

完整的"每天早报"实现会在第九章详细拆解，这里只画"骨架"，让你看到四件套是怎么协同的。

早报需求拆解

我们想要一份这样的早报：

# 2026-04-19 周日 早报

## 1. 昨夜全球新闻 Top 5
（精选 5 条与你领域相关的新闻）

## 2. 北京今日天气
（带穿衣建议）

## 3. 今日待办（来自 Notion）
（按优先级排序）

## 4. 重要邮件摘要（昨夜未读）
（仅 P0/P1，别的折叠）

## 5. 一句"今日鸡汤"
（来自一个本地的金句库，不带营销味）

四件套的角色分工

配置骨架（精简版）

Step 1：写 Skill daily-briefing

~/.claude/skills/daily-briefing/SKILL.md：

---
name: daily-briefing
description: 生成每日个人早报。当用户说"早报""今日早报""daily briefing"或定时任务触发"生成今天的早报"时使用。
tools:
  - Write
  - Read
---

# 每日早报标准流程

## 输入
当前日期、用户的关注领域（默认：AI / 创业 / 中文科技）

## 步骤
1. 调用 brave MCP 搜索"昨日 + 关注领域"，挑 Top 5
2. 调用 weather MCP 取北京今日天气
3. 调用 notion MCP 读"今日待办"数据库
4. 调用 email-classifier Subagent 处理昨夜邮件，只要 P0/P1
5. 从 ~/.claude/files/quotes.txt 随机选一句金句
6. 按下面的格式输出，写入 ~/Documents/早报/YYYY-MM-DD.md

## 格式
（见 README，此处省略）

## 风格
- 简洁，每条不超过 3 行
- 数字保留原文
- 不要"这个新闻很重要"这种主观点评
- 整体应该 5 分钟内能扫完

Step 2：装好需要的 MCP

~/.claude/settings.json：

{
  "mcpServers": {
    "brave": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "${env:BRAVE_KEY}" }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": { "NOTION_API_KEY": "${env:NOTION_KEY}" }
    },
    "gmail": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gmail"],
      "env": { "GMAIL_CREDENTIALS_PATH": "/Users/cassius/.gmail-creds.json" }
    }
  }
}

Step 3：写 Subagent email-classifier

~/.claude/agents/email-classifier.md：

---
name: email-classifier
description: 邮件分类专家。当用户要求"分类邮件""筛邮件""找重要邮件"时调用。
model: claude-haiku-4
tools:
  - Read
---

把传入的邮件按下面 5 类分：
- P0 紧急且重要（老板/客户的明确诉求）
- P1 重要不紧急（需要本周回的）
- P2 仅供知晓（订阅/通知）
- P3 可以归档（无关广告但合规需要存）
- 垃圾（直接删）

输出：只返回 P0、P1 两类的"发件人 + 一句摘要 + 建议回复要点"。

Step 4：挂 Hook 完成后通知

~/.claude/settings.json：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f ~/Documents/早报/$(date +%F).md ]; then osascript -e 'display notification \"今日早报已就位\" with title \"Claude Code\" sound name \"Glass\"'; fi"
          }
        ]
      }
    ]
  }
}

Step 5：每天 7 点自动跑

最简单的方式是用系统的 cron，第九章会讲更优雅的 /loop。Mac 上：

$ crontab -e
# 加一行：
0 7 * * * cd ~/projects/claude-daily && claude --print "生成今天的早报"

跑起来的样子

每天 7 点：

[Hook] cron 触发，启动 Claude Code 并发送 "生成今天的早报"
   │
   ▼
[主 Agent] 看到 "早报" → 命中 daily-briefing Skill
   │
   ▼
[Skill] 步骤 1：调 brave MCP 搜新闻
   │
   ▼
[MCP] 返回 Top 10 搜索结果
   │
   ▼
[主 Agent] 挑 5 条
   │
   ▼
[Skill] 步骤 2：调 weather MCP
   │
   ▼
[MCP] 返回今日天气数据
   │
   ▼
[Skill] 步骤 3：调 notion MCP 读待办
   │
   ▼
[MCP] 返回今日 Notion 任务列表
   │
   ▼
[Skill] 步骤 4：调 gmail MCP 拉昨夜邮件 + 派 email-classifier Subagent
   │
   ▼
[Subagent] 在独立 ctx 里处理 50 封邮件，只回 5 封 P0/P1
   │
   ▼
[Skill] 步骤 5：读金句库
   │
   ▼
[Skill] 步骤 6：按格式拼 → Write 到 ~/Documents/早报/2026-04-19.md
   │
   ▼
[Hook (Stop)] 检测到文件存在 → 桌面通知 "今日早报已就位"
   │
   ▼
你 7:05 起床打开 Mac → Notification Center 看到通知 → 打开文件 → 5 分钟扫完

整个过程你完全没有参与——四件套各司其职、自动协同。

这就是 Claude Code 的"超能力"完全体。一旦你跑通了一次这种"四件套协同"，再回去看"我用它写邮件"会觉得简直是浪费它。

十一、对普通人最友好的"开箱即用三件套"

如果你只想花 30 分钟配一次，这一套配完用半年：

1. 必装的 3 个 Skill（个人级）

$ mkdir -p ~/.claude/skills
$ cd ~/.claude/skills
$ git clone https://github.com/anthropics/skills.git anthropics-skills
$ ln -s anthropics-skills/pdf ~/.claude/skills/pdf-tools
$ ln -s anthropics-skills/docx ~/.claude/skills/docx-tools
$ ln -s anthropics-skills/xlsx ~/.claude/skills/xlsx-tools

这三个 Skill 让 Claude 能熟练处理 PDF、Word、Excel——覆盖了 90% 办公场景。

2. 必装的 2 个 MCP（个人级）

~/.claude/settings.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents",
        "/Users/你的用户名/Downloads",
        "/Users/你的用户名/Desktop"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

filesystem 让 Claude 能安全访问你的常用目录，playwright 让它能开浏览器干活——剩下的能力按需再加。

3. 必装的 1 个 Hook：长任务通知

~/.claude/settings.json（Mac 版）：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"任务完成\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

每次 Claude 一轮回答结束就"叮"一下。开会时扔个长任务给它跑，做完它喊你。

4. 暂不需要 Subagent

Subagent 是"任务复杂到需要并行 / 隔离 context"才用得到的。新手前 3 个月可以完全不碰，等遇到具体瓶颈再回来配。

本章一图回顾

                          Claude Code 主体
                                │
                                │  (能听能说，不能动手)
                                │
            ┌────────┬──────────┼──────────┬────────┐
            ↓        ↓          ↓          ↓        ↓
         Skills    MCP        Hooks    Subagents Plugins
        (经验包)  (通行证)    (反射神经)  (小弟)   (打包)
            │        │          │          │        │
            ▼        ▼          ▼          ▼        ▼
        SKILL.md  .mcp.json  hooks 字段   agents/  plugin.json
        模型自动  外部服务    生命周期     并行执行  一键分享
        判断加载   工具集     事件触发     独立 ctx  团队共享

                       ┌─────────────────┐
                       │  四个的关系      │
                       └─────────────────┘
                                │
                                ▼
            MCP   提供"能力"——Claude 怎么和外部世界打交道
            Skill 提供"方法论"——拿到能力之后怎么用
            Hook  提供"反射"——某个时刻必然发生的事
            Subagent 提供"分身"——同一时间多个我
            Plugin 提供"打包"——把上面任意组合分发给别人

                      ┌──────────────────┐
                      │ 决策树（速记版）  │
                      └──────────────────┘
                                │
                                ▼
       需要外部服务 → MCP
       需要长期记得方法 → Skill
       需要事件触发 → Hook
       需要并行 / 隔离 / 省钱 → Subagent
       需要分享 → Plugin

                      ┌──────────────────┐
                      │ 控制在多少        │
                      └──────────────────┘
                                │
                                ▼
                  Skills    < 30 个
                  MCP       < 10 个
                  Hooks     单事件 < 3 个
                  Subagents < 10 个

下章预告

四大扩展的"地基"打完了，从下一章开始我们要把这些扩展真的用起来——不再是抽象的概念，而是真实的生活场景。

第六章 生活场景实战 会带你做完下面这些事：

• 每天早报：早晨 7 点自动生成"昨天新闻 + 今日天气 + 待办清单 + 重要邮件摘要"，比闹钟更有用。
• 价格监控：盯着 5 个商品（机票、心仪商品、二手物件），一降价立刻通知你。
• 旅行规划：丢一句"下周去成都两天，我喜欢小众景点和川菜"，给你一份带交通、餐厅、住宿的完整行程。
• 健身打卡：每天三句话同步，自动维护一份长期数据 + 月度趋势图。
• 文件整理：把 Downloads 这个垃圾场每周自动收拾一次。
• 给爸妈用：3 个一键场景，让父母也能用上 AI。

会四大扩展的 Claude Code 是会动手、有团队、能联网、有反射的智能员工，但只有真正用到生活里，它才算是你的助理。下一章，我们让它来上班。