Claude Code Plugins 深度解析：擴展 AI 開發工具的完整指南

Claude Code Plugins 是 Anthropic 推出的擴展機制，讓開發者能夠為 Claude Code 添加自定義指令、代理、技能、事件鉤子與 MCP 伺服器。本文將深入探討其架構設計、核心元件與實作細節。

一、為什麼需要 Plugins？

在探討技術細節之前，我們需要理解 Plugins 解決的核心問題。Claude Code 本身提供強大的 AI 輔助開發能力，但不同團隊、不同專案有著截然不同的工作流程與需求。Plugins 的出現正是為了解決這個挑戰：

傳統的 .claude/ 目錄配置雖然可以自定義指令與代理，但這些配置僅限於單一專案，無法跨專案共享，也沒有版本管理機制。Plugins 透過引入插件市場 (Marketplace) 機制，讓開發者可以發布、分享、安裝具有版本控制的插件，實現真正的跨專案、跨團隊复用。

這種設計理念讓 Claude Code 從一個固定的開發助手，蛻變成一個可擴展的開發平台。

二、插件架構總覽

2.1 插件目錄結構

每個 Claude Code Plugin 都有標準化的目錄結構：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必要：插件清單檔案
├── commands/                # 指令檔案 (.md)
├── agents/                  # 自定義代理定義
├── skills/                  # 代理技能 (.md)
├── hooks/                   # 事件鉤子
│   └── hooks.json
├── .mcp.json               # MCP 伺服器配置
├── .lsp.json               # LSP 伺服器配置
└── README.md               # 文件說明

關鍵設計原則：plugin.json 必須放在 .claude-plugin/ 目錄內，但所有其他元件（commands、agents、skills、hooks）必須放在插件根目錄，而非 .claude-plugin/ 內部。

2.2 插件清單 (plugin.json)

每個插件都必須包含一個 plugin.json 檔案，作為插件的元數據描述：

{
  "name": "my-plugin",
  "description": "我的自定義插件",
  "version": "1.0.0",
  "author": {
    "name": "開發者名稱",
    "email": "developer@example.com"
  }
}

這個清單定義了插件的唯一識別碼 (name)，它同時也是指令的命名空間。例如，一個名為 commit-helper 的插件，其指令會以 /commit-helper: 開頭。

2.3 插件與獨立配置的比較

面向獨立配置 (.claude/)插件 (Plugins)
指令命名/hello (短名稱)/plugin-name:hello (命名空間)
作用範圍單一專案可跨專案共享
分發方式手動複製插件市場安裝
版本管理無語意化版本控制

三、核心元件詳解

3.1 指令 (Slash Commands)

指令是插件最基本的組成單位，本質上是 Markdown 檔案，放置於 commands/ 目錄下。檔案名稱即為指令名稱。

建立一個簡單指令：

---
description: 產生標準的 Git commit 訊息
---

# Commit Helper

根據目前的程式碼變更，產生符合 conventional commits 規範的 commit 訊息。

請分析以下變更並提供 commit 訊息建議：
$ARGUMENTS

使用方式：指令透過 /plugin-name:command-name 格式呼叫。其中 $ARGUMENTS 是特殊變數，代表使用者傳入的參數。

指令檔案結構：

  • YAML frontmatter：定義指令的中繼資料（名稱、描述）
  • 標題：指令的說明標題
  • 內容：指令的系統提示詞與使用說明

3.2 自定義代理 (Custom Agents)

代理是比指令更強大的功能，能夠執行複雜的多步驟任務。代理定義放置在 agents/ 目錄下。

代理定義範例 (agents/code-reviewer.json)：

{
  "name": "code-reviewer",
  "description": "專業的程式碼審查助手",
  "systemPrompt": "你是一位資深軟體工程師，擅长代码审查。审查时需关注：\n1. 代码组织结构\n2. 潜在的性能问题\n3. 安全性考量\n4. 最佳实践遵循",
  "model": "sonnet",
  "allowedTools": ["Read", "Grep", "Bash"]
}

代理的關鍵屬性：

屬性用途
name代理識別名稱
description代理功能說明
systemPrompt代理的系統提示詞
model使用的 AI 模型
allowedTools代理可使用的工具清單

3.3 代理技能 (Agent Skills)

技能是一種模型主動叫用的能力，而非被動等待使用者呼叫。技能放置在 skills/<skill-name>/SKILL.md。

技能定義範例 (skills/refactor-helper/SKILL.md)：

---
name: refactor-helper
description: 重構輔助技能"
---

當開發者需要重構程式碼時，請主動提供以下協助：

1. 分析現有程式碼的設計模式
2. 識別可改進的地方
3. 提供重構建議
4. 協助執行安全的漸進式重構

技能的設計理念是讓 Claude Code 能夠在適當的時機主動提供幫助，而非僅僅回應使用者的請求。

3.4 事件鉤子 (Hooks)

鉤子是事件驅動的擴展機制，能夠在特定事件發生時自動執行自定義動作。鉤子定義在 hooks/hooks.json。

鉤子配置結構：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix $FILE"
          }
        ]
      }
    ],
    "PreTaskExecute": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "agent",
            "agent": "task-planner"
          }
        ]
      }
    ]
  }
}

支援的事件類型：

事件類型觸發時機
PostToolUse工具執行完成後
PreTaskExecute任務執行前
PostTaskExecute任務執行後
PreGenerate回應生成前
PostGenerate回應生成後

matcher 規則：使用正則表達式匹配觸發事件。例如 Write|Edit 匹配 Write 或 Edit 工具的使用。

3.5 MCP 伺服器整合

MCP (Model Context Protocol) 是 Claude 推出的標準化協議，讓 AI 模型能夠與外部工具和資料來源整合。插件可以透過 .mcp.json 配置 MCP 伺服器。

