Claude Code 可扩展性：Plugins、Subagents 与 Skills 完全指南

公众号名称：奇点先锋

作者名称：sky

发布时间：2026-04-17 09:00

一、为什么需要了解这套扩展体系？

刚开始用 Claude Code 的时候，很多人会把它当成一个”更聪明的自动补全”——改几行代码、写几个函数，足够了。但当你真正把它嵌入日常开发流程，就会发现一个问题：每次都要重复告诉它同样的规则。

“我们的提交信息格式是 feat(scope): subject”。“代码审查时重点看安全和错误处理”。“测试用 pytest，不是 unittest”。

这些东西说一次两次还好，说十次你就开始怀疑人生了。

Claude Code 的设计者显然也想到了这一点。它提供了一套三层扩展体系——插件（Plugins）、子代理（Subagents）、技能（Skills）——让你把重复的指令变成可复用的资产。

这三个机制不是互相替代的关系，而是互补的。理解它们各自的角色，是构建高效开发工作流的第一步。

---

二、整体架构：三个机制如何协作

先看一张全景图。Claude Code 的核心是系统提示词和内置工具，三个扩展机制分别从不同方向接入：

┌─────────────────────────────┐
                 │     CLAUDE CODE 核心         │
                 │     系统提示词 + 工具          │
                 └──────────────┬──────────────┘
                                │
              ┌─────────┬───────┴───────┬─────────┐
              ▼         ▼               ▼         │
        ┌──────────┐ ┌──────────┐ ┌──────────┐    │
        │  插件    │ │  子代理  │ │  技能      │    │
        │  打包    │ │  委托    │ │  展开      │    │
        └──────────┘ └──────────┘ └──────────┘
         · 命令       · 独立上下文  · 提示词注入
         · 代理       · 专用工具    · 脚本引用
         · 技能       · 专业 expertise · 工具作用域
         · 钩子       · 可恢复会话
         · MCP 服务器

它们之间的关系可以这样理解：

• 插件 是容器，它可以打包子代理、技能、钩子、命令和 MCP 服务器

• 子代理 可以通过 skills: 字段加载技能

• 技能 负责向提示词注入具体指令

• 三者可以独立使用，也可以组合在一起

打个比方：技能像是乐高积木，子代理是用积木搭好的小模型，插件则是把几个小模型装进一个盒子里分享给别人。

---

三、目录结构：文件放在哪里

所有扩展都存放在项目根目录下的 .claude/ 目录中，也可以放在用户级别的 ～/.claude/ 中（对所有项目生效）。

项目根目录/
├── .claude/
│   ├── agents/                    ← 项目子代理
│   │   ├── code-reviewer.md       ← 代码审查代理
│   │   ├── test-runner.md         ← 测试运行代理
│   │   └── debugger.md            ← 调试代理
│   │
│   ├── skills/                    ← 项目技能
│   │   ├── pdf/
│   │   │   ├── SKILL.md           ← 必需：技能定义文件
│   │   │   ├── scripts/           ← 技能附带脚本
│   │   │   └── references/        ← 参考资料
│   │   └── commit-messages/
│   │       └── SKILL.md
│   │
│   ├── commands/                  ← 斜杠命令
│   │   ├── deploy.md
│   │   └── lint.md
│   │
│   └── settings.json              ← 配置
│
├── .claude-plugin/                ← 插件标记目录（如果这是一个插件）
│   └── plugin.json                ← 插件清单文件
│
└── .mcp.json                      ← MCP 服务器配置

用户级别的配置在 ～/.claude/ 下，结构类似，只不过对所有项目都生效。

---

四、子代理：专业的 AI 助手

4.1 解决什么问题

在日常开发中，有几个很常见的痛点：

痛点	子代理怎么解决
上下文污染——一次对话塞了太多无关信息	每个子代理在独立的上下文窗口中运行
重复指令——每次都告诉 AI 同样的规则	定义一次专业知识，随处复用
工具泛滥——不需要给 AI 所有工具权限	每个子代理只拥有相关的工具
团队一致性——每个人用法不一样	通过版本控制系统共享

4.2 文件格式

子代理是一个带有 YAML 前置元数据的 Markdown 文件。来看一个实际的代码审查子代理：

---
name: code-reviewer # 必需：小写加连字符
description: > # 必需：何时调用此代理
  Expert code reviewer. Use PROACTIVELY after any code changes 
  to check quality and security.
