claude-code-plugin

Claude Code Plugin 完整指南

建立、發布、安裝、更新、同步 Claude Code Plugin 的完整指南

適用場景

• 開發新的 Claude Code Plugin
• 發布 Plugin 到 Marketplace
• 安裝和更新 Plugin
• 管理 Plugin 版本
• 同步最新版本
• 建立自訂 Marketplace

---

Part 1: Plugin 架構

目錄結構

my-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest（必要）
│   └── marketplace.json     # Marketplace 索引（選用）
├── commands/                # Slash 命令（在根目錄！）
│   └── my-command.md
├── skills/                  # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Hook 配置
├── agents/                  # Subagent 定義
├── .mcp.json               # MCP 伺服器配置
├── CHANGELOG.md
└── README.md

⚠️ 重要：commands/、skills/、hooks/ 必須在根目錄，不要放進 .claude-plugin/

plugin.json 規範

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin 功能描述",
  "author": {
    "name": "作者名稱",
    "email": "[email protected]"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

四大組件

組件	用途	觸發方式	檔案格式
Commands	用戶執行的斜線命令	/command 手動	Markdown
Skills	教 Claude 如何做事	自動根據上下文	SKILL.md
Hooks	事件驅動自動化	系統事件觸發	JSON + Shell
MCP	提供工具能力	Claude 呼叫	.mcp.json

---

Part 2: 發布 Plugin

方式一：GitHub Marketplace（推薦）

Step 1: 建立 marketplace.json

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-marketplace",
  "description": "我的 Plugin 集合",
  "owner": {
    "name": "username",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "version": "1.0.0",
      "source": "./",
      "description": "Plugin 描述",
      "category": "development"
    }
  ]
}

Step 2: 推送到 GitHub

git add .
git commit -m "feat: add Plugin marketplace format"
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin main
git push origin v1.0.0

Step 3: 用戶安裝

# 添加 marketplace
/plugin marketplace add owner/repo

# 安裝 plugin
/plugin install my-plugin@my-marketplace