04-7 Plugin 的正確使用：超越 Quick Start 的 know-how

這個單元解決什麼問題多數人照 Quick Start 裝完 plugin 就以為結束了，卻說不清楚它裝了什麼、提供了哪些能力、怎麼完整配置；這是知其然不知其所以然的典型。Claude Code v2.1 起 plugin 是「打包發布 skills、agents、hooks、MCP / LSP 設定、背景監控的單元」，透過兩個公開市集（claude-plugins-official 與 claude-community）分發。本單元講 plugin 目錄結構、裝後盤點 SOP、超越 Quick Start 的進階配置、版本管理，以及拿起 plugin 之前的安全評估 SOP。

學習目標

說出一個 plugin 打包了哪些元件（skills、agents、commands、hooks、.mcp.json、.lsp.json、monitors、bin/、settings.json），以及各自在系統裡扮演的角色。
裝完一個 plugin 後，主動盤點它實際提供了哪些 skill / agent / command / hook / MCP server，而非依賴 Quick Start 的片面說明。
做超越 Quick Start 的完整配置：環境變數、與既有設定的衝突排解、模型選擇、預載 skills。
區分 claude --plugin-dir（本機開發）、--plugin-url（CI artifact）、/plugin install（市集）三條安裝路徑的使用時機。
套 03-1 評估框架與 03-3 安全原則，決定一個 plugin 該不該裝、要不要保留、要不要限縮其 hook 或 MCP 權限。

1. Plugin 是什麼：打包成一包的能力集合

Plugin 是一個目錄，內含 manifest 與一組元件：skills、agents、commands、hooks、MCP server 設定、LSP server 設定、背景監控、可執行檔。它把「單一專案用 .claude/ 散裝設定」升級成可分發、可版本化、跨專案共用的單元（截至 2026-06 依官方 plugins 章節 [1]）。安裝一個 plugin 實際在做的事：

把元件目錄與檔案註冊到 Claude Code 的載入清單。
透過 plugin.json 的 name 為所有 Skill / Command 加 namespace 前綴（/plugin-name:skill-name）。
啟用內含的 MCP server 與 LSP server 設定。
套用 settings.json 的預設值（限 agent 與 subagentStatusLine 兩個 key）[1]。

為什麼會需要 plugin 而不是只在 .claude/ 寫跨專案共用：同一份 API 慣例、code review agent、post-tool formatter 在多個 repo 都用得上，總不能每個 repo 重寫。版本化：plugin 有 version 欄位，可設 pinned 鎖版本，避免「自動追蹤 main 結果今天更新壞了」的情境。分發：透過市集讓團隊成員或社群一鍵安裝，不必手動 clone + 設定路徑。Namespace 隔離：plugin skill 一律 namespaced（/plugin-name:hello），不同 plugin 同名 skill 不會互相覆蓋。

2. Plugin 與獨立 `.claude/` 配置的差別

Claude Code 支援兩種方式加自訂 skills、agents、hooks（[1]）：

面向	獨立配置（`.claude/`）	Plugin
Skill 命名	`/hello`（短、無前綴）	`/my-plugin:hello`（namespaced）
適合	個人工作流、單一專案客製、快速實驗	跨專案共用、團隊分發、社群市集、版本化
分發方式	透過版控（隨 repo 走）	透過市集或 git URL
版本管理	隨 repo 走	顯式 `version` 欄位或 git commit SHA
Hook 設定位置	`settings.json` 內	`hooks/hooks.json`（與設定分離）
安裝指令	編輯檔案	`/plugin install` 或 `claude --plugin-dir`

起手策略先在 .claude/ 獨立配置快速迭代、驗證流程值得封裝，再轉成 plugin 分發（[1]）。這個順序避免「花三小時打包一個用不到的功能」。

3. 目錄結構

完整的 plugin 目錄結構（截至 2026-06）[1]：

my-plugin/

.claude-plugin/

plugin.json · 必要：manifest

skills/ · 選填：Agent Skills

commands/ · 選填：使用者主動觸發的 command

agents/ · 選填：自訂 Subagent

hooks/ · 選填：事件 handler

.mcp.json · 選填：MCP server 設定

.lsp.json · 選填：LSP server 設定

