developing-claude-code-plugins

开发 Claude Code 插件

概述

此技能提供了创建 Claude Code 插件的高效工作流。使用它可以快速、正确地开发插件——它将官方文档整理为可执行的步骤，并提供可运行的示例。

适用场景

在以下情况下使用此技能：

• 从头开始创建新的 Claude Code 插件
• 向现有插件添加组件（技能、命令、钩子、MCP 服务）
• 设置用于测试的开发市场
• 排查插件结构问题
• 了解插件架构和模式
• 发布插件（版本管理、打标签、市场分发）
• 发布更新或维护现有插件

如需查阅全面的官方文档，请使用 working-with-claude-code 技能访问完整文档。

快速参考

需求	阅读内容	官方文档
了解目录结构	references/plugin-structure.md	plugins.md
选择插件模式	references/common-patterns.md	plugins.md
确保钩子跨平台运行	references/polyglot-hooks.md	hooks.md
调试插件问题	references/troubleshooting.md	各类文档
查看可运行的示例	examples/ 目录	不适用

插件开发工作流

阶段 1：规划

编写代码之前：

1. 明确插件的用途

   • 它要解决什么问题？
   • 谁会使用它？
   • 它需要哪些组件？

2. 选择模式（阅读 references/common-patterns.md）

   • 只包含一个技能的简单插件？
   • 带有使用指导的 MCP 集成？
   • 命令集合？
   • 功能齐全的平台？

3. 查看示例

   • examples/simple-greeter-plugin/ - 最简插件
   • examples/full-featured-plugin/ - 包含所有组件
   • ~/.claude/plugins/ 中已安装的插件

阶段 2：创建结构

1. 创建目录（详情请参阅 references/plugin-structure.md）：

   mkdir -p my-plugin/.claude-plugin
   mkdir -p my-plugin/skills
   # Add other component directories as needed
   

2. 编写 plugin.json（必需）：

   {
     "name": "my-plugin",
     "version": "1.0.0",
     "description": "What your plugin does",
     "author": {"name": "Your Name"}
   }
   

   完整格式请参阅 references/plugin-structure.md。

3. 创建开发市场（用于本地测试）：

   创建 .claude-plugin/marketplace.json：

   {
     "name": "my-dev",
     "plugins": [{
       "name": "my-plugin",
       "source": "./"
     }]
   }
   

   完整格式请参阅 references/plugin-structure.md。

阶段 3：添加组件

使用 TodoWrite 跟踪组件创建进度：

示例：

- Create skill: main-workflow
- Add command: /hello
- Configure hooks
- Write README
- Test installation

各组件类型的相关信息，请参阅：

• 格式/语法：references/plugin-structure.md
• 适用场景：references/common-patterns.md
• 可运行代码：examples/ 目录

阶段 4：本地测试

1. 安装以进行测试：

   /plugin marketplace add /path/to/my-plugin
   /plugin install my-plugin@my-dev
   

   然后重启 Claude Code。

2. 测试各组件：

   • 技能：请求与技能描述匹配的任务
   • 命令：运行 /your-command
   • MCP 服务：检查工具是否可用
   • 钩子：触发相关事件

3. 迭代：

   /plugin uninstall my-plugin@my-dev
   # Make changes
   /plugin install my-plugin@my-dev
   # Restart Claude Code
   

阶段 5：调试和完善

如果某项功能无法正常运行，请阅读 references/troubleshooting.md，了解如何排查以下问题：

• 插件无法加载
• 技能未触发
• 命令未显示
• MCP 服务未启动
• 钩子未触发

常见问题通常包括：

• 目录结构错误
• 路径硬编码（请使用 ${CLAUDE_PLUGIN_ROOT}）
• 忘记重启 Claude Code
• 脚本缺少可执行权限

阶段 6：发布和分发

1. 编写 README，包含：

   • 插件的功能
   • 安装说明
   • 使用示例
   • 组件说明

2. 使用语义化版本为发布版本编号：

   • 更新 .claude-plugin/plugin.json 中的 version
   • 在 CHANGELOG.md 或 RELEASE-NOTES.md 中记录变更
   • 示例："version": "1.2.1"（主版本号.次版本号.修订号）

