Plugin 扩展实战:增强 Claude Code 的能力深入讲解 Claude Code 的 Plugin 系统,包

引言:从单一功能到完整工具包

在前面的文章中,我们已经学习了:

Skills(第9篇):让 AI 掌握领域知识的模块化能力
Agent(第8篇):专业化的子智能体系统
Hooks(第4篇):事件驱动的自动化机制

但在实际使用中,你可能会遇到这些场景:

场景 1: 功能分散,难以管理

你的 .claude/ 目录下有:
├── commands/
│   ├── deploy.md
│   ├── test.md
│   └── format.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

问题:这些功能是一套完整的工作流,但分散在各处
     - 团队成员需要手动复制多个文件
     - 更新时需要逐个文件同步
     - 难以版本管理

场景 2: 团队共享困难

你: "我写了一套很好用的代码审查流程,包含 Agent、Skill 和 Hook"
同事: "能分享给我吗?"
你: "好的,你需要复制这3个文件到这里,那2个文件到那里..."
同事: "这么复杂?算了我自己写吧..." 😓

场景 3: 无法跨项目复用

项目 A 中精心配置的开发工具:
- Git 提交规范 Skill
- 代码格式化 Hook
- 测试运行 Agent
- CI/CD 集成 MCP

问题:切换到项目 B 时,又要重新配置一遍

💡 Plugin 系统的价值

Plugin 就是解决这些问题的终极方案——它是一个打包和分发机制:

📦 统一打包: 将 Skills、Agents、Hooks、MCP 打包成一个完整的工具包
🚀 一键安装: 通过 /plugin install 命令,一次性获得完整功能
♻️ 跨项目复用: 安装一次,在所有项目中使用
🔄 版本管理: 支持语义化版本,方便升级和回滚
🌐 生态共享: 通过 Marketplace 与社区共享优秀工具

本文核心内容:

Plugin 的核心概念与工作原理
Plugin、Skill、Agent、MCP、Hook 的关系梳理
官方 Plugin 介绍与使用场景
创建自定义 Plugin:从单一功能到完整工具包
Plugin Marketplace:构建团队和社区的工具生态
最佳实践:Plugin 的组织、测试和分发

"Plugin 是 Claude Code 扩展能力的顶层抽象,它让单一功能进化为可复用、可分发的完整工具包"

一、Plugin 系统全景图

1.1 什么是 Plugin?

Plugin(插件)是 Claude Code 的轻量级打包机制,用于组合多种扩展点:

Plugin = Skills + Agents + Hooks + MCP Servers + LSP Servers

核心特点:

📁 单一目录: 所有相关功能组织在一个目录中
📋 统一配置: 通过 plugin.json 管理元数据和依赖
🎯 一键安装: 用户无需关心内部结构,直接安装使用
🔄 版本控制: 支持语义化版本和自动更新

1.2 Plugin 与其他扩展机制的关系

让我们先用一张图来理解它们之间的关系:

图示内容:

最底层: Tools(Read、Write、Bash 等基础工具)
第二层: MCP Servers(连接外部服务)
第三层: Skills(领域知识)、Agents(专业子智能体)、Hooks(事件处理)
第四层: Plugin(打包层,将下层能力组合)
最顶层: Marketplace(分发层,Plugin 的生态市场)

各层级详解

层级	名称	作用	示例
基础层	Tools	Claude Code 内置的基础能力	Read、Write、Grep、Bash
连接层	MCP Servers	连接外部服务和工具	数据库查询、API 调用、文件系统访问
能力层	Skills	领域知识和工作流程	PDF 处理、BigQuery 分析、代码审查
能力层	Agents(Subagents)	专业化的子智能体	后端架构师、技术博客作者、测试工程师
能力层	Hooks	事件驱动的自动化	代码提交前检查、文件保存后格式化
打包层	Plugin	组合上述能力成完整工具包	完整的部署工具、代码审查系统
分发层	Marketplace	Plugin 的发现和安装平台	官方市场、团队市场、社区市场

