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@example.com" }, "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@example.com" }, "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

方式二：npm 發布

1. 在 package.json 中命名（加 claude-plugin- 前綴）

{ "name": "claude-plugin-my-plugin", "version": "1.0.0" }

2. 發布

npm publish

3. 用戶安裝

npm install -g claude-plugin-my-plugin

方式三：直接分享

用戶下載後本地安裝

/plugin install /path/to/my-plugin

Part 3: 安裝 Plugin

從 Marketplace 安裝

1. 先添加 marketplace（只需一次）

/plugin marketplace add owner/repo

2. 列出可用 plugins

/plugin marketplace list

3. 安裝 plugin

/plugin install plugin-name@marketplace-name

從 GitHub 直接安裝

完整路徑安裝

/plugin install github:owner/repo#path/to/plugin

範例

/plugin install github:miles990/evolve-plugin

本地安裝

從本地目錄安裝

/plugin install /path/to/my-plugin

查看已安裝

列出所有已安裝的 plugins

/plugin list

查看詳細資訊

/plugin info plugin-name@marketplace

解除安裝

解除安裝特定 plugin

/plugin uninstall plugin-name@marketplace

範例

/plugin uninstall evolve@evolve-plugin

強制解除安裝（忽略相依性）

/plugin uninstall plugin-name@marketplace --force

解除安裝注意事項：

• 解除安裝不會移除 marketplace，只移除已安裝的 plugin

• 如果其他 plugin 依賴此 plugin，會警告

• 解除安裝後可隨時重新安裝

Part 4: 更新 Plugin

檢查更新

檢查所有 plugins 是否有更新

/plugin update --check

檢查特定 plugin

/plugin update --check plugin-name@marketplace

執行更新

更新特定 plugin

/plugin update plugin-name@marketplace

更新所有 plugins

/plugin update --all

自動版本檢查流程

本地版本 → 遠端版本 → 比較 ↓ ↓ plugin.json GitHub API / marketplace.json ↓ 若遠端較新 → 提示用戶更新

手動版本檢查

取得本地版本

cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["plugin@marketplace"][0].version'

取得遠端版本

curl -s https://raw.githubusercontent.com/owner/repo/main/.claude-plugin/plugin.json | jq -r '.version'

Part 5: 版本控管

版本位置（必須同步）

位置 說明

.claude-plugin/plugin.json

Plugin manifest

.claude-plugin/marketplace.json

Marketplace 索引

