自定义插件开发

Claude Code最强大的功能就是插件系统。

开发自定义插件能把团队工作流程、编码规范、最佳实践封装成可重用组件,大幅提升开发效率。

今天带你从零开始掌握Claude Code插件开发。

什么是Claude Code插件

Claude Code插件是一种打包分发自定义功能的方式,类似于VS Code扩展或Chrome插件。一个插件可以包含:

• Slash命令(斜杠命令): 快速执行的快捷指令
• SubAgent(子代理): 专注于特定任务的AI助手
• MCP服务器: Model Context Protocol集成,连接外部数据源
• Hooks(钩子): 在特定事件触发时自动执行的脚本

插件的价值

1. 知识封装 把复杂工作流程、编码规范封装成插件,新成员安装后就能获得最佳实践

2. 团队协作 通过Git共享插件,确保团队用统一的工具和规范

3. 效率提升 一键执行复杂任务,减少重复劳动

4. 可扩展性 无缝集成外部工具和服务(Jira、GitHub、Slack等)

插件开发环境搭建

前置要求

在开始之前,确保你已经:

1. 安装了Claude Code CLI
2. 熟悉基本的命令行操作
3. 了解Node.js和npm(用于某些高级插件)
4. 有一个用于测试的项目目录

安装Claude Code

# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash

# 验证安装
claude --version

创建测试项目

# 创建插件开发测试目录
mkdir claude-plugin-dev
cd claude-plugin-dev

# 初始化项目
npm init -y

# 创建基本的项目结构
mkdir -p src/components
mkdir -p src/utils
mkdir -p tests

插件目录结构

一个标准的Claude Code插件项目结构如下:

my-claude-plugin/
├── .claude/                 # Claude配置目录
│   ├── plugin.json         # 插件清单文件
│   ├── commands/           # Slash命令定义
│   │   ├── deploy.md
│   │   └── test.md
│   ├── agents/             # SubAgent定义
│   │   └── code-reviewer.md
│   └── hooks/              # Hooks脚本
│       └── pre-commit.sh
├── README.md               # 插件说明文档
└── package.json            # 如果需要npm依赖

创建你的第一个插件

第一步:创建插件清单文件

在项目根目录创建.claude/plugin.json:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "我的第一个Claude Code插件",
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  "claude": {
    "minVersion": "1.0.0"
  },
  "commands": [
    {
      "name": "hello",
      "description": "打招呼命令",
      "file": "commands/hello.md"
    }
  ],
  "agents": [],
  "hooks": {}
}

第二步:创建Slash命令

创建.claude/commands/hello.md:

---
description: 向用户打招呼并显示项目信息
---

# Hello命令

欢迎使用Claude Code插件!

请执行以下操作:
1. 读取项目的package.json文件
2. 显示项目名称和版本
3. 打印一条友好的欢迎消息

示例输出格式:

👋 你好!

项目: [项目名称] 版本: [版本号] 当前目录: [当前工作目录]

祝你编码愉快! 🚀

第三步:测试插件

# 在项目目录启动Claude Code
claude

# 使用你的自定义命令
/hello

预期输出:

👋 你好!

项目: my-first-plugin
版本: 1.0.0
当前目录: /Users/username/claude-plugin-dev

祝你编码愉快! 🚀

恭喜!你已经成功创建了第一个Claude Code插件。

Slash命令开发

Slash命令是插件中最常用的组件,它允许你通过简短的指令执行复杂任务。

命令文件结构

一个完整的Slash命令文件包含YAML frontmatter和Markdown内容:

---
description: 命令的简短描述
usage: 命令的使用示例(可选)
parameters:  # 可选的参数定义
  - name: param1
    description: 参数1的说明
    required: true
tags:  # 可选的标签
  - deployment
  - testing
---

# 命令标题

这里是命令的详细说明和执行逻辑...

实战示例1:代码部署命令

创建.claude/commands/deploy.md:

---
description: 自动化部署流程
usage: /deploy [环境]
parameters:
  - name: 环境
    description: 部署目标环境(dev/staging/prod)
    required: false
tags:
  - deployment
  - automation
---

# 部署命令

执行以下部署流程:

## 1. 环境检查
- 检查Git工作区是否干净
- 检查当前分支
- 验证环境变量

## 2. 测试
- 运行单元测试: `npm test`
- 运行linting: `npm run lint`
- 构建项目: `npm run build`

## 3. 部署
根据指定环境执行部署:

**开发环境** (默认):
```bash
npm run deploy:dev

预发布环境:

npm run deploy:staging

生产环境:

npm run deploy:prod

4. 验证

• 检查部署状态
• 运行冒烟测试
• 发送通知

注意事项

⚠️ 生产环境部署需要额外确认 ⚠️ 部署前确保所有测试通过 ⚠️ 记录部署日志用于回滚

**使用示例:**

```bash
# 部署到开发环境
/deploy

# 部署到生产环境
/deploy prod

实战示例2:数据库迁移命令

创建.claude/commands/migrate.md:

