第七篇：装了一堆插件不如搞懂这三件套 —— Skills、Subagents、Plugins 全解析

我在 Claude Code 上花了大半天配好了一套完美的工作流——代码审查规则、自动格式化 Hook、GitHub MCP 集成。当天效率翻了一倍。

第二天，新项目。全部白搭。

权限规则要重新配，Hooks 要重新写，MCP 要重新接。更尴尬的是同事过来问”你那个审查配置给我用用？”——我把 settings.json 发给他，他的环境跑不通，路径不对、命令不一样。我花了半小时帮他排查，比我自己配的时间还长。

那一刻我意识到，光会配置是不够的，你还得会打包你的配置。

Claude Code 有三种扩展机制：Skills、Subagents、Plugins。它们之间的边界其实很清楚，但很多人搞混了——包括我自己。写了一个 Skill 发现应该用 Subagent，建了一个 Subagent 又发现 Skill 就够了。花了好几周才理顺。

这篇把我交的学费整理出来，帮你少走弯路。

先建立直觉

别急着看配置，先搞清楚它们各自管什么。

Skills 就是一份 Markdown 写的操作手册。你写好规则，Claude 照着执行。没有独立进程，没有额外开销，创建一个文件就搞定。

Subagents 是另一个 Claude 实例。有自己的上下文窗口、自己的工具权限，干完活把结果交回来。你可以理解成请了一个专职帮手，活干完就走，不占你的工位。

Plugins 把上面这些东西打包成一个可安装的”应用”。装上就能用，卸掉就干净，团队成员一条命令搞定。

Skills：教 Claude 按你的方式做事

Skills 是最轻量的扩展方式。本质就是一个 SKILL.md 文件，里面写着指令，Claude 读了就知道该怎么做。

创建一个 Skill

mkdir -p .claude/skills/code-review

然后在里面创建 SKILL.md：

---name: code-reviewdescription: 审查代码质量，检查常见问题。在审查代码或用户说"review"时使用。---审查代码时，按以下顺序检查：1. 命名是否清晰——变量名能不能让人一眼看懂意图2. 错误处理是否完整——异常情况有没有兜底3. 安全问题——有没有注入风险、敏感数据泄露4. 性能——有没有明显的 N+1 查询或不必要的循环每个问题给出具体的代码位置和修改建议。

就这么简单。下次你在 Claude Code 里说”帮我 review 一下这个文件”，它会自动加载这个 Skill，按你定义的检查清单来审查。

你也可以直接用斜杠命令调用：

/code-review src/auth/login.ts

Skill 存放位置决定了谁能用

一个容易忽略的细节： 目录下的命令文件，和 Skills 是同一套机制。 官方已经把 commands 合并进了 Skills 体系。你之前写的 .claude/commands/deploy.md 和新写的 .claude/skills/deploy/SKILL.md 效果完全一样，老文件继续能用。

两种 Skill：参考型和任务型

参考型 —— 给 Claude 背景知识，让它在工作中自然运用。比如”我们项目的 API 规范”：

---name: api-conventionsdescription: 项目 API 设计规范---写 API 时遵循以下规范：- 路由用 RESTful 风格- 错误返回统一格式 { code, message, data }- 请求参数必须做校验

这种 Skill 不需要你主动调用，Claude 写代码时会自动参考。

任务型 —— 一套完整的操作流程，通常你手动触发。比如部署流程：

---name: deploydescription: 部署应用到生产环境disable-model-invocation: true---部署步骤：1. 跑完整测试套件2. 构建生产版本3. 推送到部署目标4. 验证部署是否成功

注意 disable-model-invocation: true 这行——它告诉 Claude”这个 Skill 不要自己决定什么时候用，等我说了才跑”。部署这种操作，你肯定不希望 Claude 觉得”代码看起来差不多了”就自己去部署。

进阶：动态注入和参数传递

Skills 支持参数替换。$ARGUMENTS 会被替换成你传入的内容：

---name: fix-issuedescription: 修复 GitHub Issuedisable-model-invocation: true---修复 GitHub Issue $ARGUMENTS，遵循项目编码规范。1. 读取 Issue 描述2. 分析需求3. 实现修复4. 写测试5. 创建 commit

/fix-issue 42 —— Claude 收到的就是”修复 GitHub Issue 42″。

还有个黑科技：! 反引号语法可以在 Skill 加载前执行 shell 命令，把结果注入进去：

