Claude Code Plugins 深度指南：打造你的 AI 编程助手扩展生态

引言：为什么你需要了解 Claude Code Plugins

如果你正在使用 Claude Code（Anthropic 官方的 CLI 工具），你可能已经体验过它强大的代码生成和分析能力。但你是否想过，如何让这个 AI 助手变得更加个性化，更贴合你的工作流程？

Claude Code Plugins 正是答案。

想象一下这些场景：

• 团队有一套固定的代码审查标准，希望 Claude 自动遵循
• 每次提交代码都要执行特定的格式化脚本
• 需要将 Claude 与内部工具链无缝集成
• 希望创建可复用的工作流，在多个项目间共享

这些需求，Plugins 都能满足。

本文将带你深入理解 Claude Code Plugins 的架构设计，手把手教你开发自己的插件，并分享实战经验和最佳实践。

第一章：理解 Plugin 的本质

1.1 Plugin 是什么

Claude Code Plugin 是一套可分发、可版本化的扩展系统，用于打包和共享自定义功能。简单来说，它就像是给 Claude Code 安装的”App”——你可以安装别人开发的插件，也可以创建自己的插件分享给他人。

每个 Plugin 都有：

• 唯一命名空间：如 /my-plugin:command，避免命令冲突
• 语义版本号：遵循 MAJOR.MINOR.PATCH 规范
• 独立分发能力：通过 Marketplace 机制共享

1.2 Plugin vs 项目级配置

在深入之前，我们需要区分两种配置方式：

选择建议：

• 如果功能仅用于当前项目，用项目级配置
• 如果需要跨项目共享或团队协作，用 Plugin

1.3 Plugin 能包含什么

一个 Plugin 可以包含以下组件的任意组合：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必需：插件清单
├── commands/                 # Slash 命令
│   └── deploy.md
├── agents/                   # 自定义 Agents（子代理）
│   └── code-reviewer.md
├── skills/                   # Agent Skills（技能）
│   └── sql-expert/
│       └── SKILL.md
├── hooks/
│   └── hooks.json            # 事件钩子
├── .mcp.json                 # MCP 服务器配置
├── scripts/                  # 辅助脚本
└── README.md

注意：只有 plugin.json 放在 .claude-plugin/ 目录中，其他所有目录都在插件根目录。

第二章：Plugin 生态中的四大概念

在深入开发之前，理解 Plugin 与其他概念的关系至关重要。

2.1 Plugins vs Skills：主动 vs 被动

这是最容易混淆的两个概念。

Skills（技能） 是被动的：

• Claude 根据任务上下文自动决定是否使用
• 用户不需要显式调用
• 适合给 Claude 注入领域知识或能力
• 例如：SQL 专家技能、代码审查指南

Plugins 是主动的：

• 提供显式的命令（如 /deploy）
• 用户主动调用或事件触发
• 适合封装工作流和自动化
• 例如：部署工具、格式化命令

有趣的是：Plugin 可以包含 Skills。当你安装一个 Plugin 后，其中的 Skills 会自动生效，Claude 在相关任务中会自动使用它们。

2.2 Plugins vs MCP：扩展 vs 集成

MCP (Model Context Protocol) 的核心是连接：

• 连接外部工具和数据源
• 让 Claude 能调用外部 API
• 传输协议：stdio、HTTP、SSE

Plugins 的核心是扩展：

• 扩展 Claude Code 本身的能力
• 打包命令、技能、自动化为一体
• 分发机制：Marketplace

实际关系：Plugin 可以捆绑 MCP 服务器。当 Plugin 被启用时，其中配置的 MCP 服务器会自动启动。

// Plugin 中的 .mcp.json
{
  "mcpServers": {
    "internal-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "3000"]
    }
  }
}

2.3 Plugins vs Hooks：功能 vs 事件

Hooks（钩子） 是事件驱动的自动化：

• 在特定事件发生时触发
• 可以拦截、修改或增强行为
• 支持的事件：PreToolUse、PostToolUse、UserPromptSubmit 等

Plugins 是功能的载体：

• 可以包含 Hooks 配置
• 提供打包和分发能力

典型用例：在 Plugin 中配置 Hooks，实现”每次写入文件后自动格式化”：

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

2.4 关系总结图

┌─────────────────────────────────────────────┐
│                  PLUGIN                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐        │
│  │Commands │ │ Skills  │ │  Hooks  │        │
│  │ /deploy │ │ 自动使用 │ │ 事件驱动│        │
│  └─────────┘ └─────────┘ └─────────┘        │
│                                              │
│  ┌─────────┐ ┌─────────┐                    │
│  │  MCP    │ │ Agents  │                    │
│  │外部集成 │ │ 子代理  │                    │
│  └─────────┘ └─────────┘                    │
└─────────────────────────────────────────────┘
            │
            ▼ 分发
      ┌───────────┐
      │Marketplace│
      └───────────┘