3. 提交并为发布版本打标签：

   git add .
   git commit -m "Release v1.2.1: [brief description]"
   git tag v1.2.1
   git push origin main
   git push origin v1.2.1
   

4. 选择分发方式：

   选项 A：直接通过 GitHub 分发

   • 用户添加：/plugin marketplace add your-org/your-plugin-repo
   • 你的 plugin.json 用作清单

   选项 B：通过市场分发（推荐用于包含多个插件的集合）

   • 创建单独的市场仓库
   • 添加 .claude-plugin/marketplace.json 并写入插件引用：

     {
       "name": "my-marketplace",
       "owner": {"name": "Your Name"},
       "plugins": [{
         "name": "your-plugin",
         "source": {
           "source": "url",
           "url": "https://github.com/your-org/your-plugin.git"
         },
         "version": "1.2.1",
         "description": "Plugin description"
       }]
     }
     

   • 用户添加：/plugin marketplace add your-org/your-marketplace
   • 每次发布插件时更新市场清单

   选项 C：私有/团队分发

   • 在团队的 .claude/settings.json 中配置：

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

5. 测试发布版本：

   # Test fresh installation
   /plugin marketplace add your-marketplace-source
   /plugin install your-plugin@marketplace-name
   # Verify functionality, then clean up
   /plugin uninstall your-plugin@marketplace-name
   

6. 发布公告并维护：

   • GitHub 发布页面（可选）
   • 团队通知
   • 关注问题和用户反馈
   • 规划维护更新

关键规则

始终遵循以下规则（来自 references/plugin-structure.md）：

1. .claude-plugin/ 仅包含清单（plugin.json，以及可选的 marketplace.json）

   • ❌ 不要在其中放置技能、命令或其他组件
   • ✅ 将它们放在插件根目录

2. 在配置文件的所有路径中使用 ${CLAUDE_PLUGIN_ROOT}

   • 确保插件可在不同系统间移植
   • hooks、MCP 服务和脚本必须使用

3. 在 plugin.json 中使用相对路径

   • 以 ./ 开头
   • 相对于插件根目录

4. 确保脚本可执行

   • chmod +x script.sh
   • hooks 和 MCP 服务必须使用

此技能中的资源

• references/plugin-structure.md - 目录布局、文件格式、组件语法
• references/common-patterns.md - 各插件模式的适用场景和示例
• references/polyglot-hooks.md - 适用于 Windows/macOS/Linux 的跨平台 hook 包装器
• references/troubleshooting.md - 常见问题的调试指南
• examples/simple-greeter-plugin/ - 最小可用插件（一个技能）
• examples/full-featured-plugin/ - 包含所有组件的完整插件（包括 run-hook.cmd）

交叉引用

如需深入了解官方文档，请使用 working-with-claude-code 技能访问：

• plugins.md - 插件开发概述
• plugins-reference.md - 完整 API 参考
• skills.md - 技能编写指南
• slash-commands.md - 命令格式
• hooks.md、hooks-guide.md - hook 系统
• mcp.md - MCP 服务集成
• plugin-marketplaces.md - 分发

最佳实践

1. 从简单开始 - 先采用最小结构，需要时再增加复杂度
2. 频繁测试 - 安装 → 测试 → 卸载 → 修改 → 重复
3. 参考示例 - 从可运行的插件中借鉴模式
4. 遵循惯例 - 与现有插件的风格保持一致
5. 完整记录 - 清晰的 README 有助于用户，也方便未来的自己
6. 正确使用版本号 - 采用语义化版本（主版本号.次版本号.修订号）

工作流摘要

Plan → Choose pattern, review examples
Create → Make structure, write manifests
Add → Build components (skills, commands, etc.)
Test → Install via dev marketplace
Debug → Use troubleshooting guide
Release → Version, tag, distribute via marketplace
Maintain → Monitor, update, support users

正确的路径就是最快的路径。 使用参考资料，遵循模式，频繁测试。