1.3 Plugin vs 独立配置

Claude Code 支持两种方式添加自定义功能:

方式	位置	Skill 名称	适用场景
独立配置	`.claude/` 目录	`/hello`	个人工作流、项目特定定制、快速实验
Plugin	带 `.claude-plugin/plugin.json` 的目录	`/plugin-name:hello`	团队共享、社区分发、版本管理、跨项目复用

何时使用独立配置?

✅ 为单一项目定制
✅ 个人配置,无需共享
✅ 实验性功能,打包前的测试
✅ 想要短 Skill 名称(如 /hello 而非 /my-plugin:hello)

何时使用 Plugin?

✅ 需要与团队或社区共享
✅ 多个项目需要相同功能
✅ 需要版本控制和便捷更新
✅ 通过 Marketplace 分发
✅ 接受命名空间前缀(如 /my-plugin:hello,避免冲突)

最佳实践: 在 .claude/ 中快速迭代,功能成熟后转换为 Plugin 分发

二、Plugin 的结构与组成

2.1 标准 Plugin 目录结构

一个完整的 Plugin 目录结构如下:

enterprise-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # Plugin 清单文件(使用默认位置时可选)
├── commands/                 # 简单 Skills(单个 .md 文件)
│   ├── deploy.md
│   └── status.md
├── skills/                   # Agent Skills(推荐,目录+SKILL.md)
│   ├── code-reviewer/
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── pdf-processor/
│       ├── SKILL.md
│       └── reference.md
├── agents/                   # 子智能体
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # 事件钩子
│   ├── hooks.json
│   └── security-hooks.json
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
├── scripts/                 # 辅助脚本
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── README.md                # 使用文档
├── LICENSE                  # 许可证
└── CHANGELOG.md             # 版本历史

⚠️ 重要说明:目录位置

✅ 所有组件目录(commands/、skills/、agents/、hooks/)必须在 Plugin 根目录
❌ 不要把它们放在 .claude-plugin/ 目录内
✅ .claude-plugin/ 内只放 plugin.json

commands/ vs skills/ 的区别

特性	commands/	skills/
文件格式	单个 Markdown 文件(如 `deploy.md`)	目录包含 `SKILL.md`(如 `deploy/SKILL.md`)
适用场景	简单的斜杠命令,不需要额外资源	复杂的 Agent Skills,可包含脚本、参考文档
调用方式	`/plugin-name:command-name`	`/plugin-name:skill-name`
推荐使用	简单命令	推荐用于新 Skills(支持渐进式披露)
支持资源	不支持	支持(scripts、reference 文件等)

推荐做法:

✅ 新 Skills 使用 skills/ 目录格式
✅ 简单的一次性命令可以用 commands/
✅ 需要包含脚本、示例的复杂 Skill 必须用 skills/

2.2 Plugin 清单文件:plugin.json

plugin.json 是 Plugin 的配置文件,位于 .claude-plugin/ 目录下。

重要: 如果你的 Plugin 使用默认目录位置(commands/、skills/、agents/等)且不需要自定义配置,plugin.json 是可选的。Claude Code 会自动识别这些默认目录并从目录名推导 Plugin 名称。

当你需要以下功能时,plugin.json 是必需的:

指定 Plugin 的版本、描述、作者等元数据
使用自定义组件路径(非默认目录)
在 Marketplace 中分发(需要元数据)

完整的 plugin.json 示例:

{
  "name": "enterprise-tools",
  "version": "2.1.0",
  "description": "企业级开发工具集,包含部署、审查、测试完整流程",
  "author": {
    "name": "Development Team",
    "email": "dev@company.com",
    "url": "https://github.com/company"
  },
  "homepage": "https://docs.company.com/plugin",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["deployment", "code-review", "testing", "ci-cd"],
  "commands": ["./specialized/deploy.md"],
  "agents": "./custom-agents/",
  "skills": "./custom-skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "lspServers": "./.lsp.json"
}

必填字段(如果包含 plugin.json)