## PR 上下文- diff 内容：!`gh pr diff`- 评论：!`gh pr view --comments`

Claude 看到的不是命令本身，而是命令执行后的实际输出。这样你的 Skill 就能拿到实时数据。

Subagents：给 Claude 配专职助手

Skill 能解决大部分扩展需求，但有两个场景它搞不定。

第一个是上下文保护。你的主对话窗口是有限的（200K token，Opus 4.6 可以到 1M）。让 Claude 用一个 Skill 去扫描大型代码库，几十个文件读完，上下文占了大半，后面的对话质量直线下降。Subagent 把这个过程隔离出去——探索消耗的是 Subagent 自己的上下文，主对话只收到最终结论。

第二个是权限隔离。你可能需要一个”只读审查员”，能看代码但绝对不能改。或者一个只能查数据库的助手，碰文件系统就越界了。Skill 做不到这种精细控制，Subagent 可以。

内置 Subagents

Claude Code 自带三个 Subagent，你不需要配置就能用：

你可能没注意到，Claude Code 一直在自动使用这些 Subagent。当你问”这个项目用了什么技术栈”，它不是自己去翻文件，而是派 Explore 去翻，然后把结果汇总给你。

创建自定义 Subagent

最快的方式是用交互命令：

/agents

选”Create new agent”，填写描述，Claude 帮你生成配置。

手动创建也很简单，在 .claude/agents/ 目录下放一个 Markdown 文件：

---name: security-auditordescription: 安全审计专家。在代码审查、安全检查时主动使用。tools: Read, Grep, Globmodel: sonnetmemory: project---你是一位安全审计专家。审查代码时重点关注：1. SQL 注入——所有数据库查询是否使用参数化2. XSS——用户输入是否正确转义3. 认证绕过——权限检查是否完整4. 敏感数据——密钥、密码是否硬编码发现问题时，说明风险等级（高/中/低）和修复方案。

几个配置值得说说。

tools 控制 Subagent 能用什么工具。上面这个只给了只读工具，看代码没问题，想改就改不了。反过来，如果你想保留大部分工具但禁掉特定几个，用 disallowedTools：

disallowedTools: Write, Edit

model 选什么模型跑 Subagent。haiku 最快最便宜，扫代码够用。sonnet 是日常主力。opus 适合需要深度推理的任务，但慢。填 inherit 就跟主对话用同一个模型。

memory 是我觉得最有意思的配置。设成 project，Subagent 会在 .claude/agent-memory/ 下维护自己的记忆文件，跨会话有效。上周审查时它发现你们项目习惯在 controller 层做参数校验，下次审查时它还记得这个模式，不会重复提醒。

给 Subagent 配专属 MCP

一个很实用的功能：你可以给 Subagent 接入主对话没有的 MCP Server。

---name: browser-testerdescription: 用真实浏览器测试功能mcpServers:  - playwright:      type: stdio      command: npx      args: ["-y", "@playwright/mcp@latest"]  - github---用 Playwright 工具在浏览器中测试功能。

Playwright MCP 只在这个 Subagent 的上下文里可用，不会污染主对话的工具列表。这个设计很聪明——MCP Server 太多会拖慢启动速度，还会让 Claude 选错工具。把不常用的 MCP 挂在 Subagent 上，按需启动。

怎么触发 Subagent

最常见的方式是让 Claude 自动判断。它根据你写的 description 决定什么时候委派任务，所以描述要写具体。”安全审计专家，在代码审查和安全检查时主动使用”——这个 Claude 知道什么时候该用。”一个有用的助手”——这个基本等于没写。

你也可以直接指定：”用 security-auditor 检查一下这个文件”。

两个进阶用法：background: true 让 Subagent 在后台跑，不阻塞你的主对话，适合耗时任务。isolation: worktree 让 Subagent 在独立的 Git worktree 里工作，改出来的代码在独立分支上，不碰你当前的代码状态。

Plugins：打包、分发、一键安装

配好了一堆 Skills 和 Subagents，同事过来问”你那套配置能给我用用吗？”——你把文件夹打包发给他，他解压到错误的目录，跑不通，来找你排查。

Plugin 就是为了解决这个分发问题。一个目录，里面可以包含 Skills、Subagents、Hooks、MCP 配置、甚至 LSP 服务器配置，打包好之后别人一条命令就能装上。