---
description: 数据库迁移管理工具
usage: /migrate [action] [options]
parameters:
  - name: action
    description: 操作类型(create/up/down/status)
    required: true
  - name: options
    description: 额外选项
    required: false
---

# 数据库迁移命令

## 使用方法

### 创建新迁移
```bash
/migrate create add_users_table

执行:

1. 生成迁移文件
2. 添加时间戳
3. 打开编辑器供你编辑迁移内容

执行迁移

/migrate up

执行:

1. 检查待执行的迁移
2. 显示迁移预览
3. 要求确认
4. 执行迁移
5. 更新数据库版本

回滚迁移

/migrate down

执行:

1. 显示最近一次迁移
2. 要求确认
3. 执行回滚
4. 更新数据库版本

查看状态

/migrate status

显示:

• 当前数据库版本
• 待执行的迁移
• 已执行的迁移历史

安全检查

执行迁移前自动检查:

• 数据库连接正常
• 备份已完成(生产环境)
• 有足够的磁盘空间
• 没有长时间运行的查询

错误处理

如果迁移失败:

1. 回滚所有更改
2. 显示详细错误信息
3. 保存日志到文件
4. 提供修复建议

### 实战示例3:代码审查命令

创建`.claude/commands/review.md`:

```markdown
---
description: 智能代码审查助手
usage: /review [文件路径或分支]
tags:
  - code-quality
  - best-practices
---

# 代码审查命令

## 审查流程

### 1. 收集信息
- 如果指定了文件路径,审查该文件
- 如果指定了分支,审查与main的差异
- 如果没有参数,审查当前所有更改

### 2. 审查维度

**代码质量:**
- [ ] 代码可读性
- [ ] 命名规范
- [ ] 代码复杂度
- [ ] 重复代码

**最佳实践:**
- [ ] 设计模式应用
- [ ] 错误处理
- [ ] 资源管理
- [ ] 性能考虑

**安全性:**
- [ ] SQL注入风险
- [ ] XSS漏洞
- [ ] 敏感信息泄露
- [ ] 权限检查

**测试:**
- [ ] 单元测试覆盖
- [ ] 边界条件
- [ ] 错误场景

### 3. 输出格式

```markdown
## 代码审查报告

### 总体评分: ⭐⭐⭐⭐☆ (4/5)

### 发现的问题

#### 🔴 严重问题(1)
1. **SQL注入风险** - `src/user.js:45`
   - 使用字符串拼接构建SQL查询
   - 建议:使用参数化查询

#### 🟡 警告(2)
1. **缺少错误处理** - `src/api.js:23`
2. **未使用的变量** - `src/utils.js:12`

#### 🟢 建议(3)
1. 可以使用可选链简化代码
2. 建议提取常量
3. 添加JSDoc注释

### 优点
✅ 良好的代码组织
✅ 适当的注释
✅ 一致的代码风格

### 改进建议
- 增加单元测试覆盖率到80%以上
- 使用ESLint规则自动检测问题
- 添加pre-commit hook

4. 自动修复

对于简单的问题(如格式化、未使用导入),自动修复:

eslint --fix [文件]

5. 生成报告

将审查报告保存到文件:

/review > code-review-$(date +%Y%m%d).md

## SubAgent开发

SubAgent是专注于特定任务的AI代理,它们拥有专门的指令集,可以处理特定领域的复杂任务。

### SubAgent基本结构

创建`.claude/agents/code-reviewer.md`:

```markdown
---
name: code-reviewer
description: 专业代码审查代理
version: 1.0.0
---

# 代码审查专家

你是一位资深的代码审查专家,拥有15年软件工程经验。

## 你的专长
- 多种编程语言(Python, JavaScript, TypeScript, Java, Go)
- 代码质量最佳实践
- 安全漏洞检测
- 性能优化
- 设计模式
- Clean Code原则

## 审查原则
1. **建设性反馈**: 指出问题的同时提供解决方案
2. **上下文感知**: 考虑项目的编码规范和团队习惯
3. **优先级排序**: 优先标记严重问题和安全隐患
4. **教育导向**: 解释为什么某个做法有问题,帮助开发者成长

## 审查流程

### 第一阶段:快速扫描
1. 检查明显的语法错误
2. 识别代码异味(code smells)
3. 标注潜在的安全问题

### 第二阶段:深度分析
1. 分析代码复杂度
2. 评估性能影响
3. 检查错误处理
4. 验证边界条件

### 第三阶段:建议优化
1. 提出重构建议
2. 推荐最佳实践
3. 建议测试策略
4. 文档改进建议

## 输出格式

始终使用结构化的审查报告:

