​

第八章. 插件系统：打包与分享你的工作流

本章学习路径

8.1. 为什么需要插件

上一章我们学会了用 Hooks 实现自动化。但有个问题一直没解决：

“我在 A 项目配了一套超好用的 Hooks 和自定义命令，B 项目也想用，怎么办？”

最笨的办法：复制粘贴。把 .claude/ 目录下的文件全部拷过去。

“那我有 10 个项目呢？”

复制 10 次。

“后来我改进了配置，想同步更新呢？”

再复制 10 次。

这就是 散装配置的痛点：难以复用、难以同步、难以分享。

8.1.1. 散装配置的三大痛点

痛点 1：跨项目复用困难

你在 .claude/commands/ 里写了一个超好用的 /review 命令，专门用来做代码审查。现在新开了一个项目，想用这个命令，只能手动复制文件过去。

痛点 2：团队共享麻烦

你写了一套团队规范的 Hooks（比如提交前自动跑 lint），想让队友也用上。怎么办？发个压缩包？建个共享文档？每次更新都要通知大家重新下载？

痛点 3：版本管理混乱

你的配置在不断迭代优化。但散落在各个项目里的副本版本不一，有的是 v1.0，有的是 v1.2，有的是你三个月前复制的"远古版本"。

8.1.2. 插件 vs 独立配置：何时用哪个

Claude Code 提供了两种方式来扩展功能：

“等等，插件的命令格式怎么多了个冒号？”

这就是 命名空间 机制。插件的所有命令都会带上插件名作为前缀，比如 /my-plugin:hello、/my-plugin:review。

“这不是更麻烦了吗？”

恰恰相反，这是为了 防止冲突。想象一下：你装了 A 插件和 B 插件，它们都有一个 /format 命令。如果没有命名空间，Claude 不知道该执行哪个。有了命名空间，就变成了 /a-plugin:format 和 /b-plugin:format，清清楚楚。

选择指南：

8.1.3. 本节小结

本节我们搞清楚了一个核心问题：为什么需要插件。

8.2. 插件结构解析

知道了为什么需要插件，现在来看看一个插件长什么样。

8.2.1. 最小插件结构

一个最简单的插件只需要两样东西：

1
2
3
4
5

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 插件清单（必须）
└── commands/
    └── hello.md         # 至少一个功能组件

就这么简单。.claude-plugin/plugin.json 是插件的"身份证"，告诉 Claude Code 这是一个插件、叫什么名字、版本多少。commands/ 目录放你的自定义命令。

“那 plugin.json 里写什么？”

最简版本：

1
2
3
4
5

{
  "name": "my-plugin",
  "description": "我的第一个插件",
  "version": "1.0.0"
}

三个字段，搞定。

8.2.2. 完整插件目录一览

当然，插件能做的远不止自定义命令。一个功能完整的插件可以包含：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 插件清单（必须）
├── commands/              # 斜杠命令
│   ├── review.md
│   └── format.md
├── agents/                # 自定义 Agent
│   └── security-expert.md
├── skills/                # Agent Skills（模型自动调用）
│   └── code-review/
│       └── SKILL.md
├── hooks/                 # 事件钩子
│   └── hooks.json
├── .mcp.json              # MCP 服务器配置
└── .lsp.json              # LSP 服务器配置（代码智能）

“commands 和 skills 有什么区别？”

commands 是用户主动调用的，你输入 /my-plugin:review，它才执行。

skills 是模型自动调用的。你不需要显式调用，Claude 会根据任务上下文自动判断

“哦，这个任务需要用到代码审查能力”，然后自动加载对应的 Skill。

8.2.3. plugin.json 清单文件详解

plugin.json 是插件的核心配置文件，我们来看看完整版长什么样：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "name": "code-quality-tools",
  "description": "代码质量工具集：审查、格式化、安全扫描",
  "version": "2.1.0",
  "author": {
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "homepage": "https://github.com/zhangsan/code-quality-tools",
  "repository": "https://github.com/zhangsan/code-quality-tools",
  "license": "MIT",
  "keywords": ["code-review", "formatting", "security"]
}

