developing-claude-code-plugins

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developing Claude Code Plugins

开发Claude Code插件

Overview

概述

This skill provides efficient workflows for creating Claude Code plugins. Use it to make plugin development fast and correct - it synthesizes official docs into actionable steps and provides working examples.

本技能为创建Claude Code插件提供高效工作流。借助它可以快速且正确地进行插件开发——它将官方文档整合为可执行步骤，并提供可用示例。

When to Use

使用场景

Use this skill when:

Creating a new Claude Code plugin from scratch
Adding components to an existing plugin (skills, commands, hooks, MCP servers)
Setting up a development marketplace for testing
Troubleshooting plugin structure issues
Understanding plugin architecture and patterns
Releasing a plugin (versioning, tagging, marketplace distribution)
Publishing updates or maintaining existing plugins

For comprehensive official documentation, use the

working-with-claude-code

skill to access full docs.

在以下场景使用本技能：

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

如需完整官方文档，请使用

working-with-claude-code

技能访问完整文档。

Quick Reference

快速参考

Need to...	Read This	Official Docs
Understand directory structure	`references/plugin-structure.md`	`plugins.md`
Choose a plugin pattern	`references/common-patterns.md`	`plugins.md`
Make hooks work cross-platform	`references/polyglot-hooks.md`	`hooks.md`
Debug plugin issues	`references/troubleshooting.md`	Various
See working examples	`examples/` directory	N/A

需要...	阅读此文档	官方文档
理解目录结构	`references/plugin-structure.md`	`plugins.md`
选择插件模式	`references/common-patterns.md`	`plugins.md`
实现跨平台钩子	`references/polyglot-hooks.md`	`hooks.md`
调试插件问题	`references/troubleshooting.md`	多个文档
查看可用示例	`examples/` 目录	无

Plugin Development Workflow

插件开发工作流

Phase 1: Plan

阶段1：规划

Before writing code:

Define your plugin's purpose
- What problem does it solve?
- Who will use it?
- What components will it need?
Choose your pattern (read
```
references/common-patterns.md
```
)
- Simple plugin with one skill?
- MCP integration with guidance?
- Command collection?
- Full-featured platform?

Review examples

```
examples/simple-greeter-plugin/
```
- Minimal plugin
```
examples/full-featured-plugin/
```
- All components
Installed plugins in
```
~/.claude/plugins/
```

编写代码前：

定义插件用途
- 它解决什么问题？
- 谁会使用它？
- 它需要哪些组件？
选择插件模式（阅读
```
references/common-patterns.md
```
）
- 仅含一个技能的简单插件？
- 集成MCP的引导型插件？
- 命令集合型插件？
- 全功能平台型插件？

参考示例

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

Phase 2: Create Structure

阶段2：创建结构

Create directories (see

references/plugin-structure.md

for details):

bash

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

Write plugin.json (required):

json

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

See

references/plugin-structure.md

for complete format.

Create development marketplace (for local testing):

Create

.claude-plugin/marketplace.json

json

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

See

references/plugin-structure.md

for complete format.

创建目录（详情见

references/plugin-structure.md

）：

bash

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills
# 根据需要添加其他组件目录

编写plugin.json（必填）：

json

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

完整格式见

references/plugin-structure.md

。

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

创建

.claude-plugin/marketplace.json

：

json

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

完整格式见

references/plugin-structure.md

。

Phase 3: Add Components

阶段3：添加组件

Use TodoWrite to track component creation:

Example:

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

For each component type, see:

Format/syntax:
```
references/plugin-structure.md
```
When to use:
```
references/common-patterns.md
```
Working code:
```
examples/
```
directory

使用TodoWrite跟踪组件创建：

示例：

- 创建技能：main-workflow
- 添加命令：/hello
- 配置钩子
- 编写README
- 测试安装

针对每种组件类型，请查看：

格式/语法：
```
references/plugin-structure.md
```
使用场景：
```
references/common-patterns.md
```
可用代码：
```
examples/
```
目录

Phase 4: Test Locally

阶段4：本地测试

Install for testing:

bash

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

Then restart Claude Code.

Test each component:
- Skills: Ask for tasks matching skill descriptions
- Commands: Run
```
/your-command
```
- MCP servers: Check tools are available
- Hooks: Trigger relevant events

Iterate:

bash

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

安装插件进行测试：

bash

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

然后重启Claude Code。

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

迭代优化：

bash

/plugin uninstall my-plugin@my-dev
# 进行修改
/plugin install my-plugin@my-dev
# 重启Claude Code

Phase 5: Debug and Refine

阶段5：调试与优化

If something doesn't work, read

references/troubleshooting.md

for:

Plugin not loading
Skill not triggering
Command not appearing
MCP server not starting
Hooks not firing

Common issues are usually:

Wrong directory structure
Hardcoded paths (use
```
${CLAUDE_PLUGIN_ROOT}
```
)
Forgot to restart Claude Code
Missing executable permissions on scripts

如果出现问题，请阅读

references/troubleshooting.md

解决以下问题：

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

常见问题通常是：

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

Phase 6: Release and Distribute

阶段6：发布与分发

Write README with:
- What the plugin does
- Installation instructions
- Usage examples
- Component descriptions
Version your release using semantic versioning:
- Update
```
version
```
  in
```
.claude-plugin/plugin.json
```
- Document changes in CHANGELOG.md or RELEASE-NOTES.md
- Example:
```
"version": "1.2.1"
```
  (major.minor.patch)

