Plugins 从入门到精通（上）

公众号名称：朱昆鹏AI手记

作者名称：朱昆鹏mm

发布时间：2026-05-21 23:27

一.前言

《Plugins 从入门到精通》我计划分为三个章节来写

• 上篇：讲解Plugins基础概念、目录结构和基本使用

• 中篇：讲解Plugins 的 manifest 完整字段、Marketplace 机制和高级配置

• 下篇：从源码角度来补充理解Plugins 的加载、缓存与运行机制

你现在阅读的是 上篇，咱们开始吧，希望能让你有所收获

读这篇之前，我建议你先看一下我之前写的《Skills 从入门到精通(上)》，这样会更好理解

因为 Plugins 和 Skills 是一对兄弟，Plugins 可以理解为 Skills 的”加强版”

---

二.Plugins 基础介绍

1.Plugins 的诞生

如果说 Skills 是一本”专业领域的说明书”，那 Plugins 就是一整个”工具箱”

Anthropic 在推出 Skills 之后，发现单纯一个 .md 文件还不够用

有时候用户想要的不只是给 AI 加一段说明，而是希望：

• 使用特定的AI Agent

• 设置生命周期 Hook（在操作前后自动执行某段脚本）

• 接入一个 MCP 服务器（让 AI 能调用外部工具）

把这些零碎东西分开装，又麻烦又容易乱

于是 Plugins 就诞生了——它把上面这些能力打包到一个目录里，一键安装、一键启用、一键禁用

简单理解： Skills 是一本书，Plugins 是一个图书馆

一个 Plugin 里面可以包含很多 Skills，再加上 commands、agents、hooks、MCP 服务等

2.Plugins 解决的核心痛点

我们先来看看，没有 Plugins 之前会有什么问题：

痛点一：能力分散

你想给团队加一套”前端开发规范+自动格式化命令+Hook 自动检查+MCP 接入 Figma”，要分别配置 4 个地方

配置完之后，团队里每个新人来都要再配一遍，离谱

痛点二：缺乏分发

就算你写好了一套规范，怎么给别人？发压缩包？发 GitHub？发完别人怎么装到他自己的环境里？

痛点三：版本管理混乱

你改了一个 hook 脚本，团队里有人在用旧版有人在用新版，没人知道谁是对的

Plugins 就是为了一次性解决这些问题

它让你：

• 把所有能力打包到一个目录里（commands、agents、skills、hooks、mcp、lsp 全都装得下）

• 通过 Marketplace（插件市场）一键安装和卸载

• 自带版本号和作者信息，方便维护和升级

• 支持user / project / local 三种作用域，灵活控制对谁生效

举个最直观的例子：

• 你想让团队用上”浓缩了 10 年经验的 Java 开发规范”——下载一个 java-best-practices 插件就行

• 你想让 AI 接入公司内部 Jira 系统——下载一个 jira-mcp 插件就行

• 你想给所有项目加上”提交前自动跑 lint”的 Hook——下载一个 pre-commit-guard 插件就行

---

三.Plugins 的构成

1.Plugin 存放位置

Plugin 的安装位置在哪里？根据源码 src/utils/plugins/pluginDirectories.ts，主要有两个地方：

第一种：本地缓存目录（全局）

默认是：～/.claude/plugins/（mac/linux）

里面的结构大概是这样：

～/.claude/plugins/
├── known_marketplaces.json   # 已注册的市场列表
├── installed_plugins.json    # 已安装的插件清单
├── marketplaces/             # 各个市场的本地缓存
│   └── claude-plugins-official/
│       └── .claude-plugin/
│           └── marketplace.json
└── cache/                    # 已下载的插件版本缓存
    └── my-plugin@some-market/
        └── 1.0.0/
            └── （插件实际内容）

这是 Claude Code 帮你管理的，你一般不用动手改

第二种：项目级 plugin 目录

放在你的项目下的 .claude-plugin/ 目录里

适合放和这个项目深度绑定的插件源代码

your-project/
└── .claude-plugin/
    └── plugin.json    ← plugin 元数据

如果你只是想”使用”插件，记住安装位置在 ～/.claude/plugins/ 就够了

如果你要”开发”插件，记住 .claude-plugin/plugin.json 这个文件就够了

2.plugin.json

一个 Plugin 必须包含一个 `plugin.json` 文件，位于插件目录下的 `.claude-plugin/plugin.json` 路径

它和 Skills 的 SKILL.md 类似，都是用来描述这个东西”是什么、能做什么”