字段说明：

8.2.4. 本节小结

本节我们拆解了插件的内部结构：

8.3. 创建你的第一个插件

理论讲完了，现在来实战。我们从零开始创建一个 代码审查插件，包含一个斜杠命令和一个 Agent Skill。

8.3.1. 需求分析

我们要做一个叫 code-reviewer 的插件，功能如下：

最终目录结构：

1
2
3
4
5
6
7
8

code-reviewer/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── review.md
└── skills/
    └── security-check/
        └── SKILL.md

8.3.2. 创建插件目录和清单

步骤 1：创建目录结构

1
2
3

mkdir -p code-reviewer/.claude-plugin
mkdir -p code-reviewer/commands
mkdir -p code-reviewer/skills/security-check

步骤 2：创建 plugin.json

创建文件 code-reviewer/.claude-plugin/plugin.json：

1
2
3
4
5
6
7
8
9

{
  "name": "code-reviewer",
  "description": "代码审查工具集：风格检查、安全扫描、最佳实践建议",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["code-review", "security", "best-practices"]
}

8.3.3. 添加斜杠命令

斜杠命令是用户主动调用的功能。我们来创建一个 /code-reviewer:review 命令。

创建文件 code-reviewer/commands/review.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

---
description: 审查代码文件，检查风格、逻辑和潜在问题
---

# 代码审查命令

请对用户指定的代码文件进行全面审查，包括以下维度：

## 审查维度

1. **代码风格**
   - 命名规范（变量、函数、类）
   - 缩进和格式
   - 注释完整性

2. **逻辑问题**
   - 边界条件处理
   - 空值检查
   - 异常处理

3. **性能隐患**
   - 循环效率
   - 内存泄漏风险
   - 不必要的重复计算

4. **安全漏洞**
   - SQL 注入风险
   - XSS 风险
   - 敏感信息泄露

## 输出格式

请按以下格式输出审查结果：

### 问题清单

| 严重程度 | 位置 | 问题描述 | 修复建议 |
|:---|:---|:---|:---|
| 🔴 严重 | 第 X 行 | ... | ... |
| 🟡 警告 | 第 X 行 | ... | ... |
| 🔵 建议 | 第 X 行 | ... | ... |

### 总体评价

给出代码的整体质量评分（1-10 分）和改进建议。

## 用户输入

$ARGUMENTS

关键点解释：

• --- 包裹的部分是 前置元数据Markdown 文件开头的 YAML 格式元数据块，description 字段会显示在 /help 列表中
• $ARGUMENTS 是占位符，会被用户输入的参数替换。比如用户输入 /code-reviewer:review src/main.ts，那么 $ARGUMENTS 就会变成 src/main.ts

8.3.4. 添加 Agent Skill

Agent Skill 和斜杠命令不同，它是 模型自动调用 的。Claude 会根据任务上下文判断"这个任务需要用到安全检查能力"，然后自动加载对应的 Skill。

创建文件 code-reviewer/skills/security-check/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

---
name: security-check
description: 检查代码中的安全漏洞。当用户要求审查代码安全性、检查漏洞、或分析潜在攻击面时自动启用。
---

# 安全检查技能

当检查代码安全性时，请关注以下常见漏洞类型：

## 注入类漏洞

- **SQL 注入**：检查是否使用了字符串拼接构建 SQL 语句
- **命令注入**：检查是否将用户输入直接传递给 shell 命令
- **XSS**：检查是否对用户输入进行了转义

## 认证与授权

- **硬编码凭证**：检查代码中是否包含密码、API Key 等敏感信息
- **权限检查缺失**：检查敏感操作是否有权限验证

## 数据安全

- **敏感信息泄露**：检查日志、错误信息中是否包含敏感数据
- **不安全的随机数生成**：检查是否使用了 `Math.random()` 等不安全的随机数生成方式

