查看扩展能力地图

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

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 嵌入自己的程序或平台。

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

2. 一句话决策

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

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

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

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

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

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

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

适合放：

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

不适合放：

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

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

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

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

适合放：

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

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

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

## API Rules

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

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。

7. Skill 与 CLAUDE.md 的区别

这两个最容易混。

CLAUDE.md 适合：

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

Skill 适合：

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

判断句：

• “Claude 每次都必须知道这条规则”放 CLAUDE.md。
• “Claude 做这个任务时才需要这份资料”放 Skill。
• “这是一套可复用动作流程”放 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 限制只能执行只读查询工具。

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

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

适合：

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

不适合：

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

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

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

Agent teams 比 Subagents 更重。

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

适合：

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

不适合：

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

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

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 是事件发生时确定性触发的自动化。

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。

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

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

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

适合：

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

不适合：

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

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

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。

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

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

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

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 覆盖了上层，其实两份都在上下文里。

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 + 以上全部：

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

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

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

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

19. 新手常见坑

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

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
• How Claude remembers your project
• Extend Claude with skills
• Create custom subagents
• Automate workflows with hooks
• Commands
• Create plugins
• Agent SDK overview