release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Release Process

MAG Claude Plugins插件发布流程

Complete guide for releasing new versions of plugins in the MAG Claude Plugins marketplace.

本文是MAG Claude Plugins市场中插件新版本发布的完整指南。

Critical Understanding

关键说明

Claude Code plugin discovery works through TWO configuration files that MUST BOTH BE UPDATED:

plugins/{plugin-name}/plugin.json
- The plugin's own version metadata
.claude-plugin/marketplace.json
- The marketplace catalog (what users see when browsing)

Why both?

```
plugin.json
```
- Defines the plugin itself (agents, commands, version)
```
marketplace.json
```
- The "catalog" that Claude Code reads for plugin discovery

Users run

/plugin marketplace update

which reads

marketplace.json

If you only update
plugin.json
, users won't see the new version!

Claude Code插件的发现机制依赖于两个必须同时更新的配置文件：

plugins/{plugin-name}/plugin.json
- 插件自身的版本元数据
.claude-plugin/marketplace.json
- 市场目录（用户浏览时看到的内容）

为什么必须同时更新？

```
plugin.json
```
- 定义插件本身（包括Agent、命令、版本）
```
marketplace.json
```
- Claude Code用于插件发现的"目录"

用户执行

/plugin marketplace update

时会读取

marketplace.json

如果只更新
plugin.json
，用户将无法看到新版本！

Release Checklist

发布检查清单

Step 1: Update Plugin Files

步骤1：更新插件文件

plugins/{plugin-name}/plugin.json

- Update

version

field

```
plugins/{plugin-name}/agents/*.md
```
- Add new agents (if any)
```
plugins/{plugin-name}/commands/*.md
```
- Update commands (if any)
```
plugins/{plugin-name}/skills/*/SKILL.md
```
- Add new skills (if any)

plugins/{plugin-name}/plugin.json

- 更新

version

字段

```
plugins/{plugin-name}/agents/*.md
```
- 添加新的Agent（如有）
```
plugins/{plugin-name}/commands/*.md
```
- 更新命令（如有）
```
plugins/{plugin-name}/skills/*/SKILL.md
```
- 添加新技能（如有）

Step 2: Update Documentation

步骤2：更新文档

```
CHANGELOG.md
```
- Add new version entry at the top
```
RELEASES.md
```
- Add detailed release notes at the top
```
CLAUDE.md
```
- Update ALL version references (6+ locations)

```
CHANGELOG.md
```
- 在顶部添加新版本条目
```
RELEASES.md
```
- 在顶部添加详细的发布说明
```
CLAUDE.md
```
- 更新所有版本引用（共6处以上）

Step 3: ⚠️ CRITICAL - Update Marketplace Catalog

步骤3：⚠️ 关键 - 更新市场目录

File:

.claude-plugin/marketplace.json

Update TWO fields:

Marketplace metadata version (line ~10):

json

"metadata": {
  "version": "3.3.0"  // ← Update this
}

Specific plugin version (in plugins array):

json

"plugins": [
  {
    "name": "frontend",
    "version": "3.3.0",      // ← Update this (CRITICAL!)
    "description": "..."     // ← Update if description changed
  }
]

文件：

.claude-plugin/marketplace.json

更新两个字段：

市场元数据版本（约第10行）：

json

"metadata": {
  "version": "3.3.0"  // ← Update this
}

特定插件版本（在plugins数组中）：

json

"plugins": [
  {
    "name": "frontend",
    "version": "3.3.0",      // ← Update this (CRITICAL!)
    "description": "..."     // ← Update if description changed
  }
]

Step 4: Commit and Tag

步骤4：提交并创建标签

bash

undefined

bash

undefined

Commit all changes

提交所有更改

git add -A git commit -m "feat({plugin}): v{X.Y.Z} - {Feature summary}"

Create tag (format: plugins/{plugin-name}/v{X.Y.Z})

创建标签（格式：plugins/{plugin-name}/v{X.Y.Z}）

git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."

Push

推送

git push origin main git push origin plugins/{plugin}/v{X.Y.Z}

undefined

git push origin main git push origin plugins/{plugin}/v{X.Y.Z}

undefined

Step 5: Verify

步骤5：验证

bash

/plugin marketplace update mag-claude-plugins

bash

/plugin marketplace update mag-claude-plugins

Should show new version ✅

应显示新版本 ✅

---

---

Common Mistakes

常见错误

❌ #1: Forgot to update marketplace.json

❌ 错误1：忘记更新marketplace.json

Symptom: Users still see old version after

/plugin marketplace update

Fix:

bash

undefined

症状： 用户执行

/plugin marketplace update

后仍看到旧版本

修复方法：

bash

undefined

Update .claude-plugin/marketplace.json

更新 .claude-plugin/marketplace.json

vim .claude-plugin/marketplace.json

Update plugins[].version field