## 输出格式

发现安全问题时，按以下格式报告：

| 风险等级 | 漏洞类型 | 位置 | 攻击场景 | 修复方案 |
|:---|:---|:---|:---|:---|
| 🔴 高危 | SQL 注入 | 第 X 行 | 攻击者可通过... | 使用参数化查询 |

关键点解释：

• name 和 description 是必须的 frontmatter 字段
• description 非常重要，Claude 会根据这个描述来判断何时自动调用这个 Skill
• Skill 的内容是给 Claude 看的指令，告诉它"当你需要做安全检查时，按这个思路来"

8.3.5. 本地测试插件

插件写好了，怎么测试？Claude Code 提供了 --plugin-dir 参数，可以直接加载本地插件目录进行测试。

步骤 1：启动 Claude Code 并加载插件

1

claude --plugin-dir ./code-reviewer

成功现象：Claude Code 正常启动，没有报错。

步骤 2：验证命令是否加载

1

/code....

在命令列表中，你应该能看到 /code-reviewer:review 命令。

步骤 3：测试命令

1

› /code-reviewer:review src/main.ts

Claude 会按照你在 review.md 中定义的指令，对指定文件进行代码审查。

步骤 4：验证 Skill 是否生效

Skill 是自动调用的，你不需要显式触发。试着让 Claude 做一个安全相关的任务：

1

› 帮我检查一下这个项目有没有安全漏洞

如果 Skill 配置正确，Claude 会自动加载 security-check Skill，按照你定义的检查维度进行安全扫描。

8.3.6. 本节小结

本节我们从零创建了一个完整的代码审查插件：

8.4. 插件市场机制

插件写好了，怎么分享给别人？总不能让队友也用 --plugin-dir 加载本地目录吧。

这就需要 插件市场（Marketplace） 了。

8.4.1. 市场是什么

简单说，市场就是一个 插件清单，告诉 Claude Code：“这里有哪些插件可以装，去哪里下载”。

市场可以是：

• 一个 GitHub 仓库
• 一个 GitLab 仓库
• 一个本地目录（开发测试用）

用户通过 /plugin marketplace add 命令添加市场，然后就能浏览和安装里面的插件了。

8.4.2. 创建本地市场（开发测试用）

在正式发布到 GitHub 之前，我们先创建一个本地市场来测试。

目录结构：

1
2
3
4
5
6
7
8
9
10
11

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json    # 市场清单
└── code-reviewer/          # 我们刚才创建的插件
    ├── .claude-plugin/
    │   └── plugin.json
    ├── commands/
    │   └── review.md
    └── skills/
        └── security-check/
            └── SKILL.md

步骤 1：创建市场目录

1
2

mkdir -p my-marketplace/.claude-plugin
mv code-reviewer my-marketplace/

步骤 2：创建 marketplace.json

创建文件 my-marketplace/.claude-plugin/marketplace.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "metadata": {
    "description": "我的个人插件市场"
  },
  "plugins": [
    {
      "name": "code-reviewer",
      "source": "./code-reviewer",
      "description": "代码审查工具集"
    }
  ]
}

步骤 3：添加市场并安装插件

1

claude

1

› /plugin marketplace add ./my-marketplace

成功现象：提示市场添加成功。

1

› /plugin install code-reviewer@my-marketplace

成功现象：提示插件安装成功，重启 Claude Code 后生效。

8.4.3. 发布到 GitHub（团队/社区共享）

本地测试通过后，就可以把市场发布到 GitHub 了。

步骤 1：创建 GitHub 仓库

在 GitHub 上创建一个新仓库，比如 your-username/claude-plugins。

步骤 2：推送市场目录

1
2
3
4
5
6

cd my-marketplace
git init
git add .
git commit -m "Initial commit: add code-reviewer plugin"
git remote add origin https://github.com/your-username/claude-plugins.git
git push -u origin main

步骤 3：团队成员添加市场

现在，任何人都可以通过以下命令添加你的市场：

