# Claude Code 插件（Plugins）指南

## 概述

插件是 Claude Code 的扩展功能系统，允许用户通过自定义命令、代理、钩子、技能和 MCP 服务器来扩展平台功能。插件可以在项目和团队之间共享，是分发 Claude Code 扩展的标准方式。

## 插件目录结构

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必需：插件元数据
├── commands/                 # 可选：自定义斜杠命令
│   └── hello.md
├── agents/                   # 可选：自定义代理
│   └── helper.md
├── skills/                   # 可选：Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # 可选：事件处理器
│   └── hooks.json
└── .mcp.json                 # 可选：MCP 服务器配置
```

## 插件组件说明

| 组件 | 功能 | 位置 |
|------|------|------|
| **Commands** | 自定义斜杠命令 | `commands/*.md` |
| **Agents** | 专门的代理（显示在 `/agents`） | `agents/*.md` |
| **Skills** | 扩展 Claude 能力（模型自动调用） | `skills/skill-name/SKILL.md` |
| **Hooks** | 事件处理和自动化 | `hooks/hooks.json` |
| **MCP** | 外部工具集成 | `.mcp.json` |

## 快速开始：创建第一个插件

### 步骤1：创建目录结构

```bash
# 创建插件目录
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/commands
mkdir -p my-first-plugin/skills/greeting-skill
```

### 步骤2：创建插件清单

```bash
cat > my-first-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-first-plugin",
  "description": "一个简单的问候插件，用于学习基础知识",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}
EOF
```

### 步骤3：添加自定义命令

```bash
cat > my-first-plugin/commands/hello.md << 'EOF'
---
description: 用个性化消息问候用户
argument-hint: [用户名]
---

# 问候命令

热情地问候用户 $ARGUMENTS，并询问今天有什么可以帮助的。让问候变得个性化和鼓励性。
EOF
```

### 步骤4：添加技能

```bash
cat > my-first-plugin/skills/greeting-skill/SKILL.md << 'EOF'
---
name: greeting-skill
description: 生成友好的问候语。当用户需要问候模板或社交礼仪建议时使用。
---

# 问候技能

## 说明

根据场景生成合适的问候语：
- 正式场合
- 非正式场合
- 电子邮件开头
- 即时消息
EOF
```

## plugin.json 配置详解

### 基本配置

```json
{
  "name": "plugin-name",
  "description": "插件功能描述",
  "version": "1.0.0",
  "author": {
    "name": "作者名称",
    "email": "author@example.com"
  }
}
```

### 完整配置示例

```json
{
  "name": "enterprise-tools",
  "description": "企业级工作流自动化工具",
  "version": "2.1.0",
  "author": {
    "name": "企业团队",
    "email": "team@company.com"
  },
  "homepage": "https://docs.company.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"]
}
```

### 配置字段说明

| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | 插件标识符（kebab-case 格式） |
| `description` | 否 | 插件功能简述 |
| `version` | 否 | 语义化版本号 |
| `author` | 否 | 作者信息对象（含 `name` 字段） |
| `homepage` | 否 | 文档或主页 URL |
| `repository` | 否 | 源代码仓库 URL |
| `license` | 否 | 许可证类型 |
| `keywords` | 否 | 关键词数组 |

## 安装和管理插件

### 安装插件

```bash
# 通过交互菜单浏览
/plugin

# 从市场直接安装
/plugin install formatter@your-org

# 从本地市场安装
/plugin install my-first-plugin@test-marketplace
```

### 管理已安装插件

```bash
# 启用插件
/plugin enable plugin-name@marketplace-name

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

# 卸载插件
/plugin uninstall plugin-name@marketplace-name
```

### 验证安装

```bash
# 查看新命令是否出现
/help

# 管理插件
/plugin
```

## 本地开发和测试

### 开发工作流

```bash
# 1. 创建开发目录结构
mkdir dev-marketplace
cd dev-marketplace
mkdir my-plugin

# 2. 创建市场清单
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "dev-marketplace",
  "owner": {"name": "Developer"},
  "plugins": [{
    "name": "my-plugin",
    "source": "./my-plugin",
    "description": "开发中的插件"
  }]
}
EOF

# 3. 从父目录启动 Claude Code
claude

# 4. 添加市场
/plugin marketplace add ./dev-marketplace

# 5. 安装插件
/plugin install my-plugin@dev-marketplace
```

### 迭代开发

```bash
# 修改插件代码后，重新安装
/plugin uninstall my-plugin@dev-marketplace
/plugin install my-plugin@dev-marketplace
```

## 高级功能

### 添加钩子（Hooks）

在 `hooks/hooks.json` 中定义事件处理器：

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

> **注意**：`${CLAUDE_PLUGIN_ROOT}` 环境变量指向插件安装目录。

### 添加 MCP 服务器

在插件根目录创建 `.mcp.json`：

```json
{
  "servers": {
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}
```

### 添加自定义代理

在 `agents/` 目录创建代理定义：

```markdown
# agents/code-assistant.md
---
description: 专注于代码质量的智能助手
allowed-tools: Read, Grep, Glob, Edit
---

# 代码助手代理

你是一个专注于代码质量的助手。

## 职责

1. 代码审查
2. 重构建议
3. 最佳实践指导
```

## 完整插件示例

### 示例：代码格式化插件

**目录结构：**
```
code-formatter/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── format.md
│   └── lint.md
├── skills/
│   └── formatting-rules/
│       └── SKILL.md
└── scripts/
    └── prettier-wrapper.sh
```

**plugin.json：**
```json
{
  "name": "code-formatter",
  "description": "自动代码格式化和 lint 检查",
  "version": "1.0.0",
  "author": {
    "name": "DevTools Team"
  },
  "keywords": ["format", "lint", "prettier", "eslint"]
}
```

**commands/format.md：**
```markdown
---
description: 格式化当前文件或目录
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx prettier:*), Read, Write
---

# 格式化命令

格式化指定的文件或目录：$ARGUMENTS

使用项目的 Prettier 配置进行格式化。
```

**commands/lint.md：**
```markdown
---
description: 运行 ESLint 检查
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx eslint:*)
---

# Lint 检查命令

对指定的文件或目录运行 ESLint：$ARGUMENTS

报告所有问题并提供修复建议。
```

**skills/formatting-rules/SKILL.md：**
```yaml
---
name: formatting-rules
description: 了解项目的代码格式化规则。当需要手动格式化代码或解释格式化规则时使用。
---

# 格式化规则

## 常用规则

- 缩进：2 空格
- 分号：必需
- 引号：单引号
- 尾随逗号：ES5 兼容

## 配置文件

检查以下文件了解项目规则：
- `.prettierrc`
- `.eslintrc`
- `package.json` 中的 `prettier` 和 `eslintConfig`
```

## 团队插件配置

在仓库的 `.claude/settings.json` 中配置自动安装：

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

当团队成员信任该仓库后：
- 市场会自动安装
- 通过 `enabledPlugins` 字段指定的插件会自动安装

## 调试和验证

### 调试技巧

1. **检查结构**：确保目录在插件根目录，而非 `.claude-plugin/` 内部
2. **单独测试**：分别检查每个命令、代理和钩子
3. **使用验证工具**：参见插件参考文档了解 CLI 调试命令
4. **验证安装**：运行 `/help` 查看新命令是否列出

### 检查清单

- [ ] `.claude-plugin/plugin.json` 存在且格式正确
- [ ] 组件目录（commands/、skills/ 等）在插件根目录
- [ ] 命令文件为 `.md` 格式
- [ ] 技能目录包含 `SKILL.md` 文件
- [ ] YAML frontmatter 语法正确

### 常见问题

**命令不显示：**
- 检查文件扩展名是否为 `.md`
- 验证 frontmatter 格式正确
- 重启 Claude Code

**技能不激活：**
- 检查 `description` 是否足够具体
- 验证 `SKILL.md` 路径正确

## 分享插件前的准备

在分发插件之前：
- 添加 `README.md` 包含安装和使用说明
- 在 `plugin.json` 中使用语义化版本号
- 创建或使用市场进行分发
- 在更广泛发布前与他人测试

## 相关资源

- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
- [Skills 技能指南](./02-技能指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：插件系统](https://code.claude.com/docs/en/plugins)
- [官方文档：子代理](https://code.claude.com/docs/en/sub-agents)
- [官方文档：钩子](https://code.claude.com/docs/en/hooks)
- [官方文档：MCP](https://code.claude.com/docs/en/mcp)