Plugin 的结构

my-plugin/├── .claude-plugin/│   └── plugin.json          # 插件元数据（必需）├── skills/                   # Skills│   └── code-review/│       └── SKILL.md├── agents/                   # Subagents│   └── security-auditor.md├── hooks/│   └── hooks.json            # Hooks 配置├── .mcp.json                 # MCP 配置├── .lsp.json                 # LSP 配置└── settings.json             # 默认设置

注意一个常见错误：Skills、Agents 这些目录放在 Plugin 根目录下，不是放在  里面。.claude-plugin/ 里只放 plugin.json。

plugin.json 长这样：

{  "name": "my-team-toolkit",  "description": "团队开发工具集",  "version": "1.0.0",  "author": {    "name": "Your Team"  }}

name 字段同时是命名空间。Plugin 里的 Skill 调用时要加前缀：/my-team-toolkit:code-review。这个设计防止不同 Plugin 之间的命名冲突。

从零创建一个 Plugin

假设你已经有了一些好用的 Skills 和 Subagents，想分享给团队。

# 1. 创建目录结构mkdir -p my-plugin/.claude-pluginmkdir -p my-plugin/skills/code-reviewmkdir -p my-plugin/agents# 2. 写 plugin.jsoncat > my-plugin/.claude-plugin/plugin.json << &#x27;EOF&#x27;{  "name": "team-standards",  "description": "团队编码规范和审查工具",  "version": "1.0.0"}EOF# 3. 把已有的 Skills 和 Agents 复制过来cp -r .claude/skills/code-review/* my-plugin/skills/code-review/cp .claude/agents/security-auditor.md my-plugin/agents/

测试和安装

开发阶段用 --plugin-dir 加载：

claude --plugin-dir ./my-plugin

修改了文件后不用重启，在对话里执行 /reload-plugins 就能热更新。

测试通过后，放到 Plugin Marketplace 上供人安装。Anthropic 有官方 Marketplace，也可以搭团队自己的。

一个安全细节

Plugin 里的 Subagent 不支持hooks、mcpServers 和 permissionMode 这三个配置字段。这是安全限制——防止你安装一个第三方 Plugin，它偷偷给自己加了 bypass 权限或者注入了恶意 Hook。

如果你确实需要这些配置，把 Subagent 文件从 Plugin 里复制到 .claude/agents/ 目录下，手动添加。

三者对比：什么时候用什么

这是最关键的部分。下面这张表够你在 90% 的场景下做出正确选择：

决策流程

碰到一个扩展需求，按这个顺序想：

1. 能用 Skill 解决吗？ 如果你只需要给 Claude 一些指令或规范，比如”用这种风格写测试”、”按这个流程部署”——用 Skill。轻量、简单、即时生效。

2. 需要独立上下文或权限隔离吗？ 如果任务会消耗大量上下文（比如扫描整个代码库），或者需要限制工具权限（比如只允许读不允许写），或者需要跨会话记忆——用 Subagent。

3. 需要分享给别人吗？ 把 Skills、Subagents、Hooks 打包成 Plugin。一条命令安装，不需要手动复制文件。

大多数场景，Skill 就够了。Subagent 是在你真正需要”隔离”的时候才上。Plugin 是在你需要”分发”的时候才上。

三个反面案例

不该用 Subagent 的场景： 我有一段时间给每个代码审查规则都创建了一个 Subagent——安全审查一个、性能审查一个、风格审查一个。结果每次审查，Claude 要依次启动三个 Subagent，等半天不说，最后三份报告还有互相矛盾的地方。后来合成一个 Skill，里面列清楚所有检查项，快了三倍，结果还更一致。

不该用 Skill 的场景： 让 Claude 用一个 Skill 去扫描整个 monorepo 的依赖关系。Skill 跑在主对话上下文里，几十个文件读完，上下文直接快满了。换成 Subagent（特别是用 Explore 类型），扫描在独立上下文里完成，主对话只收到一份整理好的报告。

不该单独用 Skill/Subagent 的场景： 团队里五个人各自复制了你的审查配置，但配置文件更新了，要挨个通知他们手动更新。打成 Plugin 放到团队 Marketplace，更新版本号就行，大家重新安装一下即可。

实战：为团队搭建一套审查工具链

把前面学的串起来，做一个真实的例子。

需求

团队需要一套代码审查工具：

