release

プラグインのリリースプロセス

MAG Claude Plugins マーケットプレイスでプラグインの新しいバージョンをリリースするための完全ガイドです。

重要なポイント

Claude Code のプラグイン検出は、2 つの設定ファイルを通じて行われます。両方を必ず更新してください。

1. plugins/{plugin-name}/plugin.json - プラグイン自体のバージョンメタデータ
2. .claude-plugin/marketplace.json - マーケットプレイスのカタログ（ユーザーが閲覧する情報）

両方が必要な理由

• plugin.json - プラグイン自体（エージェント、コマンド、バージョン）を定義します
• marketplace.json - Claude Code がプラグインを検出するために読み込む「カタログ」です
• ユーザーが /plugin marketplace update を実行すると、marketplace.json が読み込まれます
• plugin.json だけを更新しても、ユーザーには新しいバージョンが表示されません！

---

リリースチェックリスト

ステップ 1：プラグインファイルを更新する

• plugins/{plugin-name}/plugin.json - version フィールドを更新する
• plugins/{plugin-name}/agents/*.md - 新しいエージェントを追加する（該当する場合）
• plugins/{plugin-name}/commands/*.md - コマンドを更新する（該当する場合）
• plugins/{plugin-name}/skills/*/SKILL.md - 新しいスキルを追加する（該当する場合）

ステップ 2：ドキュメントを更新する

• CHANGELOG.md - 新しいバージョンの項目を先頭に追加する
• RELEASES.md - 詳細なリリースノートを先頭に追加する
• CLAUDE.md - バージョンへのすべての参照を更新する（6 か所以上）

ステップ 3：⚠️ 重要 - マーケットプレイスのカタログを更新する

ファイル： .claude-plugin/marketplace.json

2 つのフィールドを更新します。

1. マーケットプレイスのメタデータのバージョン（10 行目付近）：

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

2. 特定のプラグインのバージョン（plugins 配列内）：

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

ステップ 4：コミットしてタグを付ける

# 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})
git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."

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

ステップ 5：確認する

/plugin marketplace update mag-claude-plugins
# Should show new version ✅

---

よくある間違い

❌ #1：marketplace.json の更新を忘れる

症状： /plugin marketplace update の後も、ユーザーには古いバージョンが表示されます

修正方法：

# Update .claude-plugin/marketplace.json
vim .claude-plugin/marketplace.json
# Update plugins[].version field

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

❌ #2：git タグの形式が間違っている

誤り： frontend-v3.3.0、v3.3.0、frontend/v3.3.0
正しい形式： plugins/frontend/v3.3.0 ✅

❌ #3：バージョンに一貫性がない

問題： plugin.json には v3.3.0 と記載されているのに、marketplace.json には v3.2.0 と記載されています

予防策： チェックリストを使い、古いバージョンを検索します：grep -r "3.2.0" .

---

バージョン番号の付け方

MAJOR（X.0.0）： 互換性を破る変更（エージェントの削除、動作の変更） MINOR（x.Y.0）： 新機能（新しいエージェント／コマンド、後方互換性あり） PATCH（x.y.Z）： バグ修正（新機能なし、後方互換性あり）

---

クイックリファレンス

最小限のチェックリスト：

1. ✅ plugins/{plugin}/plugin.json のバージョンを更新する
2. ✅ .claude-plugin/marketplace.json のプラグインのバージョンを更新する ⚠️ 重要
3. ✅ CHANGELOG.md、RELEASES.md、CLAUDE.md を更新する
4. ✅ コミットする：git commit -m "feat({plugin}): v{X.Y.Z} - {summary}"
5. ✅ タグを付ける：git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."
6. ✅ プッシュする：git push origin main && git push origin plugins/{plugin}/v{X.Y.Z}
7. ✅ 確認する：/plugin marketplace update に新しいバージョンが表示される

---

リリース例

# 1. Update versions
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

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

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

# 4. Push
git push origin main
git push origin plugins/frontend/v3.3.0

# 5. Verify
/plugin marketplace update mag-claude-plugins
# Output: frontend v3.3.0 ✅

---

トラブルシューティング

Q：ユーザーに古いバージョンが表示されます
A： .claude-plugin/marketplace.json を確認してください。バージョンは plugin.json と一致している必要があります

Q：タグがすでに存在します
A： git tag -d {tag} を実行し、次に git push origin :{tag} を実行してから、タグを作り直してください

Q：ローカルでテストするには？
A： /plugin marketplace add /path/to/claude-code

---

関連項目： RELEASE_PROCESS.md - 詳細なドキュメント全文

最終更新日： 2025 年 11 月 13 日