1

› /plugin marketplace add your-username/claude-plugins

然后安装插件：

1

› /plugin install code-reviewer@your-username

8.4.4. marketplace.json 配置详解

我们来看看 marketplace.json 的完整配置选项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@company.com"
  },
  "metadata": {
    "description": "公司内部工具集",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./formatter",
      "description": "代码格式化工具",
      "version": "2.1.0",
      "author": {
        "name": "张三"
      },
      "keywords": ["formatting", "prettier"],
      "category": "productivity"
    },
    {
      "name": "security-scanner",
      "source": {
        "source": "github",
        "repo": "company/security-plugin"
      },
      "description": "安全扫描工具"
    }
  ]
}

顶层字段：

插件条目字段：

source 的三种写法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 写法 1：本地相对路径
"source": "./plugins/my-plugin"

// 写法 2：GitHub 仓库
"source": {
  "source": "github",
  "repo": "owner/repo-name"
}

// 写法 3：任意 Git 仓库
"source": {
  "source": "url",
  "url": "https://gitlab.com/team/plugin.git"
}

8.4.5. 本节小结

本节我们学习了插件市场机制：

8.5. 安装与管理插件

作为插件的使用者，你需要知道如何发现、安装、管理插件。

8.5.1. 添加市场源

在安装插件之前，你需要先添加市场源。

添加 GitHub 市场：

1

› /plugin marketplace add owner/repo-name

添加 GitLab 或其他 Git 仓库：

1

› /plugin marketplace add https://gitlab.com/team/plugins.git

添加本地市场（开发测试）：

1

› /plugin marketplace add ./path/to/marketplace

查看已添加的市场：

1

› /plugin

选择 “管理市场” 可以查看所有已添加的市场源。

8.5.2. 浏览和安装插件

方式 1：交互式浏览（推荐）

1

› /plugin

这会打开一个交互式菜单，你可以：

• 浏览可用插件
• 查看插件详情（描述、版本、功能）
• 一键安装

方式 2：直接安装

如果你已经知道插件名称：

1

› /plugin install plugin-name@marketplace-name

例如：

1

› /plugin install code-reviewer@my-marketplace

安装后：重启 Claude Code，插件就会生效。

8.5.3. 启用/禁用/卸载插件

禁用插件（保留配置，暂时不用）：

1

› /plugin disable plugin-name@marketplace-name

启用插件（重新启用已禁用的插件）：

1

› /plugin enable plugin-name@marketplace-name

卸载插件（完全移除）：

1

› /plugin uninstall plugin-name@marketplace-name

查看已安装的插件：

1

› /plugin

选择 “管理插件” 可以查看所有已安装的插件及其状态。

8.5.4. 团队级插件配置（自动安装）

“每个新入职的同事都要手动添加市场、安装插件，太麻烦了。”

Claude Code 支持在项目级别配置插件，团队成员克隆项目后，插件会自动安装。

步骤 1：在项目根目录创建配置

创建或编辑 .claude/settings.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-company/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "security-scanner@company-tools": true
  }
}

步骤 2：提交到 Git

1
2
3

git add .claude/settings.json
git commit -m "Add team plugin configuration"
git push

步骤 3：团队成员使用

当团队成员克隆项目并首次运行 Claude Code 时：

1. Claude Code 会检测到 .claude/settings.json 中的市场配置
2. 提示用户是否信任该项目
3. 用户确认后，自动添加市场并安装指定的插件

8.5.5. 本节小结

本节我们学习了插件的安装与管理：

8.6. 本章总结与插件开发速查

本章我们学习了 Claude Code 的插件系统——把散装的配置打包成可复用、可分享的标准格式。核心思想是：一次编写，到处使用。

8.6.1. 核心概念回顾

8.6.2. 场景速查：遇到这些情况，直接用

场景 1：创建最小插件

1
2

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands

my-plugin/.claude-plugin/plugin.json：

1
2
3
4
5