tools: Read, Grep, Glob, Bash # 可选：限制可用工具
model: inherit # 可选：sonnet|opus|haiku|inherit
permissionMode: default # 可选：权限处理方式
skills: project-conventions # 可选：自动加载的技能
---

下面的正文部分是子代理的系统提示词：

你是一名确保高标准的资深代码审查员。

## 被调用时

1. 运行 git diff 查看最近变更
2. 只关注被修改的文件
3. 立即开始审查

## 审查清单

- [ ] 代码简洁易读
- [ ] 没有重复逻辑
- [ ] 错误处理到位
- [ ] 没有泄露密钥或 API 密钥
- [ ] 输入验证已实现

## 输出格式

按优先级组织反馈：

- 严重（合并前必须修复）
- 警告（应该处理）
- 建议（锦上添花）

4.3 调用流程

步骤 1：用户请求或自动匹配
  用户："审查我的代码变更" → Claude 根据描述匹配代理
      ↓
步骤 2：发现
  扫描 .claude/agents/ 寻找匹配的代理配置
      ↓
步骤 3：生成子代理
  · 创建新的独立上下文窗口
  · 从 Markdown 正文加载系统提示词
  · 限制工具为：Read、Grep、Glob、Bash
  · 自动加载技能：project-conventions
  · 分配 agentId 用于恢复会话
      ↓
步骤 4：执行
  子代理运行 git diff，读取文件，应用检查清单，整理发现
      ↓
步骤 5：返回结果
  审查结果注入主对话；agentId 保存用于后续恢复

4.4 实战示例

测试运行子代理：

---
name: test-runner
description: Run tests and fix failures. Use PROACTIVELY after code changes.
tools: Read, Edit, Bash, Glob
---

你是测试自动化专家。

## 流程

1. 检测测试框架：package.json → Jest/Vitest，pytest.ini → pytest
2. 运行相应命令：npm test 或 pytest -v
3. 如果有失败：
   - 分析堆栈跟踪
   - 定位根本原因
   - 修复同时保持测试意图不变
4. 重新运行确认修复

## 核心原则

永远不要修改测试来让它们通过。修复的是被测试的代码。

文档生成子代理：

---
name: doc-generator
description: Generate API docs and README files. Use when creating documentation.
tools: Read, Write, Grep, Glob
model: opus
---

你是专注于开发者文档的技术写作者。

## 生成 API 文档时

1. 扫描导出的函数/类
2. 提取 JSDoc/docstrings
3. 生成 OpenAPI 规范或 Markdown 表格
4. 每个端点包含代码示例

## README 结构

- 快速开始（5 分钟内完成）
- 安装选项
- 配置参考
- 常见用例及示例

4.5 最佳实践

应该做的：

• 描述要具体且带触发条件，比如”代码变更后主动使用”

• 每个子代理专注单一职责

• 通过版本控制共享项目级子代理

• 用 skills: 字段自动加载相关技能

需要避免的：

• 给模糊的描述，比如”帮助处理代码”

• 授予不必要的工具权限——遵循最小权限原则

• 期望子代理能再 spawn 子代理（不允许）

• 忘记子代理启动时是干净上下文（会有延迟）

---

五、技能：按需展开的提示词

5.1 与子代理的区别

技能跟子代理有一个根本的不同：技能不创建新的对话窗口，而是在当前对话中展开指令。

可以把它理解成”懒加载”——Claude Code 启动时只加载技能的元数据（大约一百个 token），当用户触发相关任务时，才把完整的指令注入上下文。

5.2 三层渐进披露架构

这是技能设计中最精妙的部分。

第一层：元数据（启动时加载，约 100 token/技能）

启动时，所有技能的名称和简介被载入系统提示词。Claude 只是知道”有这些东西可用”，不会消耗太多 token。

  
    pdf
    提取和分析 PDF 内容
  
  
    commit-messages
    生成 git 提交信息
  

第二层：指令（按需加载）

当用户说”读一下这个 PDF”时，Claude 匹配到 pdf 技能，然后读取完整的 SKILL.md 注入上下文。

基础路径：/Users/dev/.claude/skills/pdf/

# PDF 处理技能

使用 extract_text.py 脚本：
    python3 {baseDir}/scripts/extract_text.py <输入文件>

提取后，总结关键要点……

第三层：资源（需要时读取）

如果指令中引用了参考文件或脚本，Claude 会按需读取。注意：脚本的输出进入上下文，而不是脚本源码本身，这样非常节省 token。