MCP 配置範例 (.mcp.json)：

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/project/path"]
    }
  }
}

MCP 伺服器的作用：

  • 讓 Claude Code 能夠存取 GitHub 程式碼庫
  • 提供檔案系統操作能力
  • 整合第三方服務（Linear、Figma、Slack 等）

3.6 LSP 伺服器整合

LSP (Language Server Protocol) 為各種程式語言提供標準化的程式碼分析能力。.lsp.json 配置語言伺服器：

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python",
      ".pyi": "python"
    }
  },
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"]
  }
}

官方支援的 LSP 插件（需安裝對應的二進制檔案）：

語言插件名稱必要二進制
C/C++clangd-lspclangd
C#csharp-lspcsharp-ls
Gogopls-lspgopls
Javajdtls-lspjdtls
Pythonpyright-lsppyright-langserver
Rustrust-analyzer-lsprust-analyzer

四、插件市場與安裝

4.1 市場運作機制

Plugin Marketplace 是插件的目錄與分發平台。使用市場需要兩個步驟：

  1. 添加市場：註冊市場目錄（尚未安裝任何插件）
  2. 安裝插件：從市場中選擇並安裝特定插件

官方市場：Anthropic 提供的官方市場 (claude-plugins-official) 在啟動 Claude Code 時會自動可用。

4.2 添加市場

# 從 GitHub 添加
/plugin marketplace add owner/repo

# 從其他 Git 主機添加 (HTTPS)
/plugin marketplace add https://gitlab.com/company/plugins.git

# 從其他 Git 主機添加 (SSH)
/plugin marketplace add git@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

4.3 安裝插件

# 互動式安裝
/plugin

# 指令行安裝
/plugin install plugin-name@marketplace-name

# 實際範例
/plugin install commit-commands@anthropics-claude-code

安裝範圍：

範圍說明配置位置
User (預設)對自己所有專案可見使用者全域設定
Project對所有協作者可見.claude/settings.json
Local僅限此倉庫本地覆寫
# 安裝到專案範圍
claude plugin install formatter@your-org --scope project

4.4 管理已安裝插件

# 開啟插件管理器
/plugin

# 停用插件（不解安裝）
/plugin disable plugin-name@marketplace-name

# 啟用插件
/plugin enable plugin-name@marketplace-name

# 解除安裝
/plugin uninstall plugin-name@marketplace-name

插件管理器介面：

  • Discover：瀏覽可用插件
  • Installed：管理已安裝插件
  • Marketplaces：添加/移除/更新市場
  • Errors：查看載入錯誤

五、本地開發與測試

5.1 載入本地插件

開發插件時，可以使用 --plugin-dir 旗標載入本地插件：

# 載入單個本地插件
claude --plugin-dir ./my-plugin

# 載入多個本地插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

修改插件後需要重啟 Claude Code 才能生效。

5.2 開發最佳實踐

1. 目錄結構驗證：確保所有元件目錄位於插件根目錄，而非 .claude-plugin/ 內部。

2. 逐步測試：先測試指令，再測試代理，最後測試鉤子。

3. 清理快取：若插件技能無法出現，嘗試清除快取：

rm -rf ~/.claude/plugins/cache
# 重啟 Claude Code 並重新安裝插件

5.3 從獨立配置遷移

若已有 .claude/ 配置，可遷移至插件格式：

# 1. 建立插件結構
mkdir my-plugin
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands
mkdir -p my-plugin/agents
mkdir -p my-plugin/skills

# 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/hooks.json 格式

六、官方插件分類

6.1 程式碼智慧 (Code Intelligence)

基於 LSP 的語言伺服器整合，提供深度的程式碼理解能力。

6.2 外部整合 (External Integrations)

預配置的 MCP 伺服器，整合常見開發工具：

類別插件
版本控制github, gitlab
專案管理atlassian, asana, linear, notion
設計工具figma
基礎設施vercel, firebase, supabase
通訊slack
監控sentry

6.3 開發工作流程

插件功能
commit-commandsGit commit 工作流程
pr-review-toolkitPR 審查代理
agent-sdk-devClaude Agent SDK 工具
plugin-dev插件開發工具包

6.4 輸出風格

插件功能
explanatory-output-style教育性質的實作洞察
learning-output-style互動式學習模式

七、故障排除

7.1 /plugin 指令無法識別

  1. 檢查版本：claude --version（需要 1.0.33+）
  2. 更新 Claude Code：
    • Homebrew：brew upgrade claude-code
    • npm：npm update -g @anthropic-ai/claude-code
  3. 重啟終端機

7.2 常見問題與解決方案

問題解決方案
市場無法載入驗證 URL 可訪問性，確認 .claude-plugin/marketplace.json 存在
插件安裝失敗檢查來源 URL 是否可訪問，確認倉庫為公開
檔案找不到插件被複製到快取，目錄外的路徑不會作用
技能不出現清除快取 rm -rf ~/.claude/plugins/cache

八、總結

Claude Code Plugins 為 AI 輔助開發工具帶來了前所未有的擴展性。透過標準化的插件結構（指令、代理、技能、鉤子、MCP/LSP 伺服器），開發者可以：

  1. 自定義工作流程：建立符合團隊需求的專屬指令與代理
  2. 跨專案共享：透過插件市場分發，讓更多開發者受益
  3. 深度整合：透過 MCP 與 LSP 協議，無縫整合現有開發工具鏈
  4. 事件驅動：使用鉤子在關鍵事件點自動觸發自定義動作

隨著插件生態系統的持續成長，Claude Code 正從一個 AI 開發助手轉變為一個開放的 AI 開發平台。

參考資料