第三章：从零开始创建你的第一个 Plugin

理论讲够了，让我们动手实践。

3.1 创建基础结构

# 创建目录结构
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/commands
mkdir -p my-first-plugin/scripts

cd my-first-plugin

3.2 编写插件清单

创建 .claude-plugin/plugin.json：

{
  "name": "dev-toolkit",
  "version": "1.0.0",
  "description": "开发工具集：代码审查、部署、格式化",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "keywords": ["development", "tools", "automation"]
}

字段说明：

• name：唯一标识，使用 kebab-case，将作为命令前缀
• description：Claude 会读取这个描述来理解插件用途
• version：遵循语义版本规范

3.3 创建第一个命令

创建 commands/review.md：

---
description: 对当前分支的代码进行全面审查
---

# 代码审查命令

## 任务
对当前 Git 分支相对于 main 分支的所有改动进行代码审查。

## 审查标准
1. **代码质量**：命名清晰、逻辑简洁、无冗余
2. **安全性**：检查潜在的安全漏洞（SQL注入、XSS等）
3. **性能**：识别可能的性能问题
4. **可维护性**：代码是否易于理解和修改

## 输出格式
按优先级（高/中/低）列出发现的问题，每个问题包含：
- 问题描述
- 具体位置（文件名:行号）
- 建议的修复方案

如果用户提供了参数 "$ARGUMENTS"，将其作为额外的审查重点。

3.4 添加辅助脚本

创建 scripts/format.sh：

#!/bin/bash
# 格式化脚本
FILE="$1"
if [[ "$FILE" == *.py ]]; then
    black "$FILE" 2>/dev/null || echo "black not installed"
elif [[ "$FILE" == *.js ]] || [[ "$FILE" == *.ts ]]; then
    prettier --write "$FILE" 2>/dev/null || echo "prettier not installed"
fi

记得添加执行权限：

chmod +x scripts/format.sh

3.5 配置 Hooks

创建 hooks/hooks.json：

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

这个 Hook 会在每次文件写入或编辑后自动执行格式化脚本。

3.6 本地测试

# 使用 --plugin-dir 加载本地插件
claude --plugin-dir ./my-first-plugin

# 在 Claude Code 中使用
/dev-toolkit:review
/dev-toolkit:review 特别关注安全问题

3.7 验证插件

claude plugin validate .

第四章：进阶——创建 Skill 和 Agent

4.1 添加 Skill

Skills 让 Claude 在特定领域表现得更专业。

创建 skills/sql-expert/SKILL.md：

---
name: sql-expert
description: SQL 数据库查询优化和设计专家
allowed-tools: Read, Bash(psql:*, mysql:*)
---

# SQL 专家技能

当用户涉及 SQL 相关任务时，你应该：

## 查询优化
- 分析执行计划，识别全表扫描
- 建议适当的索引
- 优化 JOIN 顺序

## 设计原则
- 遵循第三范式，除非有明确的反范式理由
- 适当使用分区表处理大数据量
- 考虑读写分离场景

## 常见反模式
- SELECT * 的过度使用
- N+1 查询问题
- 在 WHERE 子句中对列使用函数

当用户问 SQL 相关问题时，Claude 会自动应用这个技能中的知识。

4.2 添加 Agent

Agents 是专门化的子代理，Claude 会在适当的时候自动委派任务给它们。

创建 agents/security-auditor.md：

---
description: 安全审计专家，专门分析代码中的安全漏洞
allowed-tools: Read, Grep, Glob
---

# 安全审计代理

你是一个专业的安全审计员。当被委派安全相关的审计任务时：

## 检查清单

### 1. 注入攻击
- SQL 注入
- 命令注入
- XSS（跨站脚本）

### 2. 认证与授权
- 硬编码凭据
- 不安全的 Session 管理
- 权限绕过

### 3. 敏感数据
- 明文密码
- API 密钥泄露
- 日志中的敏感信息

## 输出格式

对每个发现的问题，提供：
1. 严重级别（Critical/High/Medium/Low）
2. 具体位置
3. 问题描述
4. 修复建议
5. 参考资料（如 OWASP 指南链接）

第五章：Marketplace——让插件走向更广阔的舞台

5.1 什么是 Marketplace

Marketplace 是 Plugin 的分发中心，可以是：

• GitHub 仓库：最常见的方式
• GitLab/其他 Git 服务
• 本地目录：用于内部团队

5.2 创建 Marketplace