monitors/ · 選填：背景監控

bin/ · 選填：plugin 啟用時加入 PATH 的可執行檔

settings.json · 選填：plugin 啟用時套用的預設值

README.md · 建議：人類可讀的說明

不要把 commands/、agents/、skills/、hooks/ 放進 .claude-plugin/ 內官方反覆強調這條（[1]）：只有 plugin.json 該在 .claude-plugin/ 內。所有其他目錄必須在 plugin 根目錄層。這是常見錯誤，會讓 plugin 載入時找不到元件。

4. Manifest：`.claude-plugin/plugin.json`

最小 manifest [1]：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

欄位	用途
`name`	唯一識別，同時是 skill namespace 前綴。`/my-first-plugin:hello` 的 `my-first-plugin` 就是這值
`description`	在 plugin manager 顯示，供使用者判斷這個 plugin 的用途
`version`	選填。若設了，使用者只在版本變動時收到更新。若省略，git 分發時以 commit SHA 為版本，每次 commit 算新版本 [1]
`author`	選填，作者資訊（name、email）
`homepage`	選填，plugin 首頁
`repository`	選填，源碼 repo
`license`	選填，授權條款

完整 schema 見官方 plugins reference [2]。

5. 各元件怎麼放

5.1 Skills

Skills 用目錄形式放 skills/<name>/SKILL.md，與獨立配置同（[1]，並見 04-4 Skill）：

my-plugin/

skills/

code-review/

SKILL.md

references/

每個 SKILL.md 用 YAML frontmatter 與 description：

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

裝好 plugin 後跑 /reload-plugins 才會載入。完整 Skill 撰寫規範見 04-4 Skill。

5.2 Commands

Commands 放 commands/<name>.md 單檔（[1]，並見 04-3 Command）：

my-plugin/

commands/

deploy.md

commands/ 對 plugin 是 legacy 形式官方在 v2.1 文件中明示「Use skills/ for new plugins」（[1]）。新 plugin 應把命令式邏輯放 skills/<name>/SKILL.md 內，享有目錄式結構、references/、scripts/ 與 progressive disclosure。

5.3 Agents

Subagent 放 agents/<name>.md，frontmatter 與獨立配置同（見 04-5 Subagent）。Plugin Subagent 有三個限制（[1]）：hooks、mcpServers、permissionMode 三個 frontmatter 欄位被忽略。

Plugin Subagent 的限制安全考量，Plugin Subagent 不支援 hooks、mcpServers、permissionMode 欄位 [1]。需要這三個時把 agent 檔複製到 .claude/agents/ 或 ~/.claude/agents/。另一條路是在 settings.json 的 permissions.allow 加規則，但該規則適用整個 session，無法只限 plugin agent。

5.4 Hooks

Hook 設定放 hooks/hooks.json，與 settings.json 的 hooks 區塊同樣格式（[1]）：

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

Hook command 透過 stdin 收到 hook 輸入 JSON；用 jq 解出欄位（範例見 04-6 Hooks）。

5.5 MCP servers

.mcp.json 與獨立配置同 schema（[1]）：

