什麼是 Claude Code Plugins

Claude Code Plugins 是一套標準化的擴充套件系統，讓你可以將自訂功能打包成獨立的模組，方便跨專案使用和與團隊分享。每個 Plugin 本質上就是一個包含 .claude-plugin/plugin.json 設定檔的資料夾，裡面可以放入 Skills、Agents、Hooks、MCP Server 等各種元件。

Plugin 與直接放在 .claude/ 目錄下的獨立設定有什麼不同？主要差異在於：

簡單來說，如果你只是為自己的專案做一些客製化設定，用 .claude/ 目錄就夠了；但如果你想要分享給團隊或社群，就應該打包成 Plugin。

Plugin 的架構與目錄結構

一個完整的 Plugin 目錄結構如下：

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # Plugin 設定檔（必要）
├── commands/               # Slash Commands（Markdown 檔案）
├── skills/                           # Agent Skills（含 SKILL.md）
├── agents/                       # 自訂 Agent 定義
├── hooks/
│   └── hooks.json           # 事件掛鉤設定
├── .mcp.json                   # MCP Server 設定
├── .lsp.json                      # LSP Server 設定
├── bin/                             # 可執行檔（加入 PATH）
├── settings.json             # 預設 Settings
└── README.md             # 說明文件

其中最關鍵的是 .claude-plugin/plugin.json，這是 Plugin 的清單檔（manifest），定義了 Plugin 的基本資訊：

{
  "name": "my-awesome-plugin",
  "description": "一個功能強大的 Claude Code 外掛",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://github.com/yourname/my-awesome-plugin",
  "repository": "https://github.com/yourname/my-awesome-plugin",
  "license": "MIT"
}

注意：commands/、agents/、skills/、hooks/ 等目錄必須放在 Plugin 根目錄，不要放進 .claude-plugin/ 裡面。.claude-plugin/ 目錄中只需要 plugin.json。

Marketplace：發現與安裝外掛

Plugin Marketplace（外掛市集）是 Plugin 的發現和安裝平台。它的運作方式類似手機的 App Store：你先加入一個市集，然後從中挑選需要的外掛安裝。

官方 Anthropic Marketplace

Claude Code 內建了官方的 Anthropic Marketplace（claude-plugins-official），啟動時自動可用。你可以透過 /plugin 指令進入 Discover 分頁瀏覽，或在 claude.com/plugins 網頁上查看完整目錄。

安裝官方市集中的 Plugin 非常簡單：

# 安裝 GitHub 整合外掛
/plugin install github@claude-plugins-official

# 安裝 TypeScript LSP 外掛
/plugin install typescript-lsp@claude-plugins-official

官方 Marketplace 外掛分類

官方市集包含多種類型的外掛：

程式碼智慧（Code Intelligence）：這類外掛啟用 Claude Code 內建的 LSP 工具，讓 Claude 能即時跳轉定義、查找引用、顯示型別錯誤。安裝後，Claude 在每次編輯檔案後會自動收到語言伺服器的診斷結果，自動修正問題。

外部服務整合：包含預先設定好的 MCP Server，讓你無需手動設定即可連接外部服務。常見的有 github、gitlab、slack、notion、linear、figma、sentry、vercel、supabase 等。

開發工作流：如 commit-commands（Git 提交工作流）、pr-review-toolkit（PR 審查工具）、plugin-dev（Plugin 開發工具組）等。

輸出風格：如 explanatory-output-style（教學式回應）和 learning-output-style（互動學習模式）。

加入第三方 Marketplace

除了官方市集，你也可以加入其他來源的 Marketplace：

# 從 GitHub 加入
/plugin marketplace add anthropics/claude-code

# 從其他 Git 平台加入（GitLab、Bitbucket 等）
/plugin marketplace add https://gitlab.com/company/plugins.git

# 加入特定分支或標籤
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

# 從本地路徑加入
/plugin marketplace add ./my-marketplace

# 從遠端 URL 加入
/plugin marketplace add https://example.com/marketplace.json

安裝與管理 Plugins

使用互動式 Plugin Manager

執行 /plugin 指令可以打開互動式的 Plugin Manager，包含四個分頁：