创建以下结构：

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    ├── dev-toolkit/
    │   └── ... (你的插件)
    └── another-plugin/
        └── ...

marketplace.json 内容：

{
  "name": "my-team-plugins",
  "owner": {
    "name": "DevOps Team",
    "email": "devops@company.com"
  },
  "metadata": {
    "description": "内部工具集合",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "dev-toolkit",
      "source": "./plugins/dev-toolkit",
      "description": "开发工具集",
      "version": "1.0.0",
      "category": "productivity"
    }
  ]
}

5.3 发布到 GitHub

# 初始化仓库
cd my-marketplace
git init
git add .
git commit -m "Initial marketplace setup"

# 推送到 GitHub
git remote add origin https://github.com/your-org/claude-plugins.git
git push -u origin main

5.4 用户安装

其他用户可以这样安装你的插件：

# 添加 Marketplace
/plugin marketplace add your-org/claude-plugins

# 安装特定插件
claude plugin install dev-toolkit@your-org/claude-plugins

# 或安装到用户级别（所有项目可用）
claude plugin install dev-toolkit@your-org/claude-plugins --scope user

5.5 企业级管控

对于企业用户，可以通过 managed-settings.json 限制只能使用批准的 Marketplace：

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "company/approved-plugins"
    }
  ]
}

第六章：最佳实践与常见问题

6.1 开发最佳实践

1. 保持插件聚焦

一个插件应该解决一类相关问题，而不是包罗万象。

❌ 错误：一个插件包含代码审查、部署、数据库管理、报表生成...
✅ 正确：dev-toolkit（开发工具）、deploy-tools（部署工具）分开

2. 语义化版本

1.0.0 → 1.0.1  # Bug 修复
1.0.0 → 1.1.0  # 新增功能（向后兼容）
1.0.0 → 2.0.0  # 破坏性变更（不兼容旧版）

3. 使用相对路径和变量

// ❌ 错误
"command": "/Users/me/scripts/format.sh"

// ✅ 正确
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"

4. 编写清晰的描述

描述是 Claude 理解插件用途的关键：

// ❌ 模糊
"description": "工具"

// ✅ 清晰
"description": "Python 代码质量工具：自动格式化(black)、类型检查(mypy)、lint(flake8)"

6.2 常见问题排查

6.3 调试技巧

# 启用调试模式
claude --debug

# 查看已安装的插件
claude plugin list

# 验证插件结构
claude plugin validate ./my-plugin

第七章：实战案例——构建一个完整的 CI/CD 助手插件

让我们综合所学，构建一个实用的 CI/CD 助手插件。

7.1 需求分析

这个插件需要：

1. 命令：部署到不同环境、回滚、查看状态
2. Skill：CI/CD 最佳实践知识
3. Hook：部署前自动运行测试
4. MCP：连接到内部部署 API

7.2 完整结构

cicd-assistant/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy.md
│   ├── rollback.md
│   └── status.md
├── skills/
│   └── cicd-expert/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── servers/
│   └── deploy-api-server.js
└── README.md

7.3 核心文件示例

plugin.json：

{
  "name": "cicd-assistant",
  "version": "1.0.0",
  "description": "CI/CD 助手：部署、回滚、状态监控",
  "author": { "name": "DevOps Team" },
  "keywords": ["cicd", "deploy", "devops"]
}

commands/deploy.md：

---
description: 部署应用到指定环境（staging/production）
---

# 部署命令

将当前分支部署到 $1 环境。

## 前置检查
1. 确认当前分支状态
2. 检查是否有未提交的更改
3. 验证测试是否通过

## 部署流程
1. 构建 Docker 镜像
2. 推送到镜像仓库
3. 更新 Kubernetes 部署
4. 等待 Pod 就绪
5. 执行健康检查

## 环境参数
- staging：测试环境
- production：生产环境（需要额外确认）

如果是生产环境，请先确认用户是否理解风险。

hooks/hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "npm test",
            "timeout": 60000,
            "description": "部署前运行测试"
          }
        ]
      }
    ]
  }
}

结语：Plugin 生态的未来

Claude Code Plugins 代表了 AI 编程助手发展的一个重要方向：可扩展性和个性化。

随着生态的成熟，我们可以期待：

• 更丰富的社区 Marketplace
• 更强大的企业级管理能力
• 与更多开发工具链的深度集成

现在正是学习和投入 Plugin 开发的最佳时机。无论你是想提升个人效率，还是为团队构建标准化工具链，Plugin 都能帮你实现目标。

开始动手吧！ 从一个简单的命令开始，逐步构建你的 AI 编程助手扩展生态。

本文基于 Claude Code 官方文档编写，如需了解更多细节，请访问 https://docs.anthropic.com