---
title: "查看扩展能力地图"
description: "Claude Code 扩展不是越多越好。用一张决策地图分清 CLAUDE.md、Rules、Skills、MCP、Subagents、Hooks、Commands、Plugins 和 Agent SDK。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-05"
---

Claude Code 的扩展层不是一堆可选插件，而是接在 agent loop 不同位置的能力。你要先知道问题属于“记忆、流程、工具、隔离、自动化、分发、产品化”哪一类，再决定加哪一层。——Aaron

> [!NOTE]
> **这一章用 14 分钟换什么**：前一组已经讲完 settings、permissions、memory 和 MCP。现在进入扩展与自动化。读完你应该能在遇到重复提示词、上下文污染、外部系统、强制动作、多仓库复用和 SDK 产品化时，选对扩展点，而不是把所有问题都塞进 `CLAUDE.md`。

## 1. 先看总图：扩展接在 agent loop 的不同位置

Claude Code 的核心是 agentic loop：理解任务、读文件、调用工具、执行命令、改代码、汇报结果。

扩展能力不是替代这个 loop，而是在不同位置增强它：

- `CLAUDE.md`：会话开始时加载，让 Claude 每次都知道项目约定。
- `.claude/rules/`：把规则按路径、语言、目录拆开，避免根文件过长。
- Skills：按需加载知识、参考资料和可调用工作流。
- MCP：连接外部系统、数据库、API、设计稿、监控和业务工具。
- Subagents：把子任务放到隔离上下文，最后只把摘要带回主会话。
- Agent teams：多个独立 Claude Code 会话协同，适合更复杂的并行任务。
- Hooks：生命周期事件触发脚本、HTTP 请求、prompt 或 subagent。
- Commands：会话内的 `/` 命令，包括内置命令、bundled skills 和 MCP prompts。
- Plugins：把 skills、hooks、subagents、MCP servers 打包分发。
- Agent SDK：把 Claude Code 的 agent loop 嵌入自己的程序或平台。

```mermaid
flowchart TD
    User["用户任务"]
    Context["会话上下文"]
    Agent["Claude Code agent loop"]
    Tools["内置工具"]
    External["外部系统"]
    Automation["自动化事件"]
    Package["可分发能力"]
    Product["产品或后台服务"]

    ClaudeMd["CLAUDE.md / Rules"]
    Skills["Skills"]
    MCP["MCP"]
    Subagents["Subagents / Agent teams"]
    Hooks["Hooks"]
    Commands["Commands"]
    Plugins["Plugins"]
    SDK["Agent SDK"]

    User --> Context
    ClaudeMd --> Context
    Skills --> Context
    Context --> Agent
    Commands --> Agent
    Agent --> Tools
    Agent --> Subagents
    Agent --> MCP
    MCP --> External
    Agent --> Automation
    Hooks --> Automation
    Skills --> Package
    Subagents --> Package
    Hooks --> Package
    MCP --> Package
    Package --> Plugins
    Agent --> Product
    SDK --> Product

    style ClaudeMd fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Skills fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style MCP fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Hooks fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

> [!IMPORTANT]
> **第一性原理**：扩展不是按功能名选择，而是按“这件事应该什么时候加载、谁触发、是否强制、是否隔离、是否分发”选择。

## 2. 一句话决策

遇到扩展需求，先用这组判断：

- Claude 第二次忘记同一条项目约定：写进 `CLAUDE.md`。
- 规则只对某些目录、语言或文件类型生效：写进 `.claude/rules/`。
- 同一段提示词或流程第三次手打：做成 Skill。
- Claude 需要访问外部系统：接 MCP。
- 子任务会读很多文件，但主会话只需要结论：用 Subagent。
- 多个独立 Claude Code 会话需要协作：用 Agent team。
- 某个动作必须每次发生：写 Hook。
- 会话里要快速切换、管理、运行流程：用 Command。
- 多仓库或团队要复用整套能力：打包 Plugin。
- 你要把 Claude Code 做进产品或后台服务：用 Agent SDK。

> [!TIP]
> **默认顺序**：先从 `CLAUDE.md` 和 Skills 开始。不要为了“架构完整”提前上 Plugin 或 SDK。

## 3. 决策流程：先问五个问题

```mermaid
flowchart TD
    Need["我想扩展 Claude Code"]
    Always["每次会话都应该知道？"]
    Path["只对部分路径生效？"]
    Repeat["是不是可复用流程？"]
    External["需要外部系统？"]
    Isolate["需要隔离上下文？"]
    Force["必须确定性执行？"]
    Share["要跨仓库分发？"]
    Product["要嵌入产品？"]

    ClaudeMd["CLAUDE.md"]
    Rules[".claude/rules/"]
    Skill["Skill"]
    MCP["MCP"]
    Subagent["Subagent"]
    Hook["Hook"]
    Plugin["Plugin"]
    SDK["Agent SDK"]

    Need --> Always
    Always -->|是| Path
    Path -->|是| Rules
    Path -->|否| ClaudeMd
    Always -->|否| Repeat
    Repeat -->|是| Skill
    Repeat -->|否| External
    External -->|是| MCP
    External -->|否| Isolate
    Isolate -->|是| Subagent
    Isolate -->|否| Force
    Force -->|是| Hook
    Force -->|否| Share
    Share -->|是| Plugin
    Share -->|否| Product
    Product -->|是| SDK
    Product -->|否| Skill

    style ClaudeMd fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Skill fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Hook fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