• Discover：瀏覽所有已加入市集中可用的 Plugin
• Installed：查看和管理已安裝的 Plugin
• Marketplaces：管理已加入的市集
• Errors：查看 Plugin 載入錯誤

你可以使用 Tab 和 Shift+Tab 在分頁間切換。

安裝範圍（Installation Scopes）

安裝 Plugin 時可以選擇不同的安裝範圍，決定 Plugin 的影響層級：

常用管理指令

除了互動式介面，你也可以使用 CLI 指令直接操作：

# 安裝外掛（預設安裝到 User 範圍）
/plugin install plugin-name@marketplace-name

# 指定安裝範圍
claude plugin install formatter@your-org --scope project

# 停用外掛（不移除）
/plugin disable plugin-name@marketplace-name

# 重新啟用外掛
/plugin enable plugin-name@marketplace-name

# 完全移除外掛
/plugin uninstall plugin-name@marketplace-name

# 重新載入所有外掛（安裝後立即生效）
/reload-plugins

自動更新機制

Claude Code 支援自動更新已安裝的 Plugin。官方 Marketplace 預設開啟自動更新，第三方市集預設關閉。你可以透過 /plugin → Marketplaces 分頁來切換個別市集的自動更新設定。

如果你需要更細緻的控制，可以使用環境變數：

# 停用所有自動更新（包含 Claude Code 本身和所有 Plugin）
export DISABLE_AUTOUPDATER=1

# 僅保留 Plugin 自動更新，停用 Claude Code 自動更新
export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

開發你的第一個 Plugin

了解完 Plugin 的安裝和管理後，接下來讓我們從零開始建立一個 Plugin。以下步驟將帶你完成一個包含自訂 Skill 的基本 Plugin。

步驟一：建立 Plugin 目錄與 Manifest

# 建立 Plugin 目錄
mkdir my-first-plugin

# 建立 .claude-plugin 目錄
mkdir my-first-plugin/.claude-plugin

然後建立 my-first-plugin/.claude-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "description": "我的第一個 Claude Code 外掛",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

步驟二：加入 Skill

Skills 放在 skills/ 目錄中，每個 Skill 是一個包含 SKILL.md 的資料夾。資料夾名稱就是 Skill 名稱，會自動加上 Plugin 的命名空間前綴。

# 建立 Skill 目錄
mkdir -p my-first-plugin/skills/code-review

建立 my-first-plugin/skills/code-review/SKILL.md：

---
name: code-review
description: 檢查程式碼品質，提供改善建議。適用於 Code Review、PR 審查或程式碼分析。
---

# Code Review Skill

進行程式碼審查時，請檢查以下面向：

1. **程式碼結構與組織**：是否遵循 SOLID 原則、模組化程度
2. **錯誤處理**：是否有完善的 try-catch、邊界條件處理
3. **安全性**：是否有 SQL Injection、XSS 等安全漏洞
4. **效能**：是否有不必要的迴圈、記憶體洩漏風險
5. **測試覆蓋**：是否有對應的測試案例

以 Markdown 表格格式輸出審查結果，包含問題等級（嚴重/警告/建議）。

步驟三：測試 Plugin

使用 --plugin-dir 旗標可以在本機直接載入 Plugin 進行測試，不需要先發布到 Marketplace：

# 載入本地 Plugin 進行測試
claude --plugin-dir ./my-first-plugin

# 可以同時載入多個 Plugin
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

啟動後，你可以使用以下方式測試：

• 執行 /my-first-plugin:code-review 來觸發你的 Skill
• 執行 /help 確認 Skill 有出現在列表中
• 修改 SKILL.md 後執行 /reload-plugins 即時套用變更

步驟四：支援動態參數

你可以使用 $ARGUMENTS 佔位符讓 Skill 接受使用者輸入的參數：

---
description: 用個人化的方式問候使用者
---

# Hello Skill

請用溫暖、個人化的方式問候名為 "$ARGUMENTS" 的使用者，
並詢問今天可以幫助他什麼。

使用時輸入 /my-first-plugin:hello Alex，$ARGUMENTS 就會被替換為 Alex。

Plugin 進階功能