{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Plugin 啟用時，這些 MCP server 自動連線到主 session。

5.6 LSP servers

LSP（Language Server Protocol）server 給 Claude 即時程式碼智慧（[1]）。.lsp.json 範例：

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

優先用官方市集的預建 LSP對 TypeScript、Python、Rust 等主流語言，直接從 claude-plugins-official 市集安裝預建的 LSP plugin。只有需要官方沒覆蓋的語言才自建 LSP plugin [1]。

5.7 Monitors

Monitors 讓 plugin 在背景 watch log、檔案、外部狀態，事件發生時通知 Claude（[1]）。monitors/monitors.json：

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

command 的每一行 stdout 視為一個 notification 傳給 Claude。完整 schema 含 when 觸發與變數替換，見 [2]。

5.8 bin/

bin/ 內的可執行檔在 plugin 啟用時加入 Bash tool 的 PATH [1]。謹慎放：每個可執行檔都是你 shell 上隨時可叫用的指令，可能被任何 hook 或 agent 觸發。

5.9 預設 settings

Plugin 根目錄的 settings.json 啟用時套用預設值。目前只支援兩個 key（[1]）：agent 與 subagentStatusLine。

{
  "agent": "security-reviewer"
}

這會把 plugin 的 agents/security-reviewer.md 設為主 session 的 agent。未知的 key 會被靜默忽略。

6. 安裝：四條路徑

依使用場景選對應的安裝方式：

路徑	指令	用途
本機開發	`claude --plugin-dir ./my-plugin`	開發、測試、debug
ZIP 本機	`claude --plugin-dir ./my-plugin.zip`	同上但用打包好的版本（v2.1.128+）[1]
URL CI artifact	`claude --plugin-url https://example.com/my-plugin.zip`	CI 產出的 plugin 載入測試
市集	`/plugin install <name>`	從 `claude-plugins-official` 或 `claude-community` 安裝

6.1 本機開發模式

--plugin-dir 直接載入指定目錄，不需安裝步驟（[1]）：

claude --plugin-dir ./my-plugin

多個 plugin 同時載入（重複 flag）：

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

開發中改完 plugin，跑 /reload-plugins 重載，不用重啟。

6.2 從市集安裝

市集是用 /plugin 命令管理。安裝流程（[1]）：

/plugin                                  # 開啟 plugin manager
# 在市集頁面選擇 plugin，按指示安裝

或用指令式：

/plugin install <plugin-name>            # 從已加入的市集安裝
/plugin marketplace add anthropics/claude-plugins-community

6.3 兩個公開市集

Anthropic 維護兩個公開市集（[1]）：

claude-plugins-official：Anthropic 策展的精選 plugin。每個 Claude Code 安裝自動可用。
claude-community：第三方提交、經 review 後上架的社群市集。使用者用 /plugin marketplace add anthropics/claude-plugins-community 加入，從 @claude-community 安裝。

兩者差異claude-plugins-official 策展方式由 Anthropic 全權決定，無申請流程；提交表單不會把 plugin 放進這裡。claude-community 透過審核 pipeline：跑 claude plugin validate 自動檢查 + 自動安全篩選，通過後 pin 在 anthropics/claude-plugins-community 倉庫的特定 commit SHA，CI 在你推新 commit 時自動 bump pin。catalog 每晚同步，所以通過到可安裝可能有 24 小時延遲。提交審核入口：claude.ai/settings/plugins/submit 或 platform.claude.com/plugins/submit。

6.4 Private 市集（團隊內部分發）

團隊可在私有 repo 架市集，只讓組織成員存取。詳細機制見 [2]。

7. 裝後盤點 SOP：別只看 Quick Start

30 分鐘盤點流程裝完 plugin 後，依下列步驟做盤點。這是「裝完等於會用」與「裝完只啟動 20%」的差距所在。

讀 manifest

開 ~/.claude/plugins/<plugin-name>/.claude-plugin/plugin.json，記下 name、version、author、description、homepage（若有）。

列出所有元件

PLUGIN=~/.claude/plugins/<plugin-name>
echo "=== skills ==="
find "$PLUGIN/skills" -name "SKILL.md" 2>/dev/null
echo "=== commands ==="
ls "$PLUGIN/commands" 2>/dev/null
echo "=== agents ==="
ls "$PLUGIN/agents" 2>/dev/null
echo "=== hooks ==="
cat "$PLUGIN/hooks/hooks.json" 2>/dev/null
echo "=== mcp servers ==="
cat "$PLUGIN/.mcp.json" 2>/dev/null
echo "=== lsp servers ==="
cat "$PLUGIN/.lsp.json" 2>/dev/null
echo "=== monitors ==="
cat "$PLUGIN/monitors/monitors.json" 2>/dev/null
echo "=== bin ==="
ls "$PLUGIN/bin" 2>/dev/null
echo "=== settings ==="
cat "$PLUGIN/settings.json" 2>/dev/null

在 Claude Code 內確認

跑 /help，看 plugin 的 skill / command 列表（會帶 namespace 前綴）。跑 /agents，看 plugin 的 agent 是否有出現在 Library。在對話中問 Claude：「列出當前 session 啟用的 plugin 與其提供的 skill / MCP server」。

逐一讀 SKILL.md / agent.md / hooks.json

不要跳過。每個檔 30 秒掃過，知道它做什麼、什麼時候觸發、是否需要 arg、是否動態注入 shell 指令。對 hooks.json 每個 command 跑本單節後段的供應鏈掃描（rg 搜尋可疑字串）。

記下設定覆寫點

plugin 的 settings.json 寫了什麼（目前只 agent 與 subagentStatusLine）。plugin 的 MCP server 啟動時需要哪些環境變數（看 .mcp.json 的 env 欄位）。你自己的 settings.json 有沒有同名的設定會被 plugin 覆寫（plugin 內 settings.json 優先序規則見 [2]）。

這個盤點 SOP 暴露的常見盲點：裝完一個「看起來會做 code review」的 plugin，盤點後才發現它還內含一個 lint-on-save hook 在 PostToolUse: Write|Edit 觸發，Quick Start 沒提。

8. 完整配置：超越 Quick Start

Quick Start 通常只示範 1-2 個 happy path。進階設定常藏在細節裡。

8.1 環境變數與 secrets

Plugin 的 .mcp.json 與 monitors/monitors.json 常引用環境變數（${GITHUB_TOKEN} 等）。Quick Start 設最少必要項，你需要：

確認本機或 CI 環境有那些變數。
透過環境變數管理工具（1Password CLI、.env 與 direnv、雲端 secret manager）注入，不要 hardcode 在 plugin 設定檔；plugin 進版控。

8.2 同名 skill / command 衝突

Plugin 的 skill 一定 namespaced（/plugin-name:hello），但獨立配置（.claude/commands/）的同名 command 仍可能與 plugin 的 commands/<name>.md 衝突。優先序規則（截至 2026-06，詳細見 [2]）：

獨立配置優先（先載入、優先匹配）。
Plugin command 後載入。
同名時獨立配置勝出。

但若獨立配置被移除，plugin command 才生效。盤點時主動檢查這層：你的 .claude/commands/deploy.md 與某 plugin 的 commands/deploy.md 同名嗎？

8.3 Hook 執行順序

多個 hook 對同一事件觸發時，執行順序依設定位置（[1]）：settings.json 的 hook 優先，再來是 plugin 的 hooks/hooks.json。若多個 plugin 都有同 matcher 的 PostToolUse，全部依序跑。沒有去抖或優先序手動設定，若你的格式化 hook 與某 plugin 的格式化 hook 對同一檔重複處理，需要手動整合。

8.4 MCP server port 衝突

若兩個 plugin 都要在同一 port 起 server，後啟動的會 fail。檢查 plugin 的 .mcp.json：

command 是 node / python / npx 啟動，port 通常由 server 動態選，較少衝突。
若硬編 port（如 localhost:8080），手動改到不同 port。

8.5 模型選擇

部分 plugin 的 Subagent 預設繼承主對話模型。對重複性高的 worker（code formatter、test runner），把 frontmatter model: haiku 改掉能省下大量成本（見 04-5 Subagent）。

Plugin Subagent 改 frontmatter 是「分叉」你改了 plugin 內的 Subagent frontmatter，下次該 plugin 更新時你的改動會被覆蓋。長期做法：把整個 plugin fork 維護、或用獨立 Subagent 取代那個功能。

8.6 用 `claude plugin init` 起步

claude plugin init my-tool scaffold 一個 plugin 骨架到 ~/.claude/skills/my-tool/，含 .claude-plugin/plugin.json manifest 與 starter SKILL.md。下次 session 自動以 my-tool@skills-dir 載入，不需 marketplace 步驟（[1]）。

9. 版本管理

Plugin 兩種版本模式（[1]）：

模式	觸發	行為
顯式 `version`	該欄位變動	使用者只在新版本收到更新
隱式（git SHA）	省略 `version` 且走 git 分發	每次 commit 算新版本

省略 version 的代價對開發者方便，但你裝的 plugin 會「每次 commit 自動更新」。一次 breaking commit 進 main 就破壞你工作流。生產環境用顯式 version 鎖版。開發階段可省略。

更新策略：

Production 鎖版：固定 version 欄位，僅在 review PR 後 bump。
Dev 追蹤：省略 version、用 claude --plugin-dir 連到本地目錄。
團隊內部分發：透過私有市集 + git tag，CI bump 版本。

10. 從獨立配置遷移到 plugin

若你已經有 .claude/commands/、agents/、skills/，可遷移成 plugin（[1]）：

# 1. 建 plugin 結構
mkdir -p my-plugin/.claude-plugin
echo '{"name": "my-plugin", "description": "...", "version": "1.0.0"}' \
  > my-plugin/.claude-plugin/plugin.json

# 2. 複製元件
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

# 3. 遷移 hooks
mkdir my-plugin/hooks
# 從 .claude/settings.json 抄 hooks 區塊到 my-plugin/hooks/hooks.json
#（格式相同）

# 4. 測試
claude --plugin-dir ./my-plugin

# 5. 驗證每個元件：跑 skills、檢查 agents 出現、驗證 hooks 觸發

遷移後清掉原檔遷移完成、plugin 載入正常後，把原 .claude/ 內的對應檔刪除，避免重複載入 [1]。

11. 安全與評估

Plugin = 你不完全控制的程式碼進入工作環境。風險面：

11.1 供應鏈評估

維度	評估點
維護者	是誰？單人還是組織？社群評價？過去 commit 活躍度？
更新頻率	上次 commit 是何時？若 plugin 一年沒更新，套用前先測試
來源	從 `claude-plugins-official`、經審核的 `claude-community`、還是私人 git URL？信任程度差很多
程式碼審查	讀過 manifest 與每個 SKILL.md / hooks.json / .mcp.json 嗎？
已知漏洞	Snyk ToxicSkills（2026-02）研究指出公開 skill 中 36% 含 prompt injection [需確認原始出處]

11.2 引入前掃描

照 04-6 Hooks 的 SOP 對 hooks/hooks.json 與每個 SKILL.md 跑：

PLUGIN=~/.claude/plugins/<plugin-name>

# 1. 可疑外連
rg -n 'curl|wget|nc|ssh|ANTHROPIC_BASE_URL|enableAllProjectMcpServers' "$PLUGIN/"

# 2. 隱藏 Unicode
rg -nP '[\x{200B}-\x{200D}\x{202A}-\x{202E}]' "$PLUGIN/"

# 3. HTML 註解、script tag、base64
rg -n '<!--|<script|data:text/html|base64,' "$PLUGIN/"

# 4. 可疑權限或外連（重複確認）
rg -n 'curl|wget|nc|scp|ssh|enableAllProjectMcpServers|ANTHROPIC_BASE_URL' "$PLUGIN/"

任何 hit 都要人工 review 上下文再決定裝不裝。

11.3 限縮 plugin 權限

裝完後若不放心它的 hook 或 MCP 權限：

停用全部 hooks：settings.json 設 "disableAllHooks": true（plugin 內 hook 也一起停；managed 級 hook 不受影響）[1]。
deny 特定 MCP server：在 settings.json 的 permissions.deny 設。
fork plugin：把整個 plugin 複製到本地、移除你擔心的部分、改 name 為 <name>-local，用 claude --plugin-dir 載入。

11.4 與 03-1 評估框架連動

引入 plugin 前跑 03-1 評估框架：

這個 plugin 解決的問題，是我工作流裡真實的高頻痛點嗎？還是 Quick Start 看起來酷？
試用一個禮拜：實際上每天叫用幾次？省下的時間是否值得引入的供應鏈風險？
有沒有更小、更可信的替代方案（例如只裝 plugin 的一個 skill，獨立配置）？

不要照 Quick Start 評估，那只是「最短路徑示範」，不是「值得裝的理由」。

12. 工具對照

各家「plugin / 擴充包」機制在名稱與架構上差異顯著（截至 2026-06）：

概念	Anthropic Claude（主範本）	OpenAI Codex	Google Antigravity	GitHub Copilot CLI	Cursor（短提）
擴充包單位	Plugin（manifest + skills/agents/hooks/mcp/lsp/monitors/bin/settings）	Codex extension（`config.toml` + `extensions/<name>/`）[需確認原始出處]	Antigravity extension（`~/.gemini/antigravity/extensions/`）[需確認原始出處]	Copilot Extensions（GitHub Marketplace 上的第三方 app）[需確認原始出處]	Cursor extensions（`.cursor/extensions/`）[需確認原始出處]
命名空間	必加 namespace（`/plugin-name:hello`）	設定式	設定式	無 namespace	設定式
安裝方式	`claude --plugin-dir`、`/plugin install`、市集	`codex extension install` [需確認原始出處]	設定式	Marketplace UI	設定式
列出已安裝	`/plugin` 指令、檔案系統掃描	`codex extension list` [需確認原始出處]	設定式	設定式	設定式
設定覆蓋點	`settings.json`（plugin 啟用時套用）、`hooks/hooks.json`、`monitors/monitors.json`	設定式	設定式	設定式	設定式
安全掃描機制	無內建；手動 `rg` 掃	設定式	設定式	設定式	設定式
公開市集	`claude-plugins-official`（預設啟用）+ `claude-community`（使用者加入）	（無統一公開市集，需查證）[需確認原始出處]	設定式	GitHub Marketplace	設定式
版本管理	顯式 `version` 或 git commit SHA	設定式	設定式	設定式	設定式

命名澄清Claude Code plugin 與「Copilot Extensions」是不同東西：前者是本機 CLI 的目錄式擴充；後者是 GitHub Marketplace 上的第三方 app，通常整合雲端服務（issue tracker、CI 平台、雲端 provider）。本表只比較同類機制。OpenAI Codex、Antigravity、Cursor 的 plugin / extension 機制在命名與架構上各異；上表「需確認原始出處」項目需查證。Cursor 為第三方 IDE（Anysphere），本 Playbook 僅短提一欄。

13. 自我檢核動手做

30 分鐘練習

盤點現有 plugin：用本單節的 find / cat SOP 對你最常用的 plugin 跑一次；列出它實際提供的 5 個元件（含 Quick Start 沒提的），以及每個元件觸發時機。
安全掃描：對同一 plugin 跑 rg 掃描（4 條指令），把所有 hit 記下來並人工 review 上下文。
本機開發測試：在 ~/playground/my-test-plugin/ 建一個空 plugin（claude plugin init my-test-plugin），加一個 SKILL 與一個 PostToolUse hook，用 claude --plugin-dir 載入測試，觀察 namespace 與 hook 觸發。
fork 一個現成 plugin：把某個你裝的 plugin 從 ~/.claude/plugins/ 完整複製到本地目錄，移除 hook 區塊，改 name 為 <原名>-no-hooks，用 claude --plugin-dir 載入驗證 hooks 沒跑。
提交前驗證：若你寫了 plugin 想要 submit 到 claude-community，先跑 claude plugin validate 跑過自動檢查。

14. 常見誤區

反模式清單

把 Quick Start 當完整文件：Quick Start 只是最短路徑示範，plugin 真正的能力集合通常大得多。不盤點就以為「裝完等於會用」。
沒盤點 hook 就啟用 plugin：hook 會在每次對應工具呼叫時自動執行，裝進未審查的 hook 等於讓陌生程式碼常態跑在你的工作環境。
把 plugin 衝突歸咎於「模型行為異常」：同名 skill 覆蓋、hook 執行序衝突等問題都是可排查的確定性問題，不是隨機性。
省略 version 給生產環境用：每次 commit 算新版本，main 分支上不小心壞了你就跟著壞。
把 plugin 內 SKILL.md / agent.md 當成「進版控但不會動」：plugin 更新時你的 .claude/ 內 fork 版本會被覆蓋。要長期改須 fork 自己維護。
裝多個 plugin 各自管同類 lint / format hook：每次 Write / Edit 觸發多個 hook 疊加執行，浪費資源。整合到一個自製 plugin 或關掉多餘的。
從私人 URL 裝 plugin 沒先讀原始碼：claude --plugin-url 載入 CI artifact 是方便，但對私人 URL 一律先讀原始碼、跑 rg 掃描。

自我檢核

通過本單元的標準

你能說出 plugin 打包的 9 種元件嗎（skills、commands、agents、hooks、.mcp.json、.lsp.json、monitors、bin/、settings.json），以及各自的作用？
你能不看 Quick Start，只從 plugin 目錄結構列出它安裝的全部元件、每個元件的作用，以及它在 settings.json 裡寫入了什麼嗎？
你能區分 claude --plugin-dir / --plugin-url / /plugin install 三條安裝路徑的使用時機嗎？
你能在裝一個新 plugin 之前，列出至少三條供應鏈評估問題與掃描指令嗎？
若 plugin 與你既有 .claude/ 設定衝突，你能說出至少兩條排查路徑嗎？

來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

[1] Anthropic, “Create plugins,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugins （截至 2026-06；含目錄結構、manifest schema、4 條安裝路徑、claude-plugins-official 與 claude-community 兩個市集、--plugin-dir / --plugin-url 差異）
[2] Anthropic, “Plugins reference,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugins-reference （截至 2026-06；完整 schema、版本管理、private marketplace、subagent 限制三欄位）
[3] Anthropic, “Discover and install plugins,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/discover-plugins （截至 2026-06；市集瀏覽與安裝流程）
[4] Anthropic, “Create and distribute a plugin marketplace,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugin-marketplaces （截至 2026-06；私有市集與 CI/CD 整合）
[5] Anthropic, “Hooks,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/hooks （截至 2026-06；plugin hooks/hooks.json 與 settings.json 同 schema）

設定層級模型見 02-1 設定的層級模型。
Skill 撰寫與 progressive disclosure 見 04-4 Skill。
Subagent frontmatter 見 04-5 Subagent。
Hook 觸發事件與 command handler 見 04-6 Hooks。
MCP server 設定見 04-9 MCP 整合。
評估框架見 03-1 如何判斷工具與 Skill 是否適合自己。
供應鏈風險見 03-3 安全、隱私與供應鏈風險。

​學習目標

​1. Plugin 是什麼：打包成一包的能力集合

​2. Plugin 與獨立 .claude/ 配置的差別

​3. 目錄結構

​4. Manifest：.claude-plugin/plugin.json

​5. 各元件怎麼放

​5.1 Skills

​5.2 Commands

​5.3 Agents

​5.4 Hooks

​5.5 MCP servers

​5.6 LSP servers

​5.7 Monitors

​5.8 bin/

​5.9 預設 settings

​6. 安裝：四條路徑

​6.1 本機開發模式

​6.2 從市集安裝

​6.3 兩個公開市集

​6.4 Private 市集（團隊內部分發）

​7. 裝後盤點 SOP：別只看 Quick Start

​8. 完整配置：超越 Quick Start

​8.1 環境變數與 secrets

​8.2 同名 skill / command 衝突

​8.3 Hook 執行順序

​8.4 MCP server port 衝突

​8.5 模型選擇

​8.6 用 claude plugin init 起步

​9. 版本管理

​10. 從獨立配置遷移到 plugin

​11. 安全與評估

​11.1 供應鏈評估

​11.2 引入前掃描

​11.3 限縮 plugin 權限

​11.4 與 03-1 評估框架連動

​12. 工具對照

​13. 自我檢核動手做

​14. 常見誤區

​自我檢核

​來源與延伸閱讀

學習目標

1. Plugin 是什麼：打包成一包的能力集合

2. Plugin 與獨立 `.claude/` 配置的差別

3. 目錄結構

4. Manifest：`.claude-plugin/plugin.json`

5. 各元件怎麼放

5.1 Skills

5.2 Commands

5.3 Agents

5.4 Hooks

5.5 MCP servers

5.6 LSP servers

5.7 Monitors

5.8 bin/

5.9 預設 settings

6. 安裝：四條路徑

6.1 本機開發模式

6.2 從市集安裝

6.3 兩個公開市集

6.4 Private 市集（團隊內部分發）

7. 裝後盤點 SOP：別只看 Quick Start

8. 完整配置：超越 Quick Start

8.1 環境變數與 secrets

8.2 同名 skill / command 衝突

8.3 Hook 執行順序

8.4 MCP server port 衝突

8.5 模型選擇

8.6 用 `claude plugin init` 起步

9. 版本管理

10. 從獨立配置遷移到 plugin

11. 安全與評估

11.1 供應鏈評估

11.2 引入前掃描

11.3 限縮 plugin 權限

11.4 與 03-1 評估框架連動

12. 工具對照

13. 自我檢核動手做

14. 常見誤區

自我檢核

來源與延伸閱讀