> 执行：python3 /path/to/scripts/extract_text.py report.pdf
> 读取：/path/to/references/forms.md

5.3 文件格式

---
name: code-review # 必需：最多 64 字符
description: > # 必需：最多 1024 字符
  Reviews code for quality, security, and best practices. 
  Use when reviewing PRs or analyzing code changes.
allowed-tools: "Bash(git:*),Read,Grep" # 可选：工具权限
model: "claude-opus-4-20250514" # 可选：模型覆盖
version: "1.0.0" # 可选：版本追踪
disable-model-invocation: false # 可选：true 时仅手动触发
user-invocable: true # 可选：显示在菜单中
---

# 代码审查技能

## 前置条件

- 有暂存或已提交的变更的 Git 仓库
- 能访问源文件

## 流程

### 第一步：收集变更

运行分析脚本收集差异信息：

```bash
python {baseDir}/scripts/analyzer.py --path . --output /tmp/review.json
```

### 第二步：审查清单

对每个变更的文件，验证：

- [ ] 函数不超过 50 行
- [ ] 变量名清晰
- [ ] 有错误处理
- [ ] 没有硬编码的密钥

## 参考资料

更多高级模式，参见 {baseDir}/references/patterns.md

5.4 调用流程

步骤 1：用户请求
用户："审查我的 PR" → Claude 扫描系统提示词中的可用技能
↓
步骤 2：工具调用
调用 Skill 工具，传入命令参数
↓
步骤 3：技能激活
· 向用户展示："code-review 技能正在加载"
· 从 .claude/skills/code-review/ 读取完整 SKILL.md
· 注入上下文，解析 {baseDir}
· 应用工具限制
· 如果指定了模型则切换
↓
步骤 4：在当前上下文执行
Claude 按照注入的指令执行——运行脚本、读取参考
脚本输出进入上下文，源码不进入（高效！）
↓
步骤 5：返回结果
结果在同一个对话中（不创建新的上下文窗口）

5.5 实战示例

提交信息生成技能：

---
name: commit-messages
description: Generates conventional commit messages. Use when committing code.
allowed-tools: "Bash(git diff:*),Bash(git status:*)"
---

# 提交信息生成器

## 格式

(): 

API 脚手架技能：

---
name: api-scaffold
description: Scaffold REST API endpoints with validation and tests.
allowed-tools: "Read,Write,Bash(npm:*)"
---

# API 端点脚手架

## 流程

1. 获取端点详情：方法、路径、请求/响应模式
2. 生成文件：
   - routes/.ts - 路由处理
   - validators/.ts - 验证模式
   - tests/.test.ts - 集成测试

## 模板

```typescript
import { Router } from 'express';
import { validate } from '../middleware/validate';
import { ResourceSchema } from '../validators/{resource}';

const router = Router();

router.post('/', validate({Resource}Schema), async (req, res) => {
  // 实现
});

export default router;
```

5.6 最佳实践

应该做的：

• 描述要具体，包含用户可能会说的关键词

• 使用 {baseDir} 让脚本路径可移植

• 利用渐进披露：把 SKILL.md 控制在 5000 token 以内

• 把复杂逻辑放在 scripts/ 目录（输出进入上下文，源码不进入）

需要避免的：

• 把 SKILL.md 直接放在 skills/ 下（必须放在子目录中）

• YAML 前置数据用制表符（只用空格）

• 硬编码绝对路径

• 忘记给脚本加可执行权限

---

六、插件：可打包分发的扩展集合

6.1 定位

如果说技能是积木、子代理是小模型，那插件就是把几个小模型装进礼盒，贴上标签送给别人。插件的核心价值在于分享和分发。

6.2 目录布局

my-plugin/
├── .claude-plugin/ ← 必需：插件标记目录
│ └── plugin.json ← 必需：清单文件
│
├── commands/ ← 默认：斜杠命令
│ ├── review.md → /my-plugin:review
│ └── deploy.md → /my-plugin:deploy
│
├── agents/ ← 默认：子代理
│ ├── security-reviewer.md
│ └── performance-tester.md
│
├── skills/ ← 默认：技能
│ └── code-patterns/
│ ├── SKILL.md
│ └── references/
│
├── hooks/ ← 钩子配置
│ └── hooks.json
│
├── scripts/ ← 工具脚本
├── .mcp.json ← MCP 服务器定义
└── README.md

注意：commands/、agents/、skills/、hooks/ 这些目录在插件根目录，不是在 .claude-plugin/ 里面。这是最常见的错误。