Commit and tag your release:

bash

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

Choose distribution method:

Option A: Direct GitHub distribution

Users add:

/plugin marketplace add your-org/your-plugin-repo

Your plugin.json serves as the manifest

Option B: Marketplace distribution (recommended for multi-plugin collections)

Create separate marketplace repository

Add

.claude-plugin/marketplace.json

with plugin references:

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"
  }]
}

Users add:

/plugin marketplace add your-org/your-marketplace

Update marketplace manifest for each plugin release

Option C: Private/team distribution

Configure in team's

.claude/settings.json

json

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

Test the release:

bash

# 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

Announce and maintain:
- GitHub releases (optional)
- Team notifications
- Monitor for issues and user feedback
- Plan maintenance updates

编写README，包含：
- 插件功能
- 安装说明
- 使用示例
- 组件描述
使用语义化版本标记发布版本：
- 更新
```
.claude-plugin/plugin.json
```
  中的
```
version
```
  字段
- 在CHANGELOG.md或RELEASE-NOTES.md中记录变更
- 示例：
```
"version": "1.2.1"
```
  （主版本.次版本.修订版本）

提交并标记发布版本：

bash

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

选择分发方式：

选项A：直接通过GitHub分发

用户添加：

/plugin marketplace add your-org/your-plugin-repo

你的plugin.json将作为清单文件

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

创建独立的市场仓库

添加

.claude-plugin/marketplace.json

并引用插件：

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

中配置：

json

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

测试发布版本：

bash

# 测试全新安装
/plugin marketplace add your-marketplace-source
/plugin install your-plugin@marketplace-name
# 验证功能，然后清理
/plugin uninstall your-plugin@marketplace-name

发布公告与维护：
- GitHub发布（可选）
- 团队通知
- 监控问题和用户反馈
- 规划维护更新

Critical Rules

关键规则

Always follow these (from

references/plugin-structure.md

.claude-plugin/
contains ONLY manifests (
```
plugin.json
```
and optionally
```
marketplace.json
```
)
- ❌ Don't put skills, commands, or other components inside
- ✅ Put them at plugin root
Use
${CLAUDE_PLUGIN_ROOT}
for all paths in config files
- Makes plugin portable across systems
- Required for hooks, MCP servers, scripts
Use relative paths in
plugin.json
- Start with
```
./
```
- Relative to plugin root
Make scripts executable
- ```
chmod +x script.sh
```
- Required for hooks and MCP servers

请始终遵循以下规则（来自

references/plugin-structure.md

）：

.claude-plugin/
目录仅包含清单文件（
```
plugin.json
```
和可选的
```
marketplace.json
```
）
- ❌ 请勿将技能、命令或其他组件放入此目录
- ✅ 将它们放在插件根目录
在配置文件中使用
${CLAUDE_PLUGIN_ROOT}
作为所有路径的前缀
- 使插件可跨系统移植
- 钩子、MCP服务器和脚本必须使用
在
plugin.json
中使用相对路径
- 以
```
./
```
  开头
- 相对于插件根目录
为脚本添加可执行权限
- ```
chmod +x script.sh
```
- 钩子和MCP服务器需要此权限

Resources in This Skill

本技能包含的资源

references/plugin-structure.md
- Directory layout, file formats, component syntax
references/common-patterns.md
- When to use each plugin pattern, examples
references/polyglot-hooks.md
- Cross-platform hook wrapper for Windows/macOS/Linux
references/troubleshooting.md
- Debug guide for common issues
examples/simple-greeter-plugin/
- Minimal working plugin (one skill)
examples/full-featured-plugin/
- Complete plugin with all components (includes
```
run-hook.cmd
```
)

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

Cross-References

交叉引用

For deep dives into official documentation, use the

working-with-claude-code

skill to access:

```
plugins.md
```
- Plugin development overview
```
plugins-reference.md
```
- Complete API reference
```
skills.md
```
- Skill authoring guide
```
slash-commands.md
```
- Command format
```
hooks.md
```
,
```
hooks-guide.md
```
- Hook system
```
mcp.md
```
- MCP server integration
```
plugin-marketplaces.md
```
- Distribution

如需深入了解官方文档，请使用

working-with-claude-code

技能访问：

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

Best Practices

最佳实践

Start simple - Begin with minimal structure, add complexity when needed
Test frequently - Install → test → uninstall → modify → repeat
Use examples - Copy patterns from working plugins
Follow conventions - Match style of existing plugins
Document everything - Clear README helps users and future you
Version properly - Use semantic versioning (major.minor.patch)

从简开始 - 先搭建最小结构，需要时再增加复杂度
频繁测试 - 安装→测试→卸载→修改→重复
参考示例 - 从可用插件中复制模式
遵循约定 - 匹配现有插件的风格
全面文档 - 清晰的README有助于用户和未来的自己
正确版本控制 - 使用语义化版本（主版本.次版本.修订版本）

Workflow Summary

工作流总结

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

The correct path is the fast path. Use references, follow patterns, test frequently.

规划 → 选择模式，参考示例
创建 → 搭建结构，编写清单
添加 → 构建组件（技能、命令等）
测试 → 通过开发市场安装
调试 → 使用故障排除指南
发布 → 版本标记，通过市场分发
维护 → 监控、更新、支持用户

正确的路径就是高效的路径。 参考资源、遵循模式、频繁测试。