加入 Hooks 事件掛鉤

Plugin 可以包含 Hooks，在特定事件發生時自動執行指令。在 Plugin 根目錄建立 hooks/hooks.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

這個範例會在 Claude 每次寫入或編輯檔案後，自動執行 Lint 修正。Hook 的輸入是 JSON 格式，透過 jq 解析取得檔案路徑。

加入 MCP Server 設定

在 Plugin 根目錄建立 .mcp.json，可以讓 Plugin 自帶 MCP Server 設定：

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

加入 LSP Server 設定

如果你需要支援特定程式語言的程式碼智慧分析，可以建立 .lsp.json：

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

使用者安裝你的 Plugin 後，必須確保對應的語言伺服器 binary 已安裝在系統中。

附帶預設設定

Plugin 可以包含 settings.json 來設定啟用時的預設行為。目前支援 agent 設定，可以指定 Plugin 中的某個自訂 Agent 作為主要對話代理：

{
  "agent": "security-reviewer"
}

這會讓 Claude Code 在啟用該 Plugin 後，預設使用 security-reviewer Agent 的系統提示詞、工具限制和模型設定。

將現有設定轉換為 Plugin

如果你已經在 .claude/ 目錄中建立了 Skills 或 Hooks，可以輕鬆地將它們轉換為 Plugin 以便分享：

# 1. 建立 Plugin 目錄結構
mkdir -p my-plugin/.claude-plugin

# 2. 建立 plugin.json
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "從現有設定遷移而來的外掛",
  "version": "1.0.0"
}
EOF

# 3. 複製現有設定
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

# 4. 遷移 Hooks（從 settings.json 中提取 hooks 物件）
mkdir my-plugin/hooks
# 將 .claude/settings.json 中的 hooks 設定複製到 my-plugin/hooks/hooks.json

# 5. 測試遷移後的 Plugin
claude --plugin-dir ./my-plugin

遷移完成後，你可以移除 .claude/ 中的原始檔案以避免重複。當 Plugin 被載入時，Plugin 版本會優先於獨立設定。

團隊 Marketplace 設定

團隊管理員可以在專案的 .claude/settings.json 中預設 Marketplace，當團隊成員信任該 Repository 後，Claude Code 會提示他們安裝這些 Marketplace 和 Plugin：

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

這讓團隊可以統一使用相同的工具組，確保所有成員的開發環境一致。

發布 Plugin 到官方 Marketplace

當你的 Plugin 開發完成並經過充分測試後，可以提交到官方 Anthropic Marketplace。提交方式有兩種：

• Claude.ai：前往 claude.ai/settings/plugins/submit
• Console：前往 platform.claude.com/plugins/submit

你也可以建立自己的 Marketplace 來獨立發布 Plugin，詳細方法請參考官方文件中的 Plugin Marketplaces 指南。

安全性注意事項

Plugins 和 Marketplaces 是高度受信任的元件，它們可以在你的機器上以你的使用者權限執行任意程式碼。在安裝 Plugin 之前，請務必注意以下幾點：

• 只安裝來源可信的 Plugin：確認 Plugin 的作者和來源 Repository
• 檢查 Plugin 的首頁和文件：了解 Plugin 會執行哪些操作
• 注意 MCP Server 設定：Plugin 中的 MCP Server 可能會存取外部服務
• 企業環境：組織可以透過 Managed Marketplace Restrictions 限制使用者可以加入的 Marketplace

常見問題排除

延伸閱讀

本文介紹了 Claude Code Plugin 系統的完整運作方式，從安裝現有外掛到開發自己的 Plugin。如果你想深入了解相關主題，建議參考以下文章：

• Custom Skills：打造你的專屬自訂技能 — 深入了解 Skills 的開發方式
• Hooks 事件掛鉤：自動化你的工作流程 — 了解 Hooks 的設定與應用
• Multi-agent 架構：Subagents 與任務分派 — 了解 Agent 系統
• Claude Code 是什麼？完整介紹與安裝教學 — 從頭開始認識 Claude Code
• Claude Code 官方 Plugins 文件 — 完整技術規格與參考

ㄚ槌

blog.che-ya.com