skills/*/SKILL.md

Skill 版本（如適用）

CHANGELOG.md

變更記錄

Git tag 發布標記

語意化版本

MAJOR.MINOR.PATCH │ │ └── Bug fixes（修復） │ └── 新功能（向後相容） └── 破壞性變更（不相容）

發布檢查清單

更新所有版本位置

• plugin.json → version
• marketplace.json → plugins[].version
• SKILL.md → version: (如適用)
• CHANGELOG.md → 新條目
• README.md → 版本徽章

Git 操作

git add . git commit -m "chore: bump version to vX.Y.Z" git tag -a vX.Y.Z -m "Release vX.Y.Z: 描述" git push origin main git push origin vX.Y.Z

CHANGELOG.md 格式

[1.1.0] - 2026-01-16

Added

• 新功能描述

Changed

• 變更描述

Fixed

• 修復描述

Security

• 安全修復

Part 6: 同步最新版本

從主 repo 同步到獨立 plugin repo

當 plugin 是從主專案分離出來時：

1. 複製 skills 目錄

cp -r /path/to/main-project/skills /path/to/plugin-repo/

2. 更新版本

編輯 plugin.json, marketplace.json

3. 提交並推送

cd /path/to/plugin-repo git add -A git commit -m "chore: sync with main-project vX.Y.Z" git push origin main

同步腳本範例

#!/bin/bash

sync-plugin.sh - 同步 plugin 到獨立 repo

MAIN_REPO="$1" PLUGIN_REPO="$2" VERSION="$3"

複製 skills

rm -rf "$PLUGIN_REPO/skills" cp -r "$MAIN_REPO/skills" "$PLUGIN_REPO/"

更新版本

sed -i '' "s/"version": ".*"/"version": "$VERSION"/"
"$PLUGIN_REPO/.claude-plugin/plugin.json"

提交

cd "$PLUGIN_REPO" git add -A git commit -m "chore: sync with main-project v$VERSION" git push origin main

自動同步（使用 GitHub Actions）

.github/workflows/sync-plugin.yml

name: Sync Plugin

on: push: branches: [main] paths: - 'skills/' - 'evolve-plugin/'

jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3

  - name: Sync to plugin repo
    run: |
      # Clone plugin repo
      git clone https://github.com/owner/plugin-repo.git

      # Copy files
      cp -r skills/ plugin-repo/
      cp evolve-plugin/.claude-plugin/* plugin-repo/.claude-plugin/

      # Push
      cd plugin-repo
      git add -A
      git commit -m "chore: auto-sync from main repo"
      git push

Part 7: Marketplace 管理

建立自己的 Marketplace

Step 1: 建立 marketplace.json

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

Step 2: 組織目錄結構

my-marketplace/ ├── .claude-plugin/ │ └── marketplace.json ├── plugin-a/ │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── commands/ │ └── skills/ ├── plugin-b/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── commands/ └── README.md

管理已添加的 Marketplace

列出已添加的 marketplaces

/plugin marketplace list

添加新 marketplace

/plugin marketplace add owner/repo

移除 marketplace

/plugin marketplace remove marketplace-name

更新 marketplace 索引

/plugin marketplace refresh

已知 Marketplaces 儲存位置

~/.claude/plugins/known_marketplaces.json

Part 8: Hooks 開發

Hook 事件類型

事件 時機 用途

PreToolUse 工具執行前 阻擋/修改工具調用

PostToolUse 工具執行後 後處理、通知

UserPromptSubmit 用戶輸入時 輸入驗證

SessionStart 會話開始 初始化

SessionEnd 會話結束 清理

Stop AI 完成回應 後處理

SubagentStop Subagent 完成 子任務處理

hooks.json 配置

{ "hooks": [ { "type": "command", "event": "PreToolUse", "command": "./hooks/protect-env.sh" }, { "type": "command", "event": "PostToolUse", "command": "./hooks/format-code.sh" }, { "type": "command", "event": "SessionStart", "command": "./hooks/init.sh" } ] }

範例 Hook：保護敏感檔案

#!/bin/bash

hooks/protect-env.sh

FILE_PATH=$(echo "$1" | jq -r '.tool.input.path // .tool.input.file_path // empty')

if [[ "$FILE_PATH" =~ .(env|key|secret|credentials)$ ]]; then echo '{"decision": "block", "reason": "Protected file type"}' >&2 exit 1 fi

exit 0

範例 Hook：自動格式化

#!/bin/bash

hooks/format-code.sh

FILE_PATH=$(echo "$1" | jq -r '.tool.input.path // empty')

if [[ "$FILE_PATH" =~ .(ts|tsx|js|jsx)$ ]]; then prettier --write "$FILE_PATH" 2>/dev/null fi

exit 0

Part 9: 常見錯誤與解決

Sharp Edges

SE-1: 目錄結構錯誤

• 嚴重度: critical

• 症狀: /plugin list 顯示 plugin 但命令不存在

• 原因: commands/、skills/ 放進 .claude-plugin/ 目錄

• 解決: 把所有組件目錄移到 plugin 根目錄

SE-2: 版本不同步

• 嚴重度: high

• 症狀: /plugin list 與 CHANGELOG 版本不符

• 原因: plugin.json、marketplace.json 版本不一致

• 解決: 建立發布 checklist，每次都檢查所有位置

SE-3: Hook 權限過高

• 嚴重度: high

• 症狀: 意外的檔案變更、數據丟失

• 原因: Hook 以用戶權限執行，範圍太廣

• 解決: 精確指定 Hook 目標，加入安全檢查

SE-4: MCP Prompt Injection

• 嚴重度: critical

• 症狀: Claude 執行意外操作

• 原因: MCP 從不信任來源獲取內容

• 解決: 只使用信任來源的 MCP

常見錯誤對照表

錯誤 正確做法

把 commands/ 放進 .claude-plugin/ 放在 plugin 根目錄

版本號不一致 同步更新所有位置

Hook 範圍太廣 精確指定目標工具

忘記 git tag 每次發布都要 tag

直接上線未測試 先用 --plugin-dir 測試

Part 10: 本地測試

測試 plugin（不安裝）

claude-code --plugin-dir /path/to/my-plugin

驗證結構

tree /path/to/my-plugin

檢查 plugin.json 語法

cat /path/to/my-plugin/.claude-plugin/plugin.json | jq .

驗證 hooks

cat /path/to/my-plugin/hooks/hooks.json | jq .

官方文檔

• Plugins

• Plugins Reference

• Plugin Marketplaces

• Hooks Guide

• Hooks Reference

• Skills

• MCP

• Subagents

• Slash Commands

延伸資源

• Claude Code GitHub

• Official Plugins

• evolve-plugin 範例：參考 evolve-plugin/.claude-plugin/ 結構