agent-aide/guide/03-插件指南.md

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：创建目录结构

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

步骤2：创建插件清单

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

步骤3：添加自定义命令

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

# 问候命令

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

步骤4：添加技能

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

# 问候技能

## 说明

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

plugin.json 配置详解

基本配置

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

完整配置示例

{
  "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	否	关键词数组

安装和管理插件

安装插件

# 通过交互菜单浏览
/plugin

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

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

管理已安装插件

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

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

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

验证安装

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

# 管理插件
/plugin

本地开发和测试

开发工作流

# 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

迭代开发

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

高级功能

添加钩子（Hooks）

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

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

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

添加 MCP 服务器

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

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

添加自定义代理

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

# 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：

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

commands/format.md：

---
description: 格式化当前文件或目录
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx prettier:*), Read, Write
---

# 格式化命令

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

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

commands/lint.md：

---
description: 运行 ESLint 检查
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx eslint:*)
---

# Lint 检查命令

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

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

skills/formatting-rules/SKILL.md：

---
name: formatting-rules
description: 了解项目的代码格式化规则。当需要手动格式化代码或解释格式化规则时使用。
---

# 格式化规则

## 常用规则

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

## 配置文件

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

团队插件配置

在仓库的 .claude/settings.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 中使用语义化版本号
• 创建或使用市场进行分发
• 在更广泛发布前与他人测试

相关资源

• 自定义斜杠命令指南
• Skills 技能指南
• Plugin Marketplaces 插件市场指南
• 官方文档：插件系统
• 官方文档：子代理
• 官方文档：钩子
• 官方文档：MCP