```markdown
## 📊 代码审查报告

**文件**: [文件路径]
**作者**: [提交者]
**日期**: [审查日期]

### 🎯 总体评估
- 代码质量: ⭐⭐⭐⭐☆
- 可维护性: ⭐⭐⭐☆☆
- 安全性: ⭐⭐⭐⭐☆
- 性能: ⭐⭐⭐⭐☆

### 🔴 必须修复的问题
...

### 🟡 建议改进
...

### 🟢 优点
...

### 📚 学习资源
...

特殊关注点

安全问题

• SQL注入
• XSS攻击
• CSRF保护
• 敏感数据泄露
• 认证/授权缺陷

性能问题

• N+1查询
• 内存泄漏
• 不必要的循环
• 缺少缓存
• 大文件处理

可维护性

• 代码重复
• 过长函数
• 深层嵌套
• 魔法数字
• 缺少注释

交互风格

• 使用友好、鼓励的语气
• 提供具体的代码示例
• 解释"为什么"而不仅仅是"是什么"
• 承认代码的好的部分
• 在批评之前先理解上下文

### 调用SubAgent

在Claude Code中,你可以这样调用SubAgent:

```bash
# 让code-reviewer代理审查文件
@code-reviewer 请审查 src/user.js 文件

# 审查整个PR
@code-reviewer 请审查 feature/new-auth 分支的所有更改

# 针对性审查
@code-reviewer 请关注安全性问题,审查 src/auth/ 目录

实战示例:性能优化专家

创建.claude/agents/performance-expert.md:

---
name: performance-expert
description: 性能优化专家代理
version: 1.0.0
---

# 性能优化专家

你是一位性能优化专家,擅长识别和解决各种性能瓶颈。

## 专长领域
- 前端性能(渲染优化、资源加载)
- 后端性能(API响应时间、数据库查询)
- 算法优化(时间复杂度、空间复杂度)
- 缓存策略(浏览器缓存、CDN、Redis)
- 并发处理(异步操作、线程池)

## 分析框架

### 前端性能
```javascript
// 检查清单
1. 资源加载
   - [ ] 图片懒加载
   - [ ] 代码分割
   - [ ] Tree shaking
   - [ ] Gzip压缩

2. 渲染优化
   - [ ] 虚拟滚动(长列表)
   - [ ] 防抖/节流
   - [ ] 避免强制同步布局
   - [ ] 使用CSS transforms动画

3. 内存管理
   - [ ] 事件监听器清理
   - [ ] 定时器清除
   - [ ] 避免内存泄漏

后端性能

// 检查清单
1. 数据库优化
   - [ ] 索引优化
   - [ ] 查询优化(避免N+1)
   - [ ] 连接池配置
   - [ ] 慢查询监控

2. 缓存策略
   - [ ] Redis缓存热点数据
   - [ ] CDN缓存静态资源
   - [ ] 浏览器缓存策略
   - [ ] 查询结果缓存

3. 并发处理
   - [ ] 异步I/O
   - [ ] 线程池/协程池
   - [ ] 批量处理
   - [ ] 请求合并

算法优化

// 分析维度
1. 时间复杂度
   - O(1): 哈希表查找
   - O(log n): 二分查找
   - O(n): 线性遍历
   - O(n log n): 排序算法
   - O(n²): 嵌套循环(需要优化)

2. 空间复杂度
   - 避免不必要的数据复制
   - 使用生成器处理大数据
   - 及时释放大对象

性能分析流程

步骤1:性能剖析

运行性能分析工具:

# Node.js
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# 前端
# 使用Chrome DevTools Performance面板

# 数据库
EXPLAIN ANALYZE [查询]

步骤2:瓶颈识别

找出:

• 最慢的函数/方法
• 最耗时的查询
• 频繁调用的代码
• 内存占用高的地方

步骤3:优化实施

按优先级实施优化:

1. 高优先级:影响大,改动小
2. 中优先级:影响中等,改动中等
3. 低优先级:影响小,改动大

步骤4:效果验证

对比优化前后的性能指标:

• 响应时间
• 吞吐量
• 内存使用
• CPU使用率

常见优化模式

模式1:缓存结果

// 优化前
function getUser(id) {
  return database.query(`SELECT * FROM users WHERE id = ${id}`);
}

// 优化后
const cache = new Map();
function getUser(id) {
  if (cache.has(id)) {
    return cache.get(id);
  }
  const user = database.query(`SELECT * FROM users WHERE id = ${id}`);
  cache.set(id, user);
  return user;
}

模式2:批量处理

// 优化前
for (const id of userIds) {
  const user = await getUser(id);
  // 处理用户
}

// 优化后
const users = await getUsers(userIds); // 批量查询
for (const user of users) {
  // 处理用户
}

模式3:惰性加载

// 优化前
const data = loadHugeData(); // 启动时加载所有数据

// 优化后
function getData() {
  if (!data) {
    data = loadHugeData(); // 首次使用时才加载
  }
  return data;
}

输出格式

## 🚀 性能优化报告

### 📊 当前性能指标
- API响应时间: 850ms
- 数据库查询时间: 620ms
- 内存使用: 512MB
- CPU使用率: 75%

### 🔍 发现的瓶颈

#### 🔴 严重瓶颈(2)
1. **N+1查询问题** - `UserService.js:45`
   - 影响:每次请求执行1000次数据库查询
   - 建议:使用JOIN或批量查询
   - 预期提升:响应时间减少80%

2. **缺少缓存** - `ProductController.js:23`
   - 影响:热门商品每次都查询数据库
   - 建议:使用Redis缓存,设置5分钟过期
   - 预期提升:数据库负载降低90%

#### 🟡 中等瓶颈(3)
...

### ✅ 优化建议(按优先级排序)

#### 优先级1:解决N+1查询
```javascript
// 当前代码
for (const orderId of orders) {
  const items = await db.query(
    `SELECT * FROM items WHERE order_id = ${orderId}`
  );
}