下面是一个最小化的示例：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "这是一个演示插件",
  "author": {
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

只要这 4 个字段，一个最简 Plugin 就成型了

其中 name 是必填的，剩下的都是选填（但是建议都写上，方便别人识别）

plugin.json 里面还可以配置一堆字段，咱们这里先列举一下常用的，详细配置我们在中篇展开讲：

字段	类型	说明
name	string	插件名称（必填，建议 kebab-case，比如 my-plugin）
version	string	版本号，遵循 semver 规范（1.2.3）
description	string	简介，会显示在 /plugin 列表里
author	object	作者信息（name / email / url）
homepage	string	主页链接
repository	string	仓库地址
license	string	许可证（MIT / Apache-2.0 等）
keywords	array	关键字，用于检索
dependencies	array	依赖的其他插件

3.Plugin 完整目录

光有 plugin.json 还不够，Plugin 真正的”内容”在它的子目录里

一个完整的 Plugin 目录长这样：

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 必填，插件元数据
├── commands/              # 可选，自定义斜杠命令
│   ├── deploy.md          # /deploy 命令
│   └── format.md          # /format 命令
├── agents/                # 可选，自定义 AI 代理
│   └── reviewer.md        # 代码审查代理
├── skills/                # 可选，插件附带的 Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                 # 可选，生命周期 Hook
│   └── hooks.json
├── output-styles/         # 可选，输出风格定义
│   └── concise.md
├── .mcp.json              # 可选，MCP 服务器配置
└── .lsp.json              # 可选，LSP 语言服务器配置

我们一个一个简单说明（深入用法放在中篇）：

- commands/ —— 放 `.md` 文件，每个文件就是一个斜杠命令

比如 commands/deploy.md 就会被识别为 /my-plugin:deploy

- agents/ —— 放 `.md` 文件，每个文件就是一个独立的 AI 代理

适合那种”专门干一件事”的子 Agent，比如 code-reviewer

- skills/ —— 和咱们之前讲过的 Skills 一样

插件可以打包自己的 Skills，命名格式 pluginName:skillName

- hooks/ —— 生命周期钩子，在 `hooks.json` 里定义

支持 PreToolUse、PostToolUse、Stop 等多个时机

- output-styles/ —— 自定义 AI 输出的风格

- .mcp.json —— 接入 MCP 服务器（比如让 AI 控制浏览器、读取数据库等）

- .lsp.json —— 接入 LSP 语言服务器（让 AI 能像 IDE 一样进行代码补全和跳转）

这种”插件 = 一个目录 + 多种能力”的设计，比 Skills 的”插件 = 一个 .md 文件”灵活得多

所以 Plugins 才能成为 Claude Code 真正的扩展平台

4.三种作用域（Scope）

Plugin 比 Skills 还多了一个概念，叫 scope（作用域）

根据源码 src/utils/plugins/schemas.ts 里的定义：

PluginScopeSchema = z.enum(['managed', 'user', 'project', 'local'])

人话翻译一下：

Scope	含义	配置位置
managed	企业策略锁定，只读	企业管理员配置，普通用户不能改
user	全局用户级	～/.claude/settings.json
project	项目级，团队共享	项目/.claude/settings.json
local	项目级，个人覆盖	项目/.claude/settings.local.json

举个场景就明白了：

• 你想自己个人电脑上所有项目都装一个 Java 规范插件 → 用 user scope

• 你们团队所有人都要用同一个 deploy 命令插件 → 用 project scope（提交到 git）

• 你想本地测试一个还没正式发布的插件 → 用 local scope（不提交到 git）

• 公司强制所有人必须用安全审查插件 → 用 managed scope（管理员配置）

这个机制让 Plugin 既能”按个人喜好”也能”按团队规范”，灵活程度比 Skills 高一个量级

---

四.Plugins 怎么用

讲了这么多构成，咱们看看实际怎么操作

1.菜单模式

最简单的方式：在 Claude Code 里直接输入 /plugin

就会弹出一个交互式管理菜单，里面有：

• Install plugins —— 浏览市场，挑插件安装

• Manage plugins —— 启用/禁用/卸载已装插件

• Marketplaces —— 管理插件市场

• Validate —— 验证插件 manifest 是否正确

照着菜单点点点就行，对新人非常友好

2.命令模式

如果你已经知道想装什么，可以直接在终端用斜杠命令一步到位

根据源码 src/commands/plugin/parseArgs.ts 里支持的命令：

# 安装插件
/plugin install                     # 安装指定插件
/plugin install @      # 从指定市场安装
/plugin install            # 添加并浏览市场

# 管理插件
/plugin enable                      # 启用
/plugin disable                     # 禁用
/plugin uninstall                   # 卸载

# 管理市场
/plugin marketplace add                # 添加新市场
/plugin marketplace list                    # 列出所有市场
/plugin marketplace update                  # 更新所有市场
/plugin marketplace remove            # 移除市场

# 工具命令
/plugin validate                      # 验证 manifest
/plugin help                                # 查看帮助

注意：/plugin 和 /plugins 是同一个命令的两种写法，随便用哪个都行

3.CLI 模式

除了在交互界面里用，Plugins 还支持直接在命令行里操作（不用进 Claude Code）

这对脚本化和 CI/CD 特别有用

根据源码 src/services/plugins/pluginCliCommands.ts：

# 在系统命令行直接执行
claude plugin install  --scope user
claude plugin uninstall 
claude plugin enable 
claude plugin disable 
claude plugin update 
claude plugin disable-all

—scope 参数支持 user、project、local（默认 user）

这样你就可以写脚本，给新员工的电脑自动装上一整套团队规范插件，全程无需手动点击

---

五.Marketplace（插件市场）

讲到这里就不得不提 Marketplace（插件市场）了

它是 Plugins 和 Skills 之间最大的区别之一

Skills 没有市场的概念，你想用谁的 Skill，得自己去找他的 GitHub 仓库下载

而 Plugins 自带了一套完整的市场机制

1.官方市场

Anthropic 提供了一个官方的”插件市场”

根据源码 src/utils/plugins/officialMarketplace.ts：

export const OFFICIAL_MARKETPLACE_SOURCE = {
  source: 'github',
  repo: 'anthropics/claude-plugins-official',
}

也就是说，官方市场就是 GitHub 上的 anthropics/claude-plugins-official 仓库

里面收录了 Anthropic 官方维护的一批插件，是首装首选

2.支持哪些类型的市场？

根据 `MarketplaceSourceSchema` 的定义，Plugin 市场支持 7 种来源：

Source	说明	示例
github	GitHub 仓库	anthropics/claude-plugins-official
git	任意 Git URL	https://gitlab.com/xxx/yyy.git
url	直接给一个 marketplace.json 链接	https://example.com/marketplace.json
npm	NPM 包	@my-org/my-marketplace
file	本地文件	/path/to/marketplace.json
directory	本地目录	/path/to/marketplace-dir/
settings	settings.json 里内联定义	直接在配置文件里写

简单来说，只要是能托管文件的地方，都能做插件市场

3.marketplace.json 长啥样

一个市场的核心是 marketplace.json 文件，里面列了它包含的所有插件

最简化的 marketplace.json 结构：

{
  "name": "my-marketplace",
"owner": {
    "name": "张三",
    "email": "zhangsan@example.com"
  },
"plugins": [
    {
      "name": "java-best-practices",
      "source": "./plugins/java-best-practices",
      "description": "Java 开发最佳实践插件",
      "category": "productivity"
    },
    {
      "name": "jira-mcp",
      "source": {
        "source": "npm",
        "package": "@my-org/jira-mcp-plugin",
        "version": "^1.0.0"
      },
      "description": "Jira MCP 接入"
    }
  ]
}

可以看到，市场里每个 plugin 自己也能指定来源——可以是本地相对路径、npm 包、git 仓库等等

这种设计的好处是：

• 一个市场可以聚合不同来源的插件

• 团队 Leader 可以维护一个”内部市场”，把零散的内部插件统一管理起来

---

六.内置 Plugin（Built-in）

除了从市场安装的插件，Claude Code 还内置了一批”出厂自带”的插件

根据源码 src/plugins/builtinPlugins.ts：

export const BUILTIN_MARKETPLACE_NAME = 'builtin'

// 内置 plugin 的 ID 格式：name@builtin
// 用来和市场插件做区分

这些内置 Plugin 有几个特点：

- 跟着 Claude Code 一起发布，不需要单独安装

• 在 /plugin UI 里有独立的 “Built-in” 分组

- 用户可以启用或禁用，状态会保存在 user settings 里

• 一个内置 plugin 可以同时提供 skills、hooks 和 MCP 服务

简单理解：内置 Plugin 就是官方”预装”的一批通用工具，你可以选择开/关

---

七.结尾

读完本篇，我建议你按这个顺序自己练一下：

1. 在 Claude Code 里输入 /plugin，进菜单里逛一逛

2. 添加官方市场，挑一个感兴趣的插件装上试试

3. 在本地建一个 .claude-plugin/plugin.json，写一个最简化的 Hello World 插件

4. 用 /plugin validate 检查你的插件 manifest 是否合规

我们明天再会吧～

---

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