更新plugins[].version字段

git add .claude-plugin/marketplace.json git commit -m "fix(marketplace): Update {plugin} version to v{X.Y.Z}" git push origin main

undefined

git add .claude-plugin/marketplace.json git commit -m "fix(marketplace): Update {plugin} version to v{X.Y.Z}" git push origin main

undefined

❌ #2: Wrong git tag format

❌ 错误2：Git标签格式错误

Wrong:

frontend-v3.3.0

v3.3.0

frontend/v3.3.0

Correct:

plugins/frontend/v3.3.0

✅

错误格式：

frontend-v3.3.0

v3.3.0

frontend/v3.3.0

正确格式：

plugins/frontend/v3.3.0

✅

❌ #3: Inconsistent versions

❌ 错误3：版本不一致

Problem: plugin.json says v3.3.0 but marketplace.json says v3.2.0

Prevention: Use checklist, search for old version:

grep -r "3.2.0" .

问题： plugin.json显示v3.3.0但marketplace.json显示v3.2.0

预防方法： 使用检查清单，搜索旧版本：

grep -r "3.2.0" .

Version Numbering

版本编号规则

MAJOR (X.0.0): Breaking changes (removed agents, changed behavior) MINOR (x.Y.0): New features (new agents/commands, backward compatible) PATCH (x.y.Z): Bug fixes (no new features, backward compatible)

MAJOR（X.0.0）： 破坏性变更（移除Agent、更改行为） MINOR（x.Y.0）： 新功能（新增Agent/命令，向后兼容） PATCH（x.y.Z）： Bug修复（无新功能，向后兼容）

Quick Reference

快速参考

Minimal checklist:

✅ Update
```
plugins/{plugin}/plugin.json
```
version
✅ Update
```
.claude-plugin/marketplace.json
```
plugin version ⚠️ CRITICAL
✅ Update
```
CHANGELOG.md
```
,
```
RELEASES.md
```
,
```
CLAUDE.md
```

✅ Commit:

git commit -m "feat({plugin}): v{X.Y.Z} - {summary}"

✅ Tag:

git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."

✅ Push:

git push origin main && git push origin plugins/{plugin}/v{X.Y.Z}

✅ Verify:
```
/plugin marketplace update
```
shows new version

最小检查清单：

✅ 更新
```
plugins/{plugin}/plugin.json
```
版本
✅ 更新
```
.claude-plugin/marketplace.json
```
中的插件版本 ⚠️ 关键
✅ 更新
```
CHANGELOG.md
```
、
```
RELEASES.md
```
、
```
CLAUDE.md
```

✅ 提交：

git commit -m "feat({plugin}): v{X.Y.Z} - {summary}"

✅ 创建标签：

git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."

✅ 推送：

git push origin main && git push origin plugins/{plugin}/v{X.Y.Z}

✅ 验证：
```
/plugin marketplace update
```
显示新版本

Example Release

发布示例

bash

undefined

bash

undefined

1. Update versions

1. 更新版本

vim plugins/frontend/plugin.json # version: "3.3.0" vim .claude-plugin/marketplace.json # plugins[0].version: "3.3.0" ← DON'T FORGET! vim CHANGELOG.md RELEASES.md CLAUDE.md

vim plugins/frontend/plugin.json # version: "3.3.0" vim .claude-plugin/marketplace.json # plugins[0].version: "3.3.0" ← 别忘记！ vim CHANGELOG.md RELEASES.md CLAUDE.md

2. Commit

2. 提交

git add -A git commit -m "feat(frontend): v3.3.0 - Multi-Model Plan Review"

3. Tag

3. 创建标签

git tag -a plugins/frontend/v3.3.0 -m "Frontend Plugin v3.3.0"

4. Push

4. 推送

git push origin main git push origin plugins/frontend/v3.3.0

5. Verify

5. 验证

/plugin marketplace update mag-claude-plugins

Output: frontend v3.3.0 ✅

输出：frontend v3.3.0 ✅

---

---

Troubleshooting

故障排除

Q: Users still see old version A: Check

.claude-plugin/marketplace.json

- version must match

plugin.json

Q: Tag already exists A:

git tag -d {tag}

then

git push origin :{tag}

then recreate

Q: How to test locally? A:

/plugin marketplace add /path/to/claude-code

Related: RELEASE_PROCESS.md - Full detailed documentation

Last Updated: November 13, 2025

问：用户仍看到旧版本 答：检查

.claude-plugin/marketplace.json

- 版本必须与

plugin.json

一致

问：标签已存在 答：执行

git tag -d {tag}

，然后

git push origin :{tag}

，之后重新创建标签

问：如何本地测试？ 答：执行

/plugin marketplace add /path/to/claude-code

相关文档： RELEASE_PROCESS.md - 完整详细文档

最后更新： 2025年11月13日