6.3 清单文件

{
"name": "code-quality-suite",
"version": "1.2.0",
"description": "Code review, testing, and documentation tools",
"author": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
"license": "MIT",
"commands": "./extra-commands/",
"agents": ["./agents/", "./advanced-agents/"],
"mcpServers": {
    "plugin-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--port", "5432"]
    }
  }
}

6.4 安装与加载流程

步骤 1：安装命令
  claude plugin install formatter@marketplace
      ↓
步骤 2：发现阶段
  · 定位 .claude-plugin/plugin.json
  · 验证清单模式
  · 检查名称冲突
      ↓
步骤 3：安装阶段
  · 复制插件目录到缓存
  · 解析 ${CLAUDE_PLUGIN_ROOT}
  · 注册作用域：user | project | local
      ↓
步骤 4：组件注册
  · 命令：commands/review.md → /code-quality-suite:review
  · 代理：agents/security-reviewer.md → 可用于委托
  · 技能：skills/code-patterns/SKILL.md → 加入可用技能列表
  · 钩子：hooks/hooks.json → 事件处理器注册
  · MCP：.mcp.json → 服务器自动启动
      ↓
步骤 5：就绪可用
  插件组件在 Claude Code 中可用

6.5 最佳实践

应该做的：

• plugin.json 只放在 .claude-plugin/ 里面

• 所有内部路径使用 ${CLAUDE_PLUGIN_ROOT}

• 用 claude --debug 测试加载错误

• 保持插件自包含（不要用 ../ 路径）

需要避免的：

• 把 commands/、agents/、skills/ 放在 .claude-plugin/ 里面

• 使用保留的市场名称

• 引用插件目录外的文件

• 忘记给命令加插件名称前缀（/plugin-name:command）

---

七、对比：什么时候用什么

7.1 决策流程

需要打包多个扩展以便分享？
  YES → 插件

需要隔离上下文 + 任务委托？
  YES → 子代理

需要在当前上下文中注入指令？
  YES → 技能

只是简单的提示词扩展？
  → 斜杠命令或 CLAUDE.md

7.2 功能对比

特性	子代理	技能	插件
核心目的	委托给专业代理	展开提示词	打包和分享
上下文	独立窗口	同一对话	其他类型的容器
位置	.claude/agents/*.md	.claude/skills/*/SKILL.md	*/.claude-plugin/
调用方式	自动或显式	通过 Skill 工具自动	包含其他类型
工具访问	每个代理可配置	通过 allowed-tools 限定	由内容继承
模型覆盖	支持	支持	通过包含的代理
可恢复	是（agentId）	否	不适用
分享方式	复制 .md 文件	复制技能目录	从市场安装

7.3 场景映射

场景	推荐方案	原因
代码审查自动化	子代理	需要隔离上下文和专用工具
测试生成	子代理	复杂多步骤流程，需要工具访问
文档生成	技能或子代理	技能用于模板，子代理用于完整文档
代码检查/格式化	插件（带钩子）	编辑后自动触发
API 脚手架	技能	在当前上下文中注入模板
项目规范	技能	用团队标准扩展提示词
团队工具包	插件	一起分发多个扩展

---

八、常见错误与修复

错误	原因	修复
子代理不出现	文件不在 agents/ 目录	移到 .claude/agents/
技能不加载	SKILL.md 位置不对	必须是 .claude/skills/<名称>/SKILL.md
插件命令丢失	目录结构错误	确保 commands/ 在插件根目录
钩子不触发	脚本没有可执行权限	chmod +x script.sh
安装后路径报错	使用了绝对路径	改用 ${CLAUDE_PLUGIN_ROOT} 或 {baseDir}
YAML 解析错误	用了制表符或缺少 ---	用空格，确保前置数据从第一行开始

---

九、总结

Claude Code 的扩展体系遵循一个组合模式：

• 技能 提供原子级的能力——一段可复用的指令

• 子代理 把技能和隔离上下文组合起来，处理复杂任务

• 插件 把一切打包成可分发的包，分享给团队或社区

关键的理解是，每个机制运作在不同的抽象层级上——技能展开提示词，子代理委托执行，插件组织分发。

对于大多数编码工作流，我的建议是：先用技能固化可复用的指令，当需要专业委托和隔离上下文时加上子代理，最后当需要在团队或项目间分享时，把所有东西装进一个插件。

---

内容效果不满意？点此反馈