// 优化后
const items = await db.query(`
  SELECT * FROM items
  WHERE order_id IN (${orders.join(',')})
`);

预期提升:响应时间从850ms降至170ms

优先级2:添加Redis缓存

...

📈 预期收益

实施所有高优先级优化后:

• API响应时间: 850ms → 170ms (减少80%)
• 数据库查询: 1000次 → 2次 (减少99.8%)
• 吞吐量: 12 req/s → 60 req/s (增加400%)

🔄 持续监控

建议设置以下监控指标:

• p50/p95/p99响应时间
• 错误率
• 数据库连接池使用率
• Redis缓存命中率

## 性能测试命令

```bash
# API性能测试
ab -n 1000 -c 10 http://localhost:3000/api/users

# 数据库性能测试
pgbench -c 10 -j 2 -t 1000 mydb

# 前端性能测试
lighthouse http://localhost:3000 --view

## Hooks开发

Hooks允许你在特定事件发生时自动执行脚本,实现自动化工作流。

### Hooks类型

Claude Code支持以下Hooks:

| Hook名称 | 触发时机 | 用途示例 |
|---------|---------|---------|
| `pre-commit` | Git提交前 | 运行测试、lint检查 |
| `post-commit` | Git提交后 | 发送通知、更新文档 |
| `pre-push` | Git推送前 | 运行完整测试套件 |
| `post-push` | Git推送后 | 通知团队、部署 |
| `pre-edit` | 文件编辑前 | 备份文件 |
| `post-edit` | 文件编辑后 | 格式化代码 |
| `on-error` | 命令失败时 | 记录错误、发送告警 |

### 创建Hook:pre-commit

创建`.claude/hooks/pre-commit.sh`:

```bash
#!/bin/bash
# Pre-commit hook: 在提交前自动检查代码质量

set -e  # 遇到错误立即退出

echo "🔍 运行pre-commit检查..."

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 1. 检查是否有未完成的TODO
echo "📝 检查TODO注释..."
if git diff --cached | grep -i "TODO" > /dev/null; then
    echo -e "${YELLOW}⚠️  警告: 代码中包含TODO注释${NC}"
    echo "请确认是否继续提交"
    read -p "按Enter继续,Ctrl+C取消"
fi

# 2. 运行ESLint
echo "🔎 运行ESLint..."
if command -v eslint &> /dev/null; then
    # 只检查暂存的文件
    FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.js$\|\.jsx$' || true)
    if [ -n "$FILES" ]; then
        eslint $FILES
        echo -e "${GREEN}✅ ESLint检查通过${NC}"
    fi
fi

# 3. 运行TypeScript类型检查
echo "🔬 运行TypeScript类型检查..."
if command -v tsc &> /dev/null; then
    tsc --noEmit
    echo -e "${GREEN}✅ TypeScript类型检查通过${NC}"
fi

# 4. 运行单元测试
echo "🧪 运行单元测试..."
if [ -f "package.json" ] && grep -q "test" package.json; then
    npm test -- --passWithNoTests
    echo -e "${GREEN}✅ 测试通过${NC}"
fi

# 5. 检查文件大小
echo "📏 检查文件大小..."
MAX_SIZE=102400  # 100KB
FILES=$(git diff --cached --name-only | grep '\.js$\|\.jsx$\|\.ts$\|\.tsx$' || true)
for FILE in $FILES; do
    if [ -f "$FILE" ]; then
        SIZE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE" 2>/dev/null || echo 0)
        if [ $SIZE -gt $MAX_SIZE ]; then
            echo -e "${YELLOW}⚠️  警告: $FILE 文件大小超过100KB${NC}"
        fi
    fi
done

# 6. 检查敏感信息
echo "🔒 检查敏感信息..."
SENSITIVE_PATTERNS=(
    "password.*=.*['\"].*['\"]"
    "api_key.*=.*['\"].*['\"]"
    "secret.*=.*['\"].*['\"]"
    "token.*=.*['\"].*['\"]"
)

for PATTERN in "${SENSITIVE_PATTERNS[@]}"; do
    if git diff --cached | grep -iE "$PATTERN" > /dev/null; then
        echo -e "${RED}❌ 错误: 检测到可能的敏感信息!${NC}"
        echo "请移除密码、API密钥等敏感信息"
        exit 1
    fi
done

echo -e "${GREEN}✨ 所有检查通过!${NC}"
exit 0

设置可执行权限:

chmod +x .claude/hooks/pre-commit.sh

创建Hook:post-commit

创建.claude/hooks/post-commit.sh:

#!/bin/bash
# Post-commit hook: 提交后执行的操作

echo "📝 提交完成!执行post-commit操作..."