{
  "name": "my-plugin",
  "description": "插件描述",
  "version": "1.0.0"
}

my-plugin/commands/hello.md：

1
2
3
4
5
6

---
description: 打招呼命令
---
向用户问好，询问今天需要什么帮助。

用户输入：$ARGUMENTS

场景 2：本地测试插件

1

claude --plugin-dir ./my-plugin

场景 3：创建本地市场

my-marketplace/.claude-plugin/marketplace.json：

1
2
3
4
5
6
7
8
9
10
11

{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./my-plugin",
      "description": "我的插件"
    }
  ]
}

1
2

› /plugin marketplace add ./my-marketplace
› /plugin install my-plugin@my-marketplace

场景 4：发布到 GitHub

1
2
3
4
5
6

cd my-marketplace
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/you/claude-plugins.git
git push -u origin main

用户安装：

1
2

› /plugin marketplace add you/claude-plugins
› /plugin install my-plugin@you

场景 5：团队自动安装配置

.claude/settings.json：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-reviewer@team-tools": true
  }
}

8.6.3. 调试插件问题

插件不生效？命令找不到？别慌，按这个清单排查：

问题 1：命令没出现在 /help 列表中

问题 2：Skill 没有被自动调用

Skill 的触发依赖于 description 字段的描述质量。如果 Claude 没有自动调用你的 Skill，检查：

• description 是否清晰描述了 “什么情况下应该使用这个 Skill”
• 你的任务描述是否与 Skill 的 description 匹配

问题 3：插件安装后文件找不到

这是一个常见坑点：插件安装后会被 复制到缓存目录，而不是原地使用。如果你的 Hooks 或 MCP 配置引用了插件目录外的文件，会找不到。

解决方案：使用 ${CLAUDE_PLUGIN_ROOT} 变量引用插件内的文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

问题 4：验证插件语法

Claude Code 提供了验证命令，可以检查插件配置是否有语法错误：

1

claude plugin validate ./my-plugin

或者在 Claude Code 内部：

1

› /plugin validate ./my-plugin

8.6.4. 从独立配置迁移到插件

如果你已经在 .claude/ 目录下积累了一些好用的配置，想把它们打包成插件分享给团队，按这个步骤迁移：

迁移对照表：

迁移步骤：

步骤 1：创建插件骨架

1

mkdir -p my-plugin/.claude-plugin

步骤 2：创建 plugin.json

1
2
3
4
5

{
  "name": "my-plugin",
  "description": "从个人配置迁移而来的插件",
  "version": "1.0.0"
}

步骤 3：复制文件

1
2
3
4
5
6
7
8

# 复制命令
cp -r .claude/commands my-plugin/

# 复制 agents（如果有）
cp -r .claude/agents my-plugin/

# 复制 MCP 配置（如果有）
cp .mcp.json my-plugin/

步骤 4：迁移 Hooks

独立配置的 Hooks 在 settings.json 里，插件的 Hooks 需要单独放到 hooks/hooks.json：

创建 my-plugin/hooks/hooks.json：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
        }
      ]
    }
  ]
}

步骤 5：测试

1

claude --plugin-dir ./my-plugin

迁移后的变化：

8.6.5. 插件开发最佳实践

实践 1：语义化版本号

版本号遵循 主版本.次版本.修订号 格式：

• 主版本：不兼容的 API 变更（如命令名改了）
• 次版本：向后兼容的功能新增
• 修订号：向后兼容的问题修复

实践 2：写好 README

在插件根目录创建 README.md，包含：

• 插件功能介绍
• 安装方法
• 命令列表和使用示例
• 配置说明（如果有环境变量）

实践 3：命名规范

• 插件名：使用 kebab-case（如 code-reviewer）
• 命令名：简短有意义（如 review、format）
• Skill 名：描述能力（如 security-check、performance-analysis）

实践 4：最小权限原则

• MCP 服务器只配置必要的权限
• Hooks 只监听必要的事件
• 文件系统访问只授权必要的目录