2.5 Claude Code 插件系统完全指南

版本要求: Claude Code v2.0.12+ 状态: 公开测试版 (Public Beta) 官方文档: code.claude.com/docs/en/plugins

一、什么是 Claude Code 插件？

Claude Code 插件是一种轻量级扩展包，可以将自定义功能打包并在项目和团队之间共享。通过插件，你可以：

安装来自 Marketplace 的预构建功能
创建自己的自定义工作流
在团队中统一开发规范

Claude Code 插件概览

Claude Code 插件系统架构概览

1.1 插件包含的组件

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

组件类型	英文名	调用方式	用途
斜杠命令	Slash Commands	用户通过 `/命令名` 调用	常用操作的快捷方式
子代理	Subagents	Claude 自动调用	专门任务的智能助手
技能	Skills	Claude 自动识别并调用	模型主动决定何时使用
钩子	Hooks	事件自动触发	工作流关键点的自动化
MCP 服务器	MCP Servers	Claude 自动连接	外部工具和数据源集成

1.2 Commands vs Skills vs Agents

这三个概念容易混淆，让我们用一个表格来区分：

特性	Commands（命令）	Skills（技能）	Agents（代理）
触发方式	用户显式调用 `/xxx`	Claude 自动识别	Claude 根据任务调用
交互模式	单次执行	能力增强	多轮对话
适用场景	固定流程任务	特定领域知识	复杂专业任务
示例	`/commit` 提交代码	PDF 处理技能	安全审查代理

通俗理解：

Command = 按钮（你按一下，执行一个动作）
Skill = 技能（Claude 遇到相关问题自动使用）
Agent = 专家（Claude 请专家来处理复杂问题）

二、插件目录结构

2.1 标准目录布局

text

my-plugin/
├── .claude-plugin/           # 元数据目录（必需）
│   └── plugin.json          # 插件清单文件（必需）
├── commands/                 # 斜杠命令（可选）
│   ├── deploy.md
│   └── test.md
├── agents/                   # 子代理（可选）
│   ├── security-reviewer.md
│   └── code-optimizer.md
├── skills/                   # 技能（可选）
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # 钩子配置（可选）
│   └── hooks.json
├── .mcp.json                # MCP 服务器（可选）
├── scripts/                 # 辅助脚本（可选）
│   └── format-code.sh
└── README.md                # 插件文档

2.2 plugin.json 完整示例