如果你选择创建 plugin.json,只有一个字段是必填的:

字段	类型	说明	示例
`name`	string	唯一标识符(kebab-case,无空格)	`"deployment-tools"`

注意: name 用于命名空间,如 Plugin 名为 my-plugin,其 Skill hello 在 UI 中显示为 /my-plugin:hello。如果不提供 plugin.json,Plugin 名称将从目录名自动推导。

元数据字段

字段	类型	说明
`version`	string	语义化版本号(如 `"2.1.0"`)
`description`	string	Plugin 用途的简短说明
`author`	object	作者信息(name、email、url)
`homepage`	string	文档 URL
`repository`	string	源代码 URL
`license`	string	许可证标识符(如 `"MIT"`)
`keywords`	array	用于发现的标签

组件路径字段

字段	类型	说明
`commands`	string\|array	额外的 Skill 文件/目录
`agents`	string\|array	额外的 Agent 文件
`skills`	string\|array	额外的 Skills 目录
`hooks`	string\|array\|object	Hook 配置路径或内联配置
`mcpServers`	string\|array\|object	MCP 配置路径或内联配置
`lspServers`	string\|array\|object	LSP 配置
`outputStyles`	string\|array	输出样式文件/目录

重要规则:

✅ 自定义路径补充默认目录,不替换
✅ 如果 commands/ 存在,会在自定义路径外额外加载
✅ 所有路径必须相对于 Plugin 根目录,以 ./ 开头
✅ 可以用数组指定多个路径

2.3 环境变量:`${CLAUDE_PLUGIN_ROOT}`

${CLAUDE_PLUGIN_ROOT} 包含 Plugin 目录的绝对路径。在 Hooks、MCP Servers 和脚本中使用,确保路径正确:

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

三、官方 Plugin 介绍

Claude Code 提供了一系列官方 Plugin,覆盖不同的开发场景。让我们深入了解几个典型的 Plugin:

3.1 feature-dev:完整的功能开发流程

用途: 7 阶段的功能开发工作流,从需求分析到部署

核心能力:

需求分析: 理解功能需求,识别边界情况
技术设计: 制定技术方案,评估权衡
代码实现: 逐步实现功能
单元测试: 编写测试用例
集成测试: 端到端测试
文档编写: 生成使用文档
Code Review: 自我审查和改进

适用场景:

新功能开发
模块重构
需要系统化流程的复杂任务

使用方式:

# 安装
/plugin install feature-dev

# 使用
/feature-dev:start "添加用户登录功能"

3.2 code-review:4 个并行代理的代码审查

用途: 多角度、全方位的代码审查系统

核心能力:

Security Agent: 安全漏洞检查(SQL注入、XSS、敏感信息泄露)
Performance Agent: 性能问题分析(算法复杂度、内存泄漏、数据库查询优化)
Best Practice Agent: 最佳实践检查(代码风格、设计模式、可维护性)
Test Coverage Agent: 测试覆盖率分析(缺失的测试用例、边界条件)

并行机制: 4个 Agent 同时工作,最后汇总报告

适用场景:

Pull Request 审查
代码质量把关
团队代码规范检查

使用方式:

# 安装
/plugin install code-review

# 审查当前分支
/code-review:review

# 审查指定文件
/code-review:review src/auth/login.ts

3.3 hookify:自然语言描述钩子

用途: 用自然语言描述 Hook 行为,无需编写脚本

核心能力:

将自然语言转换为 Hook 配置
自动选择合适的事件类型(PreToolUse、PostToolUse 等)
生成并测试 Hook 脚本

适用场景:

快速创建自动化流程
非开发人员配置 Hook
原型验证

使用方式:

# 安装
/plugin install hookify

# 创建 Hook
/hookify:create "当保存 Python 文件时,自动运行 black 格式化"

3.4 LSP Plugin 系列

LSP(Language Server Protocol) Plugins 为 Claude 提供实时代码智能:

Plugin	语言服务器	安装命令
`pyright-lsp`	Pyright (Python)	`pip install pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	见官方文档

核心能力:

✅ 即时诊断:编辑后立即看到错误和警告
✅ 代码导航:跳转到定义、查找引用
✅ 语言感知:类型信息和文档悬停提示

使用方式:

# 1. 先安装语言服务器
npm install -g typescript-language-server typescript

# 2. 安装 LSP Plugin
/plugin install typescript-lsp

注意: LSP Plugin 只配置连接,不包含语言服务器本身

3.5 更多官方 Plugin

访问官方 Marketplace 浏览完整列表:

/plugin discover

四、创建自定义 Plugin

4.1 快速入门:创建第一个 Plugin

让我们通过一个实战案例,创建一个简单的问候 Plugin:

Step 1: 创建 Plugin 目录

mkdir my-first-plugin

Step 2: 创建清单文件

mkdir my-first-plugin/.claude-plugin

创建 my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "学习基础的问候 Plugin",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Step 3: 添加 Skill

mkdir -p my-first-plugin/skills/hello

创建 my-first-plugin/skills/hello/SKILL.md:

---
description: 用友好的消息问候用户
disable-model-invocation: true
---

热情地问候用户,并询问今天有什么可以帮助的。

Step 4: 测试 Plugin

claude --plugin-dir ./my-first-plugin

在 Claude Code 中:

/my-first-plugin:hello

Step 5: 添加 Skill 参数

更新 hello/SKILL.md:

---
description: 用个性化消息问候用户
---

# Hello Command

热情地问候名为 "$ARGUMENTS" 的用户,并询问今天有什么可以帮助的。让问候语个性化且鼓舞人心。

测试:

/my-first-plugin:hello Alex

命名空间说明: Plugin Skill 总是带命名空间前缀(如 /my-first-plugin:hello),避免多个 Plugin 中同名 Skill 冲突

创建一个用于数据库 schema 迁移的完整工具:

Plugin 结构

db-migration-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── migration-generator/
│   │   ├── SKILL.md
│   │   └── templates/
│   │       ├── up.sql.tmpl
│   │       └── down.sql.tmpl
│   └── migration-validator/
│       └── SKILL.md
├── agents/
│   └── db-architect.md
├── .mcp.json
└── scripts/
    ├── generate-migration.sh
    └── validate-migration.sh

Skill:migration-generator/SKILL.md

---
name: migration-generator
description: 生成数据库迁移脚本。当需要创建 schema 变更、添加表、修改列时使用。
---

# 数据库迁移生成器

根据用户描述生成标准的数据库迁移脚本。

## 生成步骤

1. **理解变更需求**:
   - 询问变更类型(创建表、修改列、添加索引等)
   - 确认数据库类型(PostgreSQL、MySQL、SQLite)
   - 了解业务背景和约束

2. **生成迁移脚本**:
   - `up.sql`:应用变更的脚本
   - `down.sql`:回滚变更的脚本
   - 命名格式:`YYYYMMDDHHMMSS_description.sql`

3. **包含最佳实践**:
   - 使用事务包裹变更
   - 添加回滚点
   - 包含数据迁移逻辑(如果需要)
   - 添加详细注释

## 示例

用户: "添加 users 表的 email_verified 布尔字段,默认 false"

生成的迁移:

**202602120900_add_email_verified_to_users.up.sql**:
```sql
BEGIN;

-- 添加 email_verified 字段
ALTER TABLE users
ADD COLUMN email_verified BOOLEAN NOT NULL DEFAULT false;

-- 为已存在用户设置默认值
UPDATE users
SET email_verified = false
WHERE email_verified IS NULL;

-- 添加注释
COMMENT ON COLUMN users.email_verified IS '邮箱是否已验证';

COMMIT;

202602120900_add_email_verified_to_users.down.sql:

BEGIN;

-- 删除 email_verified 字段
ALTER TABLE users
DROP COLUMN IF EXISTS email_verified;

COMMIT;

使用模板文件 templates/up.sql.tmpl 和 templates/down.sql.tmpl 生成脚本。