# 1. 显示提交信息
echo "📄 最新提交:"
git log -1 --pretty=format:"%h - %s (%an, %ar)" HEAD

# 2. 统计本次提交
echo "📊 提交统计:"
git diff --stat HEAD~1 HEAD

# 3. 更新CHANGELOG(可选)
if command -v conventional-changelog &> /dev/null; then
    echo "📝 更新CHANGELOG..."
    conventional-changelog -p angular -i CHANGELOG.md -s
    git add CHANGELOG.md
fi

# 4. 发送桌面通知(仅macOS)
if [[ "$OSTYPE" == "darwin"* ]]; then
    commit_msg=$(git log -1 --pretty=%s HEAD)
    terminal-notifier -title "Git提交成功" -message "$commit_msg" 2>/dev/null || true
fi

# 5. 记录提交日志
LOG_FILE=".claude/commits.log"
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $(git log -1 --pretty=%H HEAD)" >> $LOG_FILE

echo "✅ Post-commit操作完成"

创建Hook:on-error

创建.claude/hooks/on-error.sh:

#!/bin/bash
# On-error hook: 当命令失败时执行

echo "❌ 检测到错误!执行错误处理..."

ERROR_LOG=".claude/errors.log"
ERROR_TIME=$(date '+%Y-%m-%d %H:%M:%S')

# 记录错误
echo "[$ERROR_TIME] 命令失败" >> $ERROR_LOG
echo "工作目录: $(pwd)" >> $ERROR_LOG
echo "Git状态:" >> $ERROR_LOG
git status -s >> $ERROR_LOG
echo "---" >> $ERROR_LOG

# 发送通知
if command -v terminal-notifier &> /dev/null; then
    terminal-notifier -title "Claude Code错误" \
                      -message "命令执行失败,请检查日志" \
                      -sound default 2>/dev/null || true
fi

# 自动创建问题报告
REPORT_FILE=".claude/error-report-$(date +%Y%m%d-%H%M%S).md"
cat > $REPORT_FILE << EOF
# 错误报告

**时间**: $ERROR_TIME
**项目**: $(basename $(pwd))
**分支**: $(git branch --show-current)