json

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "一个示例插件，展示所有功能",
  "author": {
    "name": "Your Name",
    "email": "your@email.com",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/yourname/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "automation", "workflow"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

2.3 字段说明

字段	必需	类型	说明
name	是	string	插件唯一标识符（kebab-case，无空格）
version	否	string	语义化版本号（如 1.2.0）
description	否	string	简短描述
author	否	object	作者信息
commands	否	string/array	额外命令路径
agents	否	string/array	额外代理路径
hooks	否	string/object	钩子配置路径或内联配置
mcpServers	否	string/object	MCP 配置路径或内联配置

重要：自定义路径是补充默认目录，而非替换。如果 commands/ 目录存在，它会与自定义路径一起加载。

三、创建你的第一个插件

3.1 快速入门

bash

# 1. 创建 Marketplace 结构
mkdir test-marketplace
cd test-marketplace

# 2. 创建插件目录
mkdir my-first-plugin
cd my-first-plugin

# 3. 创建元数据目录和文件
mkdir .claude-plugin

3.2 创建 plugin.json

json

{
  "name": "my-first-plugin",
  "description": "我的第一个 Claude Code 插件",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

3.3 添加一个命令

创建 commands/hello.md：

markdown

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

# Hello 命令

热情地问候用户，询问今天可以如何帮助他们。
让问候语个性化且充满鼓励。

3.4 创建 Marketplace 清单

在 test-marketplace 目录下创建 .claude-plugin/marketplace.json：

json

{
  "name": "test-marketplace",
  "owner": {
    "name": "Test User"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./my-first-plugin",
      "description": "我的测试插件"
    }
  ]
}

3.5 安装和测试

bash

cd ..  # 回到 test-marketplace 目录
claude

# 在 Claude Code 中执行
/plugin marketplace add ./test-marketplace
/plugin install my-first-plugin@test-marketplace
/hello  # 测试你的新命令

四、五大核心组件详解

4.1 Commands（斜杠命令）

斜杠命令是用户主动调用的快捷操作。

文件位置：commands/ 目录

文件格式：带 frontmatter 的 Markdown 文件

markdown

---
description: 自动格式化并提交代码
allowed-tools: Bash, Edit, Write
---

# 代码提交命令

## 执行步骤

1. 运行 prettier --write . 格式化代码
2. 运行 git add . 暂存所有更改
3. 生成简洁的提交信息
4. 执行 git commit

## 提交信息规范

- 使用现在时态
- 50 字符以内的标题
- 说明做了什么和为什么

4.2 Skills（技能）

技能是 Claude 自动识别并使用的能力，无需用户显式调用。

文件位置：skills/技能名/SKILL.md

关键特性：Claude 根据 description 字段自动决定何时使用

yaml

---
name: pdf-processor
description: 从 PDF 文件提取文本、填写表单、合并文档。当处理 PDF 文件、表单或文档提取时使用。
allowed-tools: Read, Bash, Write
---

# PDF 处理技能

## 快速开始

提取文本：

import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()

## 依赖要求

pip install pypdf pdfplumber

description 写作技巧：

错误示例（太模糊）：

yaml

description: 帮助处理文档

正确示例（具体明确）：

yaml

description: 从 PDF 文件提取文本、填写表单、合并文档。当处理 PDF 文件、表单或文档提取时使用。

4.3 Agents（子代理）

子代理是具有专业知识的对话式助手，可以进行多轮交互。

文件位置：agents/ 目录

文件格式：带 frontmatter 的 Markdown 文件

markdown

---
description: 专门进行代码安全审查的代理
capabilities: ["安全漏洞检测", "OWASP Top 10 检查", "敏感数据扫描"]
---

# 安全审查代理

## 职责

我是一个专门的安全审查代理，负责：

- 检测常见安全漏洞
- 识别敏感数据泄露风险
- 提供修复建议

## 审查清单

1. SQL 注入
2. XSS 跨站脚本
3. CSRF 跨站请求伪造
4. 敏感数据暴露
5. 认证/授权问题

## 交互方式

请先提供需要审查的代码或文件路径，我会进行详细分析。

4.4 Hooks（钩子）

钩子是在特定事件发生时自动执行的操作。

文件位置：hooks/hooks.json 或内联在 plugin.json

支持的事件：

事件	触发时机	用途示例
PreToolUse	工具执行前	验证参数、阻止危险操作
PostToolUse	工具执行后	代码格式化、日志记录
UserPromptSubmit	用户提交前	输入验证、上下文注入
SessionStart	会话开始	环境初始化
SessionEnd	会话结束	清理工作
Stop	Claude 结束响应	拦截退出、继续迭代

示例：代码写入后自动格式化

json

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

示例：安全检查钩子

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/security-check.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

4.5 MCP Servers

MCP（Model Context Protocol）服务器用于连接外部工具和数据源。

文件位置：.mcp.json 或内联在 plugin.json

json

{
  "mcpServers": {
    "database-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

重要变量：${CLAUDE_PLUGIN_ROOT} 会被替换为插件安装目录的绝对路径。

五、插件市场 (Marketplace)

5.1 什么是 Marketplace？

Marketplace 是一个 JSON 格式的插件目录，用于集中管理和分发插件。

5.2 marketplace.json 结构

json

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "team@company.com"
  },
  "metadata": {
    "description": "公司开发工具集",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "自动代码格式化",
      "version": "2.1.0"
    },
    {
      "name": "github-plugin",
      "source": {
        "source": "github",
        "repo": "owner/plugin-repo"
      },
      "description": "来自 GitHub 的插件"
    }
  ]
}

5.3 插件来源类型

来源类型	配置方式	示例
本地路径	相对路径字符串	"./plugins/my-plugin"
GitHub	source 对象
Git URL	source 对象	{"source": "url", "url": "https://gitlab.com/..."}

5.4 常用 Marketplace 命令

bash

# 添加 Marketplace
/plugin marketplace add owner/repo              # GitHub
/plugin marketplace add https://gitlab.com/...  # Git URL
/plugin marketplace add ./local-marketplace     # 本地路径

# 管理 Marketplace
/plugin marketplace list                        # 列出所有
/plugin marketplace update marketplace-name     # 更新
/plugin marketplace remove marketplace-name     # 移除

# 安装插件
/plugin install plugin-name@marketplace-name

# 启用/禁用插件
/plugin enable plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

六、团队协作配置

6.1 项目级自动安装

在项目根目录的 .claude/settings.json 中配置：

json

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

团队成员只需信任该项目文件夹，插件就会自动安装。

6.2 推荐的团队工作流

创建组织级 Marketplace 仓库
添加通用插件（代码审查、测试、部署等）
团队成员一次性添加：/plugin marketplace add your-org/claude-plugins
版本控制：使用语义化版本管理插件更新

七、官方插件示例

Anthropic 官方提供了多个示例插件，位于 github.com/anthropics/claude-code/tree/main/plugins：

插件名	功能	包含组件
code-review	自动化 PR 代码审查	命令 + 5 个并行代理
commit-commands	Git 工作流自动化	/commit, /commit-push-pr
feature-dev	7 阶段功能开发流程	命令 + 3 个代理
frontend-design	前端设计指导	技能
plugin-dev	插件开发工具包	命令 + 代理 + 技能
security-guidance	安全提醒钩子	钩子（监控 9 种安全模式）
hookify	自定义钩子创建	命令 + 代理 + 技能