#### Agent:db-architect.md

```markdown
---
name: db-architect
description: 数据库架构师。设计 schema、评估性能影响、制定迁移策略。当需要复杂的数据库设计时调用。
---

# Database Architect Agent

你是一位资深的数据库架构师,专注于 schema 设计、性能优化和数据迁移。

## 你的职责

1. **Schema 设计**:
   - 设计合理的表结构和关系
   - 选择合适的数据类型
   - 设计索引策略

2. **性能评估**:
   - 评估变更对查询性能的影响
   - 识别潜在的性能瓶颈
   - 提出优化建议

3. **迁移策略**:
   - 制定零停机迁移方案
   - 处理数据转换和回填
   - 评估回滚风险

## 工作流程

1. 理解业务需求和数据模型
2. 设计 schema 变更方案
3. 评估性能和风险
4. 生成迁移脚本
5. 制定测试和回滚计划

## 输出格式

**Schema 设计文档**:
- 表结构说明
- 字段类型和约束
- 索引设计
- 关系图示

**迁移计划**:
- 变更步骤
- 预估影响范围
- 回滚步骤
- 测试清单

MCP Server:.mcp.json

{
  "mcpServers": {
    "database-query": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

实际使用提示: 这个 MCP Server 连接到 PostgreSQL,允许 Claude 查询当前 schema,生成更准确的迁移脚本。

4.2 将独立配置转换为 Plugin

如果你已经在 .claude/ 中有配置,可以轻松转换为 Plugin:

Step 1: 创建 Plugin 结构

mkdir -p my-plugin/.claude-plugin

创建 my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "description": "从独立配置迁移",
  "version": "1.0.0"
}

Step 2: 复制现有文件

# 复制 Skills
cp -r .claude/commands my-plugin/
cp -r .claude/skills my-plugin/

# 复制 Agents
cp -r .claude/agents my-plugin/

# 复制 Hooks
mkdir my-plugin/hooks
# 从 settings.json 中提取 hooks 对象
# 粘贴到 my-plugin/hooks/hooks.json

Step 3: 迁移 Hooks

从 .claude/settings.json 复制 hooks 配置到 my-plugin/hooks/hooks.json。

注意:Hook 命令需要更新路径,使用 ${CLAUDE_PLUGIN_ROOT}:

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

Step 4: 测试迁移后的 Plugin

claude --plugin-dir ./my-plugin

迁移前后对比:

独立配置(`.claude/`)	Plugin
仅在一个项目中可用	可通过 Marketplace 共享
Skill 在 `.claude/commands/`	Skill 在 `plugin-name/skills/`
Hooks 在 `settings.json`	Hooks 在 `hooks/hooks.json`
手动复制共享	`/plugin install` 安装

清理旧配置: 迁移后,删除 .claude/ 中的原始文件,避免重复。Plugin 版本优先级更高。

五、Plugin Marketplace:构建工具生态

5.1 什么是 Plugin Marketplace?

Plugin Marketplace(插件市场)是 Plugin 的发现和安装平台:

📦 官方市场: Anthropic 提供的精选 Plugin
🏢 团队市场: 企业内部的 Plugin 仓库
🌐 社区市场: 开源社区贡献的 Plugin

5.2 Marketplace 的结构

一个 Marketplace 本质上是一个包含 marketplace.json 的 Git 仓库:

my-marketplace/
├── marketplace.json      # 市场配置
└── plugins/              # Plugin 源代码目录
    ├── plugin-a/
    ├── plugin-b/
    └── plugin-c/

marketplace.json 示例

{
  "name": "company-tools",
  "displayName": "Company Internal Tools",
  "description": "企业内部开发工具集",
  "version": "1.0.0",
  "homepage": "https://docs.company.com/plugins",
  "plugins": [
    {
      "name": "android-review",
      "displayName": "Android 代码审查",
      "description": "Android 代码审查工具集",
      "version": "1.0.0",
      "source": "./plugins/android-review",
      "author": {
        "name": "Android Team"
      },
      "tags": ["android", "code-review"]
    },
    {
      "name": "db-migration",
      "displayName": "数据库迁移工具",
      "description": "数据库 schema 迁移工具",
      "version": "1.2.0",
      "source": "./plugins/db-migration",
      "author": {
        "name": "Backend Team"
      },
      "tags": ["database", "migration"]
    }
  ]
}

5.3 创建团队 Marketplace

Step 1: 初始化 Git 仓库

mkdir company-plugins
cd company-plugins
git init

Step 2: 创建市场配置

创建 marketplace.json:

{
  "name": "company-tools",
  "displayName": "Company Tools",
  "description": "公司内部工具集",
  "version": "1.0.0",
  "plugins": []
}

Step 3: 添加 Plugin

mkdir -p plugins/my-tool
cp -r /path/to/my-plugin/* plugins/my-tool/

更新 marketplace.json:

{
  "plugins": [
    {
      "name": "my-tool",
      "displayName": "My Tool",
      "description": "我的工具描述",
      "version": "1.0.0",
      "source": "./plugins/my-tool",
      "author": { "name": "Your Name" }
    }
  ]
}

Step 4: 推送到 Git

git add .
git commit -m "Add my-tool plugin"
git push origin main

Step 5: 配置 Marketplace

编辑 .claude/settings.json:

{
  "pluginMarketplaces": [
    {
      "name": "company-tools",
      "url": "https://github.com/company/plugins.git",
      "autoUpdate": true
    }
  ]
}

Step 6: 使用 Marketplace

# 刷新市场
/plugin refresh

# 浏览可用 Plugin
/plugin discover

# 安装
/plugin install my-tool@company-tools

5.4 Plugin 的安装作用域

安装 Plugin 时,可以选择不同的作用域:

作用域	配置文件	适用场景
`user`	`~/.claude/settings.json`	个人 Plugin,跨所有项目(默认)
`project`	`.claude/settings.json`	团队共享,通过版本控制
`local`	`.claude/settings.local.json`	项目特定,gitignored
`managed`	`managed-settings.json`	托管 Plugin(只读,仅更新)

安装示例:

# 安装到 user 作用域(默认)
/plugin install formatter

# 安装到 project 作用域(团队共享)
/plugin install formatter --scope project

# 安装到 local 作用域(不提交)
/plugin install formatter --scope local

5.5 Plugin 缓存机制

出于安全和验证目的,Claude Code 会将 Plugin 复制到缓存目录:

工作流程:

用户通过 Marketplace 安装 Plugin
Claude Code 定位 Marketplace 和 Plugin 的 source 字段
根据 source 类型(相对路径、npm、pip、url、github)复制到缓存
从缓存加载 Plugin

路径遍历限制:

Plugin 不能引用其目录外的文件(如 ../shared-utils)
外部文件不会被复制到缓存

解决方案:

使用符号链接: 在 Plugin 目录内创建符号链接,指向外部文件
重构 Marketplace: 将 Plugin 路径设为父目录,包含所有依赖

六、Plugin 开发最佳实践

6.1 设计原则

1. 单一职责原则

✅ 每个 Plugin 专注一个领域(如代码审查、数据库迁移)
❌ 不要创建"万能 Plugin"包含无关功能

2. 组合优于继承

✅ 将小功能组合成 Plugin(Skills + Agents + Hooks)
✅ 用户可以选择安装多个小 Plugin,而非一个大而全的 Plugin

3. 约定优于配置

✅ 使用默认目录结构(skills/、agents/、hooks/)
✅ 仅在必要时使用自定义路径

4. 文档先行

✅ 提供清晰的 README.md
✅ 包含使用示例和常见问题
✅ 维护 CHANGELOG.md 记录版本变更

6.2 版本管理

遵循语义化版本(Semantic Versioning):

MAJOR.MINOR.PATCH

MAJOR: 破坏性变更(不兼容的 API 改动)
MINOR: 新功能(向后兼容的新增)
PATCH: Bug 修复(向后兼容的修复)

示例:

1.0.0: 第一个稳定版本
1.1.0: 添加新 Skill(向后兼容)
1.1.1: 修复 Hook 脚本 bug
2.0.0: Agent 接口改动(破坏性变更)
2.0.0-beta.1: 测试预发布版本

最佳实践:

✅ 分发前更新 plugin.json 中的版本号
✅ 在 CHANGELOG.md 记录变更
✅ 使用预发布版本测试(如 2.0.0-beta.1)

6.3 测试 Plugin

本地测试:

# 使用 --plugin-dir 加载 Plugin
claude --plugin-dir ./my-plugin

# 测试 Skills
/my-plugin:skill-name

# 测试 Agents
"请 my-plugin:agent-name Agent 执行任务"

# 测试 Hooks(触发相应事件)

多 Plugin 测试:

# 同时加载多个 Plugin
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b

调试技巧:

# 启用调试模式
claude --debug

# 或在 TUI 中
/debug

调试模式显示:

Plugin 加载详情
plugin.json 错误
Skill、Agent、Hook 注册信息
MCP Server 初始化日志

6.4 常见问题与调试

问题	原因	解决方案
Plugin 未加载	`plugin.json` 无效	使用 `/plugin validate` 验证 JSON
Skill 未出现	目录结构错误	确保 `skills/` 在根目录,不在 `.claude-plugin/` 内
Hook 未触发	脚本不可执行	运行 `chmod +x script.sh`
MCP Server 失败	缺少 `${CLAUDE_PLUGIN_ROOT}`	所有路径使用该变量
路径错误	使用绝对路径	所有路径必须相对,以 `./` 开头
LSP 错误: `Executable not found`	语言服务器未安装	安装二进制文件(如 `npm install -g typescript-language-server`)

示例错误信息:

清单验证错误:

Invalid JSON syntax: Unexpected token } in JSON at position 142

→ 检查缺少逗号、多余逗号或未引用的字符串

Plugin 加载错误:

Plugin directory not found at path: ./plugins/my-plugin

→ marketplace.json 中的 source 路径指向不存在的目录

Hook 故障排查:

检查脚本可执行:chmod +x ./scripts/script.sh
验证 shebang 行:#!/bin/bash 或 #!/usr/bin/env bash
确认路径使用 ${CLAUDE_PLUGIN_ROOT}
手动测试脚本:./scripts/script.sh

6.5 安全考虑

1. 脚本执行权限

✅ 最小权限原则:仅授予必要的权限
✅ 避免在 Hook 脚本中使用 sudo
❌ 不要在脚本中硬编码敏感信息(密码、API Key)

2. 环境变量

✅ 使用环境变量传递敏感配置
✅ 在 README 中说明需要的环境变量
❌ 不要在 plugin.json 中包含密钥

3. 第三方依赖

✅ 明确列出依赖(如 MCP Server 需要的 npm 包)
✅ 固定依赖版本,避免供应链攻击
✅ 定期更新依赖,修复安全漏洞

4. 输入验证

✅ 在 Hook 脚本中验证输入
✅ 避免直接执行用户输入

6.6 性能优化

1. 按需加载

Skills 使用渐进式披露(见第9篇)
Agents 仅在需要时调用
MCP Servers 延迟初始化

2. 减少 Token 占用

✅ Skills 的 description 字段简洁明确
✅ Agent 系统提示清晰但不冗长
✅ 避免在 Skill 中包含大量示例

3. 脚本执行效率

✅ Hook 脚本快速执行(< 1秒)
✅ 耗时任务异步执行
✅ 缓存计算结果

七、Plugin 生态与社区

7.1 发现 Plugin

官方 Marketplace:

/plugin discover

浏览分类:

Development: 代码生成、审查、测试
DevOps: 部署、CI/CD、监控
Database: Schema 管理、迁移、查询
Language Support: LSP Plugin(Python、TypeScript、Rust 等)
Productivity: 自动化、工作流、模板

社区资源:

Build with Claude: 社区 Plugin 市场
GitHub Topics: 开源 Plugin

7.2 分享 Plugin

方式 1: 提交到官方市场

高质量、通用性强的 Plugin
遵循官方指南和质量标准
通过 Pull Request 提交

方式 2: 创建团队市场

企业内部 Plugin
托管在内部 Git 仓库
配置到 settings.json

方式 3: 开源到 GitHub

创建公开仓库
添加详细 README 和示例
标记 claude-code-plugin topic

方式 4: 发布到 npm/pip

将 Plugin 发布为 npm 或 pip 包
在 Marketplace 中引用包名

八、实战总结

8.1 何时创建 Plugin?

使用独立配置(.claude/):

个人工作流,无需共享
项目特定定制
快速实验和原型

创建 Plugin:

功能成熟,需要跨项目复用
团队或社区共享
需要版本管理和更新机制
组合多个扩展点(Skills + Agents + Hooks + MCP)

8.2 Plugin 开发路径

初学者:

从简单的 Skill 开始(单个 SKILL.md)
添加 Agent 提供专业能力
配置 Hook 实现自动化
打包为 Plugin 分发

进阶开发者:

集成 MCP Server 连接外部服务
配置 LSP Server 提供代码智能
创建复杂的多组件 Plugin
维护团队 Marketplace

专家级:

开发可配置的通用 Plugin
贡献到官方市场
构建 Plugin 生态系统
编写 Plugin 开发工具

8.3 关键要点回顾

Plugin 是打包机制: 组合 Skills、Agents、Hooks、MCP、LSP
命名空间隔离: Plugin Skill 使用 /plugin-name:skill 格式
环境变量: ${CLAUDE_PLUGIN_ROOT} 确保路径正确
作用域管理: user、project、local 作用域灵活使用
版本控制: 遵循语义化版本,维护 CHANGELOG
测试先行: 使用 --plugin-dir 本地测试再分发
文档完善: README、示例、常见问题缺一不可

🔗 相关文章:

上一篇: Skills 实战:让 AI 成为你的领域专家

如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!

也欢迎访问我的个人主页发现更多宝藏资源

Plugin 扩展实战:增强 Claude Code 的能力

引言:从单一功能到完整工具包

💡 Plugin 系统的价值

一、Plugin 系统全景图

1.1 什么是 Plugin?

1.2 Plugin 与其他扩展机制的关系

各层级详解

1.3 Plugin vs 独立配置

二、Plugin 的结构与组成

2.1 标准 Plugin 目录结构

commands/ vs skills/ 的区别

2.2 Plugin 清单文件:plugin.json

必填字段(如果包含 plugin.json)

元数据字段

组件路径字段

2.3 环境变量:${CLAUDE_PLUGIN_ROOT}

三、官方 Plugin 介绍

3.1 feature-dev:完整的功能开发流程

3.2 code-review:4 个并行代理的代码审查

3.3 hookify:自然语言描述钩子

3.4 LSP Plugin 系列

3.5 更多官方 Plugin

四、创建自定义 Plugin

4.1 快速入门:创建第一个 Plugin

Plugin 结构

Skill:migration-generator/SKILL.md

MCP Server:.mcp.json

4.2 将独立配置转换为 Plugin

五、Plugin Marketplace:构建工具生态

5.1 什么是 Plugin Marketplace?

5.2 Marketplace 的结构

marketplace.json 示例

5.3 创建团队 Marketplace

5.4 Plugin 的安装作用域

5.5 Plugin 缓存机制

六、Plugin 开发最佳实践

6.1 设计原则

6.2 版本管理

6.3 测试 Plugin

6.4 常见问题与调试

6.5 安全考虑

6.6 性能优化

七、Plugin 生态与社区

7.1 发现 Plugin

7.2 分享 Plugin

八、实战总结

8.1 何时创建 Plugin?

8.2 Plugin 开发路径

8.3 关键要点回顾

2.3 环境变量:`${CLAUDE_PLUGIN_ROOT}`