## 环境信息
\`\`\`
Node.js: $(node --version 2>/dev/null || echo "未安装")
npm: $(npm --version 2>/dev/null || echo "未安装")
OS: $(uname -s) $(uname -r)
\`\`\`

## Git状态
\`\`\`
$(git status -s)
\`\`\`

## 最近提交
\`\`\`
$(git log -3 --oneline)
\`\`\`

## 系统日志
请查看: \`$ERROR_LOG\`

## 下一步
1. 检查错误日志
2. 查看Git状态
3. 尝试撤销操作: \`git reset --soft HEAD~1\`
EOF

echo "📄 错误报告已生成: $REPORT_FILE"

注册Hooks

在plugin.json中注册hooks:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "hooks": {
    "pre-commit": ".claude/hooks/pre-commit.sh",
    "post-commit": ".claude/hooks/post-commit.sh",
    "on-error": ".claude/hooks/on-error.sh"
  }
}

插件调试技巧

1. 启用调试模式

# 启动Claude Code时启用详细日志
CLAUDE_DEBUG=1 claude

# 或者设置环境变量
export CLAUDE_DEBUG=1
claude

2. 测试单个命令

# 直接测试命令文件
claude --command .claude/commands/deploy.md

# 查看命令解析结果
claude --parse .claude/commands/deploy.md

3. 验证插件清单

# 验证plugin.json语法
cat .claude/plugin.json | jq .

# 检查插件完整性
claude --validate-plugin

4. 调试Hooks

# 手动运行hook测试
.claude/hooks/pre-commit.sh

# 查看hook输出
bash -x .claude/hooks/pre-commit.sh

# 测试hook是否被调用
echo "测试pre-commit" > test.txt
git add test.txt
git commit -m "test"  # 应该触发pre-commit hook

5. 查看日志

# Claude Code日志位置
~/.claude/logs/

# 查看最新日志
tail -f ~/.claude/logs/claude-code.log

# 搜索错误
grep "ERROR" ~/.claude/logs/claude-code.log

6. 使用调试输出

在命令文件中添加调试信息:

---
description: 调试示例命令
---

# 调试命令

## 调试信息
当前时间: \`$(date)\`
当前目录: \`$(pwd)\`
用户: \`$(whoami)\`

## 执行步骤
1. 第一步...
2. 第二步...

---
**调试提示**: 查看详细日志请运行 \`tail -f ~/.claude/logs/*.log\`
---

插件发布和分享

1. 准备发布

完善README.md:

# My Claude Code Plugin

## 简介
这个插件提供了XXX功能,帮助您...

## 安装

\`\`\`bash
# 方法1: 从GitHub安装
claude plugin install username/my-claude-plugin

# 方法2: 从本地安装
claude plugin install ./my-claude-plugin

# 方法3: 从URL安装
claude plugin install https://github.com/username/my-claude-plugin
\`\`\`

## 功能

### 命令
- \`/hello\`: 打招呼
- \`/deploy\`: 部署应用
- \`/review\`: 代码审查

### SubAgents
- \`@code-reviewer\`: 代码审查专家
- \`@performance-expert\`: 性能优化专家

### Hooks
- \`pre-commit\`: 提交前检查
- \`post-commit\`: 提交后通知

## 使用示例

\`\`\`bash
# 使用deploy命令
claude
/deploy prod

# 调用code-reviewer
@code-reviewer 请审查 src/user.js
\`\`\`

## 配置

插件支持以下配置选项:

\`\`\`json
{
  "deploy": {
    "defaultEnv": "dev",
    "autoConfirm": false
  },
  "review": {
    "strictMode": true,
    "maxComplexity": 10
  }
}
\`\`\`

## 开发

\`\`\`bash
# 克隆仓库
git clone https://github.com/username/my-claude-plugin.git
cd my-claude-plugin

# 安装依赖
npm install

# 运行测试
npm test

# 本地测试
claude --plugin ./
\`\`\`

## 贡献

欢迎提交Issue和Pull Request!

## 许可证

MIT License

创建CHANGELOG.md:

# 更新日志

## [1.0.0] - 2025-01-15

### 新增
- 添加deploy命令
- 添加review命令
- 添加code-reviewer SubAgent
- 添加pre-commit和post-commit hooks

### 改进
- 优化错误处理
- 改进日志输出

### 修复
- 修复hook权限问题

2. 版本控制

使用语义化版本:

# 主版本.次版本.修订号
1.0.0  # 初始版本
1.1.0  # 添加新功能(向后兼容)
1.1.1  # Bug修复
2.0.0  # 重大变更(不向后兼容)

发布新版本:

# 1. 更新版本号
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# 2. 更新CHANGELOG.md
# 手动添加变更说明

# 3. 提交更改
git add .
git commit -m "chore: release v1.1.0"
git tag v1.1.0
git push origin main --tags

3. 发布到GitHub

# 1. 创建GitHub仓库
gh repo create my-claude-plugin --public --description "My Claude Code Plugin"

# 2. 推送到GitHub
git remote add origin https://github.com/username/my-claude-plugin.git
git push -u origin main

# 3. 创建GitHub Release
gh release create v1.0.0 \
  --title "v1.0.0" \
  --notes "第一个正式版本"

4. 发布到npm(可选)

如果你的插件包含Node.js依赖,可以发布到npm:

# 登录npm
npm login

# 发布包
npm publish

# 查看已发布的包
npm view my-claude-plugin

5. 分享插件

方式1: GitHub链接

# 用户可以通过GitHub链接安装
claude plugin install https://github.com/username/my-claude-plugin

方式2: 直接目录

# 用户克隆后本地安装
git clone https://github.com/username/my-claude-plugin.git
cd my-claude-plugin
claude plugin install ./

方式3: 团队共享

# 将插件放在团队共享的Git仓库中
# 在项目CLAUDE.md中添加安装说明

实用技巧和最佳实践

1. 命令设计原则

好的命令:

• ✅ 名称简短、易记(/deploy, /test)
• ✅ 功能单一、专注
• ✅ 有清晰的描述和用法示例
• ✅ 错误处理完善
• ✅ 提供进度反馈

不好的命令:

• ❌ 名称过长(/deploy-to-production-server)
• ❌ 功能混杂(既部署又测试)
• ❌ 缺少使用说明
• ❌ 静默失败

2. SubAgent设计技巧

明确角色定位:

# ❌ 太宽泛
你是一个全栈开发工程师...

# ✅ 定位清晰
你是一位专注于React性能优化的前端专家...

提供上下文模板:

## 分析模板
1. 收集信息: [具体步骤]
2. 分析问题: [检查清单]
3. 提出方案: [决策树]
4. 验证结果: [测试方法]

结构化输出:

## 📊 分析报告

### 问题诊断
...

### 解决方案
1. 方案A(推荐)
   - 优点:...
   - 缺点:...
   - 适用场景:...

2. 方案B
   - ...

3. Hook最佳实践

快速失败:

#!/bin/bash
set -e  # 遇到错误立即退出
set -u  # 使用未定义变量时报错
set -o pipefail  # 管道命令失败时退出

幂等性:

#!/bin/bash
# ✅ 好的设计: 可以多次运行
npm install  # 如果已安装会跳过

# ❌ 不好的设计: 不能重复运行
rm -rf node_modules
npm install

用户友好:

#!/bin/bash
# 提供清晰的输出
echo "✅ 检查通过"
echo "⚠️  警告: ..."
echo "❌ 错误: ..."

# 允许用户跳过(对于非关键检查)
if [ "$SKIP_TESTS" = "true" ]; then
    echo "跳过测试(用户设置)"
    exit 0
fi

4. 性能优化

缓存结果:

# 使用缓存避免重复计算
\`\`\`bash
# 检查缓存
CACHE_FILE=".claude/cache/deps.txt"
if [ -f "$CACHE_FILE" ] && [ $(find "$CACHE_FILE" -mtime -1) ]; then
    echo "使用缓存的依赖信息"
    cat "$CACHE_FILE"
    exit 0
fi

# 生成并缓存
npm list > "$CACHE_FILE"
\`\`\`

并行执行:

#!/bin/bash
# ✅ 并行执行(更快)
npm run lint &
LINT_PID=$!
npm run test &
TEST_PID=$!

wait $LINT_PID
wait $TEST_PID

# ❌ 串行执行(较慢)
npm run lint
npm run test

5. 错误处理

优雅降级:

# 当可选工具不可用时提供替代方案
\`\`\`bash
# 尝试使用jq格式化JSON
if command -v jq &> /dev/null; then
    echo '{"name": "value"}' | jq .
else
    echo '{"name": "value"}'  # 直接输出
fi
\`\`\`

详细错误信息:

## 错误处理

如果命令失败,请提供:
1. **错误消息**: 清晰描述问题
2. **原因分析**: 解释为什么失败
3. **解决方案**: 提供修复建议
4. **相关链接**: 指向文档或资源

示例:
\`\`\`
❌ 部署失败

错误: 无法连接到生产服务器

原因:
- 服务器可能正在维护
- 网络连接可能中断
- 认证凭据可能已过期

解决方案:
1. 检查网络连接: \`ping server.example.com\`
2. 验证认证: \`aws sts get-caller-identity\`
3. 查看服务器状态: https://status.example.com
4. 重试命令: /deploy prod

帮助文档: https://docs.example.com/deployment
\`\`\`

6. 文档和注释

自文档化代码:

# 使用清晰的标题和结构
## 步骤1:环境检查
## 步骤2:运行测试
## 步骤3:部署

# 使用注释说明为什么这样做
# 使用Git而不是直接拷贝,以便保留历史
git clone $REPO_URL

# 设置超时避免长时间等待
timeout 300 npm test

示例驱动:

## 使用示例

### 基础用法
\`\`\`bash
/review
\`\`\`

### 高级用法
\`\`\`bash
# 审查特定文件
/review src/user.js

# 审查并生成报告
/review > report.md

# 审查并自动修复
/review --fix
\`\`\`

### 实际场景
\`\`\`bash
# 场景1: PR审查前
/review feature/new-auth

# 场景2: 每日代码质量检查
/review --daily

# 场景3: 性能问题排查
@performance-expert 分析 src/api.js 的性能瓶颈
\`\`\`

7. 团队协作

统一配置:

// .claude/plugin.json
{
  "name": "team-standards",
  "version": "1.0.0",
  "config": {
    "lint": {
      "rules": ["airbnb", "plugin:react/recommended"],
      "autoFix": true
    },
    "test": {
      "framework": "jest",
      "coverage": 80
    }
  }
}

版本管理:

# 在README中说明兼容性
## 兼容性
- Claude Code: >= 1.0.0
- Node.js: >= 16.14.0
- macOS/Linux/Windows

## 版本策略
- 遵循语义化版本
- 主版本更新可能包含不兼容变更
- 建议使用固定版本号: `"version": "1.2.3"`

变更日志:

# 保持详细的CHANGELOG.md
## [1.2.0] - 2025-01-20
### Added
- 新增--watch选项

### Changed
- 默认超时时间从30秒增加到60秒

### Deprecated
- --old-flag将在2.0.0中移除

### Fixed
- 修复Windows路径问题

### Security
- 更新依赖版本修复CVE-2025-1234

常见问题解答(FAQ)

Q1: 如何调试命令没有执行的问题?

A: 按以下步骤排查:

1. 检查命令文件路径:

# 确认路径正确
cat .claude/plugin.json | grep commands

# 验证文件存在
ls -la .claude/commands/

2. 检查命令文件格式:

# 确保有YAML frontmatter
head -5 .claude/commands/mycommand.md

# 应该看到:
# ---
# description: 命令描述
# ---

3. 启用调试模式:

# 查看详细日志
CLAUDE_DEBUG=1 claude

# 尝试命令
/mycommand

4. 验证命令语法:

# 检查Markdown语法
npx markdownlint .claude/commands/mycommand.md

Q2: Hook脚本没有被执行?

A: 检查以下几点:

1. 权限问题:

# 确保脚本可执行
chmod +x .claude/hooks/*.sh

# 检查权限
ls -la .claude/hooks/

2. Shebang行:

# 必须有shebang
head -1 .claude/hooks/pre-commit.sh
# 应该是: #!/bin/bash 或 #!/bin/sh

3. 手动测试:

# 直接运行脚本
./.claude/hooks/pre-commit.sh

# 查看详细输出
bash -x .claude/hooks/pre-commit.sh

4. 注册状态:

# 检查plugin.json中的hooks配置
cat .claude/plugin.json | jq .hooks

Q3: 如何在命令中使用环境变量?

A: 有三种方式:

1. 在项目中定义:

# .env
DEPLOY_API_URL=https://api.example.com
DEPLOY_API_KEY=your_key_here

# 在命令中引用
\`\`\`bash
curl -H "Authorization: Bearer $DEPLOY_API_KEY" \
     $DEPLOY_API_URL/deploy
\`\`\`

2. 在命令文件中动态获取:

## 配置
API_URL: \`$(grep API_URL .env | cut -d= -f2)\`

3. 通过Claude Code环境:

# 在Claude Code启动时设置
export MY_PLUGIN_CONFIG=/path/to/config
claude

Q4: SubAgent无法正常工作?

A: 检查以下几点:

1. Agent定义完整性:

# 检查必须的字段
cat .claude/agents/myagent.md | head -10

# 应该包含:
# ---
# name: agent-name
# description: agent description
# version: 1.0.0
# ---

2. 调用语法:

# ✅ 正确
@code-reviewer 请审查这个文件

# ❌ 错误
@code_reviewer 请审查这个文件
@codeReviewer 请审查这个文件

3. Agent可见性:

# 列出所有可用的agents
claude --list-agents

# 验证你的agent在列表中

Q5: 如何处理跨平台的路径问题?

A: 使用跨平台兼容的方式:

#!/bin/bash
# ❌ 不好的方式(仅适用于特定平台)
DIR="/Users/username/project"

# ✅ 好的方式(跨平台)
PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"

# ✅ 或使用相对路径
SCRIPT_DIR="$(dirname "$0")"

# 对于文件操作,使用跨平台工具
if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS specific
    STAT_FORMAT="-f%z"
else
    # Linux
    STAT_FORMAT="-c%s"
fi

Q6: 插件之间有冲突怎么办?

A: 按优先级解决:

1. 检查命令名称:

# 列出所有命令
claude --list-commands

# 如果冲突,重命名你的命令
# 或者卸载冲突的插件

2. 命名空间:

// 为命令添加前缀避免冲突
{
  "commands": [
    {
      "name": "myplugin:deploy",  // 添加前缀
      "description": "My plugin deploy"
    }
  ]
}

3. 加载顺序:

# 插件按加载顺序,后加载的优先级更高
# 在~/.claude/plugins.json中调整顺序

Q7: 如何测试插件的兼容性?

A: 建立测试流程:

1. 多版本测试:

# 测试不同Claude Code版本
docker run claude:v1.0.0 claude --plugin ./
docker run claude:v1.1.0 claude --plugin ./

2. 环境测试:

# .github/workflows/test.yml
name: Test Plugin
on: [push, pull_request]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16.x, 18.x, 20.x]
    steps:
      - uses: actions/checkout@v2
      - name: Test plugin
        run: |
          npm install
          npm test

3. 集成测试:

# 创建测试项目
mkdir test-project
cd test-project
claude plugin install ../my-plugin
claude
/mycommand

Q8: 如何优化插件性能?

A: 优化策略:

1. 懒加载:

// 只在需要时加载
{
  "commands": [
    {
      "name": "heavy-command",
      "lazy": true  // 延迟加载
    }
  ]
}

2. 缓存:

# 缓存依赖结果
CACHE_DIR=".claude/cache"
CACHE_FILE="$CACHE_DIR/dependencies.json"

if [ -f "$CACHE_FILE" ]; then
    cat "$CACHE_FILE"
else
    npm list --json > "$CACHE_FILE"
    cat "$CACHE_FILE"
fi

3. 并行处理:

# 使用GNU parallel或xargs -P
find . -name "*.js" | parallel -j 4 eslint {}

总结

Claude Code插件系统强大灵活,能显著提升开发效率。通过本教程,你已经学会:

核心概念

• ✅ 插件的基本组成(命令、SubAgent、Hooks)
• ✅ 插件文件结构和清单配置
• ✅ 开发环境搭建

实战技能

• ✅ 创建Slash命令
• ✅ 开发专业SubAgent
• ✅ 编写自动化Hooks
• ✅ 调试和测试插件

发布分享

• ✅ 版本管理和发布流程
• ✅ 文档编写最佳实践
• ✅ 团队协作方法

最佳实践

• ✅ 代码质量和性能优化
• ✅ 错误处理和用户体验
• ✅ 跨平台兼容性

下一步行动

1. 立即实践

   • 为你的项目创建第一个插件
   • 封装常用命令和脚本
   • 建立团队插件库

2. 深入学习

   • 研究优秀开源插件源码
   • 探索MCP集成高级用法
   • 学习更多Shell脚本技巧

3. 社区贡献

   • 分享插件到GitHub
   • 贡献给Claude Code社区
   • 帮助其他开发者

参考资源

官方文档:

• Claude Code官方文档
• 插件开发指南
• MCP协议规范

社区资源:

• Awesome Claude Code
• Claude Code插件示例
• Claude Code中文社区

相关教程:

• MCP集成完整指南
• Think模式深度解析
• 实战案例：快速原型开发

---

Sources:

• Claude Code: Best practices for agentic coding
• Understanding Claude Code's Full Stack: MCP, Skills...
• Claude Code五件套一篇全解（Plugins/Skills/MCP/...）
• The Ultimate Claude Code Guide
• Awesome Claude Code
• Claude Code Cheatsheet
• Claude Code CLI Cheatsheet