Claude Code 插件开发的最佳实践和建议
每个插件应该专注于一个特定领域或功能。
好的例子：
python- Python 开发支持git- Git 操作支持deepresearch- 深度研究支持
不好的例子：
awesome-toolkit- 包含太多不相关功能utils- 过于通用，职责不清
插件、组件的名称应该清晰描述其功能。
推荐：
python # 清楚说明是 Python 开发
git # 清楚说明是 Git 操作
office-xlsx # 清楚说明是 Excel 操作
避免：
awesome-tool # 不清楚具体功能
helper # 过于通用
utils # 过于通用
尽量减少外部依赖，保持插件简单。
推荐：
- 使用内置工具和命令
- 避免复杂的外部脚本
- 提供可选功能而非强制依赖
设计易于使用和理解的插件。
推荐：
- 清晰的错误消息
- 提供使用示例
- 包含帮助文档
- 合理的默认值
使用 kebab-case（小写字母和连字符）：
✅ my-awesome-plugin
✅ code-formatter
✅ api-client-generator
❌ MyAwesomePlugin (PascalCase)
❌ my_awesome_plugin (snake_case)
❌ myAwesomePlugin (camelCase)
使用 小写字母、数字和连字符：
✅ code-reviewer
✅ security-auditor
✅ performance-optimizer
❌ CodeReviewer
❌ code_reviewer
❌ codeReviewer
使用 小写字母和连字符：
✅ plugin-developer
✅ marketplace-manager
✅ security-expert
❌ pluginDeveloper
❌ plugin_developer
❌ PluginDeveloper
使用 小写字母和连字符，简洁描述性：
✅ format-code
✅ run-tests
✅ deploy-app
❌ formatTheCode
❌ format_code
❌ FormatCode
保持目录结构清晰一致：
plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
├── agents/
├── skills/
├── scripts/
└── README.md
遵循 DRY（Don't Repeat Yourself）原则。
不好：
<!-- command1.md -->
执行命令A
执行命令B
执行命令C
<!-- command2.md -->
执行命令A
执行命令B
执行命令C好：
<!-- common-skill/SKILL.md -->
公共操作：A、B、C
<!-- command1.md -->
使用 common-skill + 特定操作X
<!-- command2.md -->
使用 common-skill + 特定操作Y提供清晰的错误消息和恢复建议：
---
description: 执行部署
allowed-tools: Bash
---
# deploy
部署应用到服务器。
## 错误处理
如果部署失败，检查：
1. 服务器连接
2. 权限配置
3. 环境变量
## 恢复步骤
1. 检查错误日志
2. 修复问题
3. 重新部署每个插件都应该有完整的 README：
# Plugin Name
> 简短描述
## 安装
\`\`\`bash
uvx --from git+https://github.com/lazygophers/ccplugin.git@master install lazygophers/ccplugin plugin-name@ccplugin-market
\`\`\`
## 功能
- 功能1
- 功能2
## 使用
\`\`\`bash
/command-name
\`\`\`
## 配置
说明配置选项
## 示例
提供使用示例只在必要时添加注释：
需要注释：
- 复杂逻辑
- 非显而易见的决策
- 工作原因和限制
不需要注释：
- 显而易见的代码
- 重复代码内容
-
格式验证
cat .claude-plugin/plugin.json | jq .
-
本地测试
/plugin install ./plugin-path
-
功能测试
- 测试所有命令
- 测试所有技能
- 测试所有代理
- plugin.json 格式正确
- 目录结构符合规范
- 命名规范符合
- 所有命令可执行
- 所有技能可激活
- 所有代理可调用
- 功能完整无占位符
- 文档完整
使用 MAJOR.MINOR.PATCH 格式：
- MAJOR: 破坏性变更
- MINOR: 新功能，向后兼容
- PATCH: Bug 修复，向后兼容
示例：
1.0.0 → 1.0.1 # Bug 修复
1.0.1 → 1.1.0 # 新增功能
1.1.0 → 2.0.0 # 破坏性变更
维护详细的变更日志：
## [1.1.0] - 2025-01-06
### Added
- 新功能 X
- 新命令 Y
### Changed
- 改进功能 Z
### Fixed
- 修复 bug A
- 修复 bug B
### Deprecated
- 旧命令 W 将在 2.0.0 移除升级前检查：
- 破坏性变更是否必要
- 是否有迁移路径
- 是否更新文档
升级后验证：
- 功能是否正常
- 性能是否可接受
- 兼容性是否保持
避免长时间运行的阻塞操作。
不好：
---
allowed-tools: Bash(*)
---
# command
执行耗时 5 分钟的操作好：
---
allowed-tools: Bash(async-task)
---
# command
启动异步任务，立即返回缓存计算结果避免重复计算。
批量处理提高效率。
不好：
逐个处理文件好：
批量处理所有文件验证所有用户输入：
## 参数验证
- 检查参数格式
- 验证参数范围
- 清理特殊字符使用合适的权限模式：
---
permissionMode: default # 询问用户
---避免存储敏感信息：
不好：
在 plugin.json 中存储 API 密钥好：
从环境变量读取密钥谨慎执行代码：
## 安全检查
- 验证命令来源
- 检查参数安全性
- 限制执行范围不好：
创建复杂的抽象层
过度工程化
好：
保持简单
直接实现
不好：
固定路径: /usr/local/bin好：
使用环境变量或配置不好：
假设用户使用特定工具好：
检查工具可用性
提供备选方案