这个流程不是绝对规则，但足够处理大多数新手场景。

> [!WARNING]
> **不要把所有问题都归到 prompt**：prompt 能提醒，但不能保证执行；prompt 能装知识，但会占上下文；prompt 能描述工具，但不能替代连接。

## 4. `CLAUDE.md`：每次会话都要知道的项目常识

`CLAUDE.md` 的定位是 always-on context。

适合放：

- 项目结构。
- 构建、测试、发布命令。
- 代码风格和命名约定。
- 生成文件不要手改。
- 关键目录的职责。
- 团队每次都要遵守的工作方式。

不适合放：

- 一次性任务背景。
- 长篇 API 文档。
- 可复用 checklist 的完整正文。
- 只对一个目录生效的细规则。
- 密钥、token、账号。
- 权限边界。

如果根 `CLAUDE.md` 超过 200 行，通常已经开始混入参考资料或流程细节。官方建议把参考内容移到 Skills，把路径相关规则拆到 `.claude/rules/`。

> [!IMPORTANT]
> **CLAUDE.md 不是知识库入口页**：它只装每次会话都值得进入上下文的少量规则。

## 5. `.claude/rules/`：把规则按路径拆开

Rules 解决的是“不是所有规则都应该全局加载”的问题。

适合放：

- `src/api/**` 的接口规范。
- `db/migrations/**` 的数据库迁移规范。
- `docs/**` 的文档写作规范。
- `*.test.ts` 的测试规则。
- `packages/mobile/**` 和 `packages/web/**` 的差异规则。

带 `paths` frontmatter 的 rule 只在 Claude 处理匹配文件时加载。

```md
---
paths:
  - "src/api/**/*.ts"
---

## API Rules

- Validate input before business logic.
- Use the shared error response shape.
- Update API docs when adding endpoints.
```

> [!TIP]
> **判断标准**：如果一条规则只在某些文件里有意义，放 rules，不要放根 `CLAUDE.md`。

## 6. Skills：把知识和工作流做成按需能力

Skills 是官方扩展层里最灵活的一类。一个 Skill 本质上是一个 Markdown 文件，里面包含说明、参考资料、流程和可选脚本。

适合放：

- 发布流程。
- 代码审查 checklist。
- API 风格指南。
- 排障 playbook。
- 数据库查询模式说明。
- 多步迁移流程。
- 需要 Claude 自己判断如何应用的经验。

Skills 可以由用户显式调用，也可以由 Claude 根据描述自动加载。官方还说明 Claude Code 的 skills 兼容 Agent Skills open standard，并在此基础上扩展了 invocation control、subagent execution 和 dynamic context injection。

> [!IMPORTANT]
> **Skill 是能力，不是强制边界**：它告诉 Claude 怎么做一件事，但不能保证某个动作必定发生，也不能阻止工具调用。

## 7. Skill 与 `CLAUDE.md` 的区别

这两个最容易混。

`CLAUDE.md` 适合：

- 每次会话都要知道。
- 项目核心约定。
- 简短稳定。
- 不需要用户显式调用。

Skill 适合：

- 只在某类任务需要。
- 内容较长。
- 有步骤、有参考资料、有例子。
- 可以通过 `/skill-name` 调用。

判断句：

- “Claude 每次都必须知道这条规则”放 `CLAUDE.md`。
- “Claude 做这个任务时才需要这份资料”放 Skill。
- “这是一套可复用动作流程”放 Skill。

