Plugins 外掛系統：擴展 Claude Code 的能力

Claude Code 的 Plugins（外掛）系統是一套完整的擴充機制，讓你能夠將 Skills、Agents、Hooks 和 MCP Server 打包成可分享、可安裝的模組。透過 Plugin Marketplace（外掛市集），開發者可以輕鬆發現、安裝和管理各式外掛，從程式碼智慧分析到專案管理整合，都能一鍵搞定。本篇教學將深入介紹 Plugin 的架構、安裝方式、Marketplace 運作機制，以及如何開發你自己的 Plugin。

什麼是 Claude Code Plugins

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

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

比較項目	獨立設定（.claude/）	Plugin
適用範圍	僅限單一專案	可跨專案、跨團隊使用
指令命名	`/hello`	`/plugin-name:hello`（命名空間）
分享方式	需手動複製檔案	透過 Marketplace 一鍵安裝
版本管理	無內建版本控制	支援 Semantic Versioning
適合場景	個人工作流、快速實驗	團隊協作、社群發布

簡單來說，如果你只是為自己的專案做一些客製化設定，用 .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"
}

欄位	說明	必要性
`name`	Plugin 唯一識別名稱，也是 Skill 的命名空間前綴	必要
`description`	在 Plugin Manager 中顯示的描述文字	必要
`version`	版本號，建議使用 Semantic Versioning（如 1.0.0）	必要
`author`	作者資訊	選填
`homepage`	Plugin 首頁連結	選填
`repository`	原始碼倉庫連結	選填

注意：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 在每次編輯檔案後會自動收到語言伺服器的診斷結果，自動修正問題。

語言	Plugin 名稱	需要的 Binary
TypeScript	`typescript-lsp`	`typescript-language-server`
Python	`pyright-lsp`	`pyright-langserver`
Rust	`rust-analyzer-lsp`	`rust-analyzer`
Go	`gopls-lsp`	`gopls`
Java	`jdtls-lsp`	`jdtls`
PHP	`php-lsp`	`intelephense`
C/C++	`clangd-lsp`	`clangd`
Swift	`swift-lsp`	`sourcekit-lsp`

外部服務整合：包含預先設定好的 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 的影響層級：

範圍	說明	適用場景
User（使用者）	為自己安裝，所有專案都可用	個人常用工具
Project（專案）	安裝到 `.claude/settings.json`，團隊成員共享	團隊統一工具
Local（本地）	僅在目前 Repository 中為自己安裝	實驗性外掛
Managed（託管）	由管理員透過 Managed Settings 安裝，無法修改	企業強制外掛

常用管理指令

除了互動式介面，你也可以使用 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

常見問題排除

問題	解決方案
`/plugin` 指令無法使用	確認 Claude Code 為最新版本，執行 `npm update -g @anthropic-ai/claude-code` 更新
Marketplace 無法載入	確認 URL 可存取，且路徑中存在 `.claude-plugin/marketplace.json`
Plugin 安裝失敗	確認 Plugin 來源 URL 可存取，Repository 為公開或你有存取權限
Plugin Skills 沒有出現	清除快取 `rm -rf ~/.claude/plugins/cache`，重啟後重新安裝
LSP 伺服器未啟動	確認對應的 Binary 已安裝且在 `$PATH` 中，檢查 `/plugin` Errors 分頁