• • 一份审查规范（所有人遵循统一标准）
• • 一个安全审计助手（独立运行，只读权限）
• • 打包成 Plugin 方便新成员安装

第一步：创建审查规范 Skill

---name: review-standardsdescription: 团队代码审查标准。在 review 代码时自动使用。---代码审查清单：## 必查项- 函数不超过 30 行- 变量命名用 camelCase- 所有公开 API 有入参校验- 错误处理不用空 catch- 没有硬编码的密钥或密码## 建议项- 复杂逻辑有注释说明"为什么"- 单元测试覆盖核心路径- 日志输出包含足够上下文审查结果按"必须修改"和"建议修改"分类输出。

第二步：创建安全审计 Subagent

---name: security-scandescription: 安全审计。在检查安全漏洞或敏感信息泄露时主动使用。tools: Read, Grep, Globmodel: sonnetmemory: project---你是一位应用安全专家。扫描代码时关注：1. OWASP Top 10 漏洞2. 硬编码的密钥、Token、密码3. 不安全的加密方式（MD5、SHA1 用于密码）4. 未经验证的用户输入直接用于查询或命令5. 过于宽松的 CORS 配置每个发现包含：风险等级、代码位置、攻击方式、修复建议。把发现记录到你的记忆里，下次扫描时对比上次的结果。

第三步：打包成 Plugin

mkdir -p team-review-kit/.claude-pluginmkdir -p team-review-kit/skills/review-standardsmkdir -p team-review-kit/agents

写 plugin.json：

{  "name": "team-review-kit",  "description": "团队代码审查工具集：审查规范 + 安全扫描",  "version": "1.0.0",  "author": { "name": "Your Team" }}

复制 Skill 和 Subagent 到对应目录，测试：

claude --plugin-dir ./team-review-kit

验证 /team-review-kit:review-standards 和 security-scan Subagent 都能正常工作后，推到团队 Marketplace。

新成员加入，一条命令搞定：

/plugin install team-review-kit

审查规范自动加载，安全扫描助手随时待命。不需要复制配置文件，不需要讲解怎么设置。

踩过的坑

Skill 别写太长。官方建议 SKILL.md 不超过 500 行，这个限制是有道理的——Claude 读 Skill 本身就要消耗上下文。我早期有个 Skill 写了 800 多行，把各种边界情况都列进去了，结果 Claude 光消化这份”手册”就用掉了大量 token，反而影响了后续对话质量。后来拆成一个 200 行的主文件加几个 supporting files，效果好多了。

Subagent 的工具给少不给多。工具列表太长，Subagent 反而选不准该用哪个。一个只读审查员，Read、Grep、Glob 三件套就够了。我试过给一个审查 Subagent 开放所有工具，它有时候会”顺手”改代码，完全不是你要的。

Plugin 调用 Skill 必须带命名空间前缀，比如 /team-toolkit:deploy，这不是 bug。两个不同 Plugin 都有叫 deploy 的 Skill 怎么办？命名空间就是防这个的。嫌麻烦的话，在 .claude/skills/ 里建一个同名 Skill 做转发就行。

还有一个架构限制要知道：Subagent 不能再生成 Subagent。主对话可以派 Subagent，但 Subagent 内部不能继续嵌套。需要多个 Agent 协同作战的场景，用 Agent Teams（--agent 模式），后面第 12 篇会专门讲。

回到开头那个场景——花大半天配好的工作流，换个项目就白搭。现在你知道怎么解决了：Skill 写规则，Subagent 做隔离，Plugin 做分发。我那套审查工作流后来打成了 Plugin，团队新人入职当天就能用上，再没帮人排查过配置问题。

不过有一条经验比任何技术细节都管用：先 Skill，不够再 Subagent，需要分享再 Plugin。 你永远不知道一个简单的 Skill 能走多远，直到它真的撞了墙。

这篇反复提到一个词：上下文。Skill 要吃上下文，Subagent 的卖点之一是保护上下文，上下文用完了 Claude 说话就开始不着调。

下一篇就聊这个——200K token 听着挺多，为什么用着用着就不够了？大项目里怎么让 Claude 始终保持清醒？/compact、Subagent 分流、还有几个你八成没试过的技巧，下篇一起讲。

FutureCraft AI · 未来构界

Claude Code 从入门到精通 · 第 7 篇，共 15 篇

2026年3月