> [!WARNING]
> **不要把 Skill 当隐形全局规则**：如果任务没有触发它，Claude 可能不会加载。必须每次都知道的内容不要只放 Skill。

## 8. MCP：连接外部系统，不是装知识

MCP 解决的是外部连接问题。

适合用 MCP：

- GitHub issue / PR。
- Jira / Linear。
- Sentry / Statsig。
- PostgreSQL / 数据仓库。
- Figma / Notion / 内部文档。
- Slack / Gmail / 内部 API。
- 浏览器、桌面、业务工具。

MCP 给 Claude “能访问什么”。Skill 可以告诉 Claude “怎么正确使用这些访问能力”。这两者经常配合。

示例：

- MCP 连接数据库。
- Skill 记录业务表结构、常见查询、危险查询边界。
- permissions 限制只能执行只读查询工具。

> [!CAUTION]
> **MCP 会扩大外部访问面**：接入前先确认 server 来源、OAuth scope、token 权限、输出大小和 permissions。

## 9. Subagents：隔离上下文里的专门 worker

Subagent 适合把一个子任务隔离出去，让它自己读文件、搜索、验证，最后只把结论返回主会话。

适合：

- 代码库探索。
- 安全审查。
- 并行方案比较。
- 大量文件阅读。
- 专门领域 worker。
- 主会话不需要保留中间过程的任务。

不适合：

- 需要你实时逐步决策的任务。
- 必须连续编辑同一批文件的主路径任务。
- 子任务结果会立刻影响下一步，且你不能等摘要。
- 只是为了“看起来更自动化”的简单任务。

官方说明：Subagent 有自己的上下文窗口，结果以摘要返回。它不会继承主会话的完整历史，也不会自动继承主会话中已调用的 skills；需要显式指定。

> [!TIP]
> **使用标准**：如果中间过程会污染主上下文，而主会话只需要结论，用 Subagent。

## 10. Agent teams：多个独立会话协作

Agent teams 比 Subagents 更重。

Subagent 是主会话管理的隔离 worker。Agent team 是多个独立 Claude Code session 之间协作，适合需要互相沟通、共享任务、并行推进的复杂工作。

适合：

- 多假设研究。
- 大型功能拆分。
- 多维代码审查。
- 需要角色之间互相质询的任务。

不适合：

- 单文件修改。
- 简单调研。
- 主线已经很清晰的实现任务。
- 你还没有稳定的本地流程。

官方说明 Agent teams 仍属于更高级的协作形态，使用前要理解它比 Subagent 更消耗 token，也更需要协调规则。

> [!WARNING]
> **不要把 Agent team 当默认并行按钮**：先用普通 Subagent 解决隔离问题；只有需要多个独立会话沟通时再升级。

## 11. Hooks：必须发生的自动化

Hooks 解决的是“这件事不能只靠 Claude 记得”的问题。

适合：

- `PreToolUse` 阻止危险命令。
- `PostToolUse` 编辑后运行 formatter 或 linter。
- `UserPromptSubmit` 注入运行环境信息。
- `SessionStart` 初始化上下文。
- `Stop` 或 `SessionEnd` 发通知、写日志、收尾。
- permission 事件上做额外审批。

Hook 可以运行：

- shell command。
- HTTP request。
- LLM prompt。
- subagent。

Skill 和 Hook 的区别很重要：

- Skill 是 Claude 读取并应用的工作流。
- Hook 是事件发生时确定性触发的自动化。

> [!IMPORTANT]
> **强制动作要用 Hook**：例如阻止 `rm -rf /`、编辑后跑格式化、会话结束发通知。这些不要只写在 prompt 或 Skill 里。

## 12. Commands：会话内的控制入口

Commands 是你在 Claude Code 会话里输入 `/` 看到的命令体系。

它包含三类：

- 内置命令：行为由 CLI 实现，比如 `/mcp`、`/memory`、`/permissions`、`/compact`。
- Bundled skills：官方打包的 skills，比如 `/debug`、`/batch`、`/simplify` 等，具体可用性取决于版本、平台和账号。
- MCP prompts：MCP server 暴露的 prompt 会显示为 slash command。

命令只在消息开头识别，命令后面的文本会作为参数传入。

常见用途：

- 管理上下文：`/compact`、`/clear`、`/context`。
- 管理配置：`/config`、`/permissions`、`/memory`。
- 管理外部连接：`/mcp`、`/plugin`。
- 运行工作流：bundled skills 或自定义 skills。

> [!TIP]
> **Commands 是入口，不是另一套能力模型**：很多命令背后其实是 settings、memory、MCP、skills 或 CLI 内置逻辑。

## 13. Plugins：把稳定能力打包分发

Plugin 是 packaging layer。官方说明 plugin 可以打包：

- Skills。
- Hooks。
- Subagents。
- MCP servers。
- Commands。
- 其他配置组件。

适合：

- 多仓库复用同一套 skills。
- 团队统一安装 hooks 和 MCP。
- 内部平台分发标准能力。
- 通过 marketplace 给外部用户安装。

不适合：

- 还在频繁改的个人实验。
- 单项目专用规则。
- 没有文档、版本、兼容边界的脚本集合。

Plugin skills 会 namespace，例如 `/my-plugin:review`，这样多个 plugin 的同名能力可以共存。

> [!WARNING]
> **不要过早 Plugin 化**：先在一个项目里把 Skill、Hook、MCP 跑稳，再打包。否则你只是把不稳定扩散到更多仓库。

## 14. Agent SDK：把 agent loop 嵌到程序里

Agent SDK 是产品化和服务化入口，不是普通项目的第一步。

适合：

- 自己的 CLI。
- 后台自动化服务。
- 内部平台。
- CI / review agent。
- Web app 里的 coding agent。
- 自定义权限、hooks、MCP、subagents 的程序化编排。

不适合：

- 你还没在 Claude Code CLI 跑通流程。
- 需求只是写一份提示词。
- 只是想少敲一个命令。
- 没有日志、错误处理、权限和发布边界。

官方 Agent SDK 支持用代码运行 agent loop，并配置 MCP、hooks、permissions、subagents、slash commands、skills 和 plugins。

> [!IMPORTANT]
> **先 CLI，后 SDK**：交互流程没跑通前，不要急着把不确定性写进代码。

## 15. 上下文成本：扩展不是免费的

每个扩展都会以不同方式影响上下文。

- `CLAUDE.md`：启动时加载全文，每次请求都带着。
- Rules：无 `paths` 的启动加载；有 `paths` 的按文件触发。
- Skills：默认启动时加载名称和描述，使用时加载全文；手动-only skill 可以降低启动成本。
- MCP：启动时加载 tool names；Tool Search 默认延迟加载完整 schema。
- Subagents：隔离上下文，不污染主会话，但仍然消耗自己的 token。
- Hooks：默认不进上下文；只有返回输出时才会进入会话。
- Plugins：取决于它打包了哪些组件。

> [!CAUTION]
> **上下文噪音会降低质量**：扩展越多，不一定越强。真正有效的 setup 是“少量稳定规则 + 按需加载的能力 + 清晰的权限边界”。

## 16. 加载和覆盖规则也不同

不同扩展的合并方式不一样。

- `CLAUDE.md` 是 additive：多个层级都会进入上下文，冲突需要 Claude 自己判断。
- Skills 按名称覆盖：不同 scope 同名时会按优先级选一个。
- Subagents 按名称覆盖：scope 和 CLI flag 会影响最终定义。
- MCP server 按名称覆盖：local 优先于 project，project 优先于 user。
- Hooks 是 merge：匹配同一事件的 hooks 都会触发。
- Plugin skills 会 namespace：降低同名冲突。

这解释了很多排障现象：

- 你改了 project MCP，但 local 同名 server 仍然生效。
- 你写了多个 hook，它们不是互相覆盖，而是都执行。
- 你以为下层 `CLAUDE.md` 覆盖了上层，其实两份都在上下文里。

> [!TIP]
> **排障先问加载模型**：是 additive、override、merge，还是 namespace？先搞清楚这个，再看具体文件。

## 17. 常见组合方式

实际项目通常不是单独用一个扩展，而是组合。

`CLAUDE.md` + Skills：

- `CLAUDE.md` 放核心规则。
- Skill 放长参考资料和流程。
- 适合 API 风格、发布流程、代码审查。

Skill + MCP：

- MCP 提供外部连接。
- Skill 教 Claude 如何正确使用这些连接。
- 适合数据库、Sentry、GitHub、Slack。

Skill + Subagent：

- Skill 定义审查流程。
- Subagent 隔离执行审查。
- 适合安全、性能、测试覆盖。

Hook + MCP：

- Hook 在事件发生时触发。
- MCP 把结果发到外部系统。
- 适合通知、审计、同步状态。

Plugin + 以上全部：

- 把稳定能力打包给多个仓库。
- 适合团队标准化。

> [!IMPORTANT]
> **组合的前提是职责清楚**：不要让 `CLAUDE.md`、Skill、Hook 同时重复表达同一个规则。重复越多，冲突越难排查。

## 18. 一个项目的推荐演进顺序

不要一次性把所有扩展上齐。推荐按触发器演进：

1. Claude 第二次犯同一个项目级错误：补 `CLAUDE.md`。
2. 根规则变长或目录差异明显：拆 `.claude/rules/`。
3. 同一流程第三次手打：做 Skill。
4. 外部系统频繁复制粘贴：接 MCP。
5. 子任务污染主上下文：用 Subagent。
6. 某动作必须确定性发生：写 Hook。
7. 同一套能力要给多个仓库：打包 Plugin。
8. 流程已经稳定并需要产品化：上 Agent SDK。

> [!TIP]
> **扩展是沉淀，不是预设**：先在真实工作中出现重复，再把重复变成能力。

## 19. 新手常见坑

- 把所有项目资料都塞进 `CLAUDE.md`。
- 把一次性提示词做成 Skill。
- 把 Skill 当权限系统。
- 用 prompt 代替 Hook 做强制动作。
- 接太多 MCP，只为“看起来功能多”。
- Subagent 任务太模糊，最后只返回一堆不可执行摘要。
- 一开始就做 Plugin，导致每次改动都要分发。
- 过早上 Agent SDK，把交互流程的不确定性固化成代码。
- 忽略上下文成本，导致 Claude 反而更难选对规则。

> [!WARNING]
> **能删掉的扩展才是健康扩展**：如果你删掉某个扩展后说不清失去什么能力，它大概率还没必要存在。

## 20. 验收标准

这一章学完，你应该能做到：

- 我能说清每个扩展点解决的问题。
- 我能判断“规则、流程、连接、隔离、自动化、分发、产品化”分别放哪层。
- 我知道强制边界不应该只写在 prompt、`CLAUDE.md` 或 Skill 里。
- 我知道 MCP 负责外部连接，Skill 负责使用方法。
- 我知道 Subagent 和 Agent team 的差别。
- 我知道 Hook 和 Skill 的差别。
- 我知道 Commands 只是会话入口，背后可能是内置逻辑、Skill 或 MCP prompt。
- 我知道 Plugin 是稳定能力的分发层，不是早期实验容器。
- 我知道 Agent SDK 应该在 CLI 流程稳定后再用。
- 我能解释每个扩展的上下文成本。

## 21. 术语速查

- `CLAUDE.md`：每次会话加载的项目说明和长期规则。
- `.claude/rules/`：可按路径或主题拆分的规则目录。
- `Skill`：可按需加载的知识、参考资料和工作流。
- `MCP`：连接外部工具、服务、数据库和 API 的协议。
- `Subagent`：在隔离上下文中执行子任务的 worker。
- `Agent team`：多个独立 Claude Code 会话组成的协作团队。
- `Hook`：生命周期事件触发的确定性自动化。
- `Command`：会话内以 `/` 开头的控制入口。
- `Bundled skill`：官方随 Claude Code 提供的 skill 命令。
- `MCP prompt`：MCP server 暴露成 slash command 的 prompt。
- `Plugin`：把 skills、hooks、subagents、MCP servers 等打包分发的组件。
- `Agent SDK`：用代码调用 Claude Code agent loop 的开发接口。
- `Tool Search`：MCP tool schema 的按需加载机制。

## 22. 官方资料

- [Extend Claude Code](https://code.claude.com/docs/en/features-overview)
- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Commands](https://code.claude.com/docs/en/commands)
- [Create plugins](https://code.claude.com/docs/en/plugins)
- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview)

<Cards>
  <Card href="/docs/claude-code/official/02-extensions-automation/skills" title="Skills" description="下一章专门讲 Skills：什么时候自动加载、什么时候手动调用、怎么组织参考资料和可复用流程。" />
  <Card href="/docs/claude-code/official/01-core-capabilities/mcp" title="连接 MCP（上一篇）" description="MCP 是扩展地图里最容易扩大外部访问面的能力。先确认 scope、OAuth、permissions 和输出限制。" />
  <Card href="/docs/claude-code/understanding/08-multi-agent" title="深度理解：多 Agent 协作" description="如果想继续理解 Subagents 和 Agent teams 背后的协作模型，可以读理解篇多 Agent。" />
</Cards>