八、最佳实践

8.1 设计原则

避免模糊指令 - 具体的指令产生更好的输出
处理边缘情况 - 测试大文件、语法错误、空文件
遵守 Token 限制 - 命令 <200 tokens，代理 <500 tokens
实现安全护栏 - 危险操作需要明确确认

8.2 命令设计技巧

糟糕的命令：

text

分析代码

好的命令：

text

审查内存泄漏、竞态条件和未处理的 Promise rejection

8.3 调试技巧

bash

# 启用调试模式
claude --debug

调试输出显示：

正在加载哪些插件
插件清单中的错误
命令、代理和钩子的注册情况
MCP 服务器初始化状态

8.4 常见问题排查

问题	可能原因	解决方案
插件未加载	plugin.json 无效	验证 JSON 语法
命令不显示	目录结构错误	确保 commands/ 在根目录
钩子不触发	脚本无执行权限	运行 chmod +x script.sh
MCP 服务器失败	路径错误	使用 ${CLAUDE_PLUGIN_ROOT} 变量

九、社区资源

9.1 官方资源

官方文档 - 完整的插件开发指南
官方博客 - 插件功能介绍
官方插件仓库 - 示例插件

9.2 社区资源

claude-code-plugins-plus - 社区插件集合（185+ 插件）
claude-plugins.dev - 插件 CLI 管理工具
Claude Code Marketplace - 社区 Marketplace

9.3 学习资源

Agnost AI 插件指南 - 详细开发教程
Repomix 插件文档 - 使用指南

十、总结

Claude Code 插件系统是一个强大而灵活的扩展框架，让你能够：

定制化 - 根据团队需求创建专属工具
标准化 - 在项目间统一开发规范
自动化 - 通过钩子实现工作流自动化
协作化 - 通过 Marketplace 共享最佳实践

从一个简单的命令开始，逐步探索技能、代理和钩子的强大功能，你会发现 Claude Code 的无限可能！

本文档基于 Claude Code 官方文档及社区资源整理，版本 2025.12

2.5 Claude Code 插件系统完全指南 ​

一、什么是 Claude Code 插件？ ​

1.1 插件包含的组件 ​

1.2 Commands vs Skills vs Agents ​

二、插件目录结构 ​

2.1 标准目录布局 ​

2.2 plugin.json 完整示例 ​

2.3 字段说明 ​

三、创建你的第一个插件 ​

3.1 快速入门 ​

3.2 创建 plugin.json ​

3.3 添加一个命令 ​

3.4 创建 Marketplace 清单 ​

3.5 安装和测试 ​

四、五大核心组件详解 ​

4.1 Commands（斜杠命令） ​

4.2 Skills（技能） ​

4.3 Agents（子代理） ​

4.4 Hooks（钩子） ​

4.5 MCP Servers ​

五、插件市场 (Marketplace) ​

5.1 什么是 Marketplace？ ​

5.2 marketplace.json 结构 ​

5.3 插件来源类型 ​

5.4 常用 Marketplace 命令 ​

六、团队协作配置 ​

6.1 项目级自动安装 ​

6.2 推荐的团队工作流 ​

七、官方插件示例 ​

八、最佳实践 ​

8.1 设计原则 ​

8.2 命令设计技巧 ​

8.3 调试技巧 ​

8.4 常见问题排查 ​

九、社区资源 ​

9.1 官方资源 ​

9.2 社区资源 ​

9.3 学习资源 ​

十、总结 ​

2.5 Claude Code 插件系统完全指南

一、什么是 Claude Code 插件？

1.1 插件包含的组件

1.2 Commands vs Skills vs Agents

二、插件目录结构

2.1 标准目录布局

2.2 plugin.json 完整示例

2.3 字段说明

三、创建你的第一个插件

3.1 快速入门

3.2 创建 plugin.json

3.3 添加一个命令

3.4 创建 Marketplace 清单

3.5 安装和测试

四、五大核心组件详解

4.1 Commands（斜杠命令）

4.2 Skills（技能）

4.3 Agents（子代理）

4.4 Hooks（钩子）

4.5 MCP Servers

五、插件市场 (Marketplace)

5.1 什么是 Marketplace？

5.2 marketplace.json 结构

5.3 插件来源类型

5.4 常用 Marketplace 命令

六、团队协作配置

6.1 项目级自动安装

6.2 推荐的团队工作流

七、官方插件示例

八、最佳实践

8.1 设计原则

8.2 命令设计技巧

8.3 调试技巧

8.4 常见问题排查

九、社区资源

9.1 官方资源

9.2 社区资源

9.3 学习资源

十、总结