Claude Code plugin 是什麼？安裝位置與費用

Claude Code plugin 是什麼

Claude Code plugin 是由一個目錄組成的元件集合，Claude Code 會將其載入並視為單一單位管理。這些元件包括 skills、agents、hooks、MCP servers、LSP servers 和 background monitors。安裝 plugin 會一次加入其中的所有元件，並以同一個名稱管理；停用 plugin 也會以相同方式移除這些元件。

plugin 不會賦予 agent 原本不具備的任何能力。plugin 內的每個元件，都可以手動寫入 .claude/ 目錄。plugin 是封裝層：可用來為這些元件建立版本、交付給 15 個人，並在日後更新，而不必要求每個人自行複製檔案。這就是 plugin 的完整概念。多數對 plugin 的誤解，源自將其視為一種新的能力類型。

.claude-plugin/plugin.json 中的選用 manifest 會指定 plugin 的名稱，而該名稱會成為 namespace。名為 commit-commands 的 plugin 中，某項 skill 的呼叫方式是 /commit-commands:commit。因此，兩個 plugin 都可以提供名為 commit 的 skill，且彼此不會互相遮蔽。plugin agents 在 @-mention 清單中的作用域也採用相同方式，例如 plugin-name:agent-name。

Plugin、skill、MCP server 或規則檔案

這 4 個詞常被當成彼此競爭的選項。其實並不是，這裡一次說明它們的界線。

• skill 是 Claude 在工作需要時載入的單一指示單位。請參閱 Agent Skill 的實際定義。
• MCP server 是獨立的程序，透過通訊協定向 agent 提供工具，通常是由你自行執行的網路服務。
• 例如 CLAUDE.md 這類規則檔案是專案內容，會在工作階段開始時讀取，並套用到所有內容。
• plugin 是可將 skills、agents、hooks 與 MCP server 定義集中在一起的容器，另包含版本號碼與發佈管道。

因此，plugin 要回答的問題不是「agent 能做什麼」，而是「我要如何將這些內容交付給團隊，並在下個月更新」。如果你是在前 3 者之間做選擇，skills、MCP servers 與規則檔案的比較 會詳細說明這項決策。如果你關注的是 MCP 部分，在 VPS 上執行自己的 MCP servers 會說明主機代管方式。

插件存放位置與內容

從 marketplace 安裝的 plugin 會複製到 ~/.claude/plugins/cache 的本機快取，而不是從原始複製位置執行。每個已安裝版本都有自己的目錄。更新或解除安裝時，舊版本目錄會標記為孤立目錄，約 2 週後刪除。因此，已載入舊版本的工作階段仍可繼續執行，不會在工作中途失敗。

由於路徑會在每次更新時變更，plugin 絕不能將自身位置寫死。plugin 內的 hooks 和 MCP 設定使用 ${CLAUDE_PLUGIN_ROOT}，此變數會解析為目前的安裝目錄。必須在更新後保留的狀態，應放在 ${CLAUDE_PLUGIN_DATA}；此變數會解析為 ~/.claude/plugins/data/ 下的穩定目錄。

快取只會複製 plugin 自己的目錄，因此會產生一個常在後期才發現的問題。指向 plugin 根目錄以外位置的路徑，例如 ../shared-utils，在使用本機路徑開發時可以運作，但安裝後會失效，因為這些檔案從未被複製。

目錄結構如下。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

只有 plugin.json 會放在 .claude-plugin/ 內。其他內容都位於 plugin 根目錄。將 skills/ 或 hooks/ 放在 .claude-plugin/ 內，是 plugin 能順利安裝卻完全沒有作用的最常見原因：Claude Code 會在根目錄尋找這些目錄，但找不到任何目錄，於是載入沒有元件的 plugin。

manifest 本身很小。

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

如何安裝 Claude Code plugin

安裝分為兩個步驟，第一個步驟不會安裝任何內容。您要先加入 marketplace，也就是 plugin 的目錄，再從中安裝個別 plugin。Anthropic 的官方 marketplace claude-plugins-official 會在您第一次以互動方式啟動 Claude Code 時自動註冊。其他 marketplace 則需自行加入。

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

請注意，repository 是 anthropics/claude-code，但 marketplace 名稱是 claude-code-plugins。名稱來自 repository 內的 catalog file，而不是 repository path。因此，請先從 /plugin 的 Marketplaces tab 讀取 marketplace 名稱，再輸入安裝指令。

安裝完成後，請查看摘要列。Plugin is now active. 表示元件已在本次 session 載入。Run /reload-plugins to activate. 表示尚未載入，您需要執行該指令。如果 /reload-plugins 警告重新讀取對話內容，請改以 /reload-plugins --force 重新執行。接著確認 plugin 確實存在：/plugin 會在 Installed tab 顯示該 plugin，/help 會在 Custom commands 列出其 skills，而任何載入失敗的項目都會出現在 Errors tab，並附上原因。

安裝時需要指定 scope，而 scope 會決定哪些人能取得該 plugin。User scope 表示您本人，且適用於每個 project。Project scope 會將 plugin 寫入 repository 的 .claude/settings.json 中的 enabledPlugins，因此所有 clone 該 repository 的人都會收到該 plugin 的安裝提示。Local scope 表示只有您本人能在此 repository 中使用。

如果要執行 script、Dockerfile，或在無法使用互動面板的 session 中操作，請改用 shell form。除非傳入 --scope，否則它會安裝至 user scope。

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install 會在 session 外執行，因此已開啟的 session 不會立即看到新的 plugin。您必須執行 /reload-plugins，或啟動新的 session。

在這兩種介面中，管理現有項目的方式相同。/plugin list 會列出已安裝的項目，並接受 --enabled 或 --disabled。/plugin disable name@marketplace 會停用 plugin，但不會移除它；/plugin enable 會重新啟用它；/plugin uninstall 會將它移除。斜線指令形式會開啟 plugin 面板來套用變更，因此在 script 中應使用 claude plugin ... shell 對應指令。

若要將 marketplace 提供給整個團隊，請將它放入 project 的 .claude/settings.json。成員信任該 repository folder 後，系統會提示他們進行安裝。

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

在建置自己的 plugin 時，請完全略過 marketplace。claude --plugin-dir ./my-plugin 會為該 session 載入一個 directory，/reload-plugins 會在不重新啟動的情況下套用您的編輯內容，而 claude plugin validate ./my-plugin 會在其他人使用前檢查 manifest、skill 和 agent frontmatter，以及 hooks/hooks.json。

Claude Code 外掛的成本是多少？

機制本身免費。截至 2026 年 8 月，新增 marketplace、安裝外掛或讓外掛保持啟用，都不會收取費用。官方與社群 marketplace 都是公開的 git repository，而外掛則是一個文字檔案目錄。

外掛實際消耗的是 token；訂閱方案用量或 API 帳單衡量的也是 token。外掛會從哪一種用量中扣除，取決於你原本採用哪種方式支付工具費用；Claude Code 各方案的費用會將訂閱層級與按 token 計價的 API 費用並列說明。這項成本有 3 種來源，行為也各不相同。

持續性內容成本。 外掛提供的內容會放在你的內容視窗中，並在工作階段的每一輪重新讀取。安裝前，/plugin 詳細檢視畫面會顯示以 token 計算的 Context cost 估算值，以及 Will install 區段，列出即將新增的 commands、skills、agents、hooks，以及 MCP 和 LSP servers。請同時查看這兩項資訊。本機或自訂 marketplace 的外掛可能不提供這些資料，這時只能自行估算。包含 MCP server 的外掛通常最耗用內容空間，因為工具定義很大。不過，支援 MCP tool search 的模型會延後載入這些定義，直到需要使用工具時才載入。

呼叫成本。 執行外掛的 skill 時，該 skill 的指示會附加到對話中，因此只有在使用時才會支付 skill 內容的成本。不過，skill 本體的成本通常較低；skill 指示 agent 執行的工作則不一定如此：unlazy skill 的 Depth Tree 方法幾乎會把所有 token 用在它強制 agent 執行的額外處理階段，而不是你安裝的檔案。agent 的情況不同。subagent 會以自己的 system prompt 和 cache 執行獨立對話，開始時沒有任何 cache 命中。因此，會建立 agents 的外掛，其成本可能遠高於內容估算值所顯示的結果。

Cache 成本。 在工作階段中途啟用或停用外掛，可能會導致下一個請求重新處理整個對話。Skills、commands、agents、hooks、LSP servers、monitors 和 themes 都不會造成這種情況：它們新增的內容會附加在既有歷史之後，因此下一個請求只需支付新內容的成本，並從 cache 讀取之前的內容。例外是提供 MCP server 的外掛。如果其工具由 tool search 延後載入，cache 會保留。如果工具載入 prompt prefix，下一個請求就會將整個對話重新視為未快取輸入而讀取。這正是 /reload-plugins 會發出警告並在你傳入 --force 前拒絕執行的原因。

你可以直接觀察這些變化，不必自行猜測。每個 API 回應都會回報 cache_read_input_tokens 和 cache_creation_input_tokens，而顯示即時 token 用量的自訂 statusline會將兩者直接呈現在你面前。健康的工作階段，讀取的內容通常遠多於建立的內容。如果建立量在每一輪都持續偏高，表示 prefix 中有內容在每一輪變更。若要了解哪些內容正在填滿視窗，請參閱如何管理 Claude Code 內容視窗和這些 token 計數的實際意義。

有一項整理工作值得定期執行。Installed 分頁會將至少 2 週未使用的外掛歸入 Not used recently 標題下，詳細檢視畫面也會顯示 Last used 行。這些外掛仍會在每個工作階段消耗啟動時間與內容空間。請停用或解除安裝它們。

外掛會以你的權限執行

Anthropic 的官方文件對此說得很直接：外掛與市集是高度受信任的元件，可以使用你的使用者權限，在電腦上執行任意程式碼。這不是假設情境。外掛的 hooks 會在工作階段事件發生時執行 shell 命令，包括工具呼叫前後。啟用外掛期間，其 bin/ 目錄會加入 Bash 工具的 PATH。外掛啟動的 MCP server 也都是由它建立的程序。這些內容都不會與你的使用者帳號隔離在 sandbox 中。

在筆記型電腦上，風險通常受限於桌面使用者可存取的範圍。在伺服器上通常不是如此。執行 agent 的帳號通常持有 SSH 金鑰、部署權杖、雲端 CLI 工作階段，以及 Docker socket 的存取權，因此「以你的使用者身分執行任意程式碼」實際上等同於控制這台機器。如果 Claude Code 執行於 VPS，請先閱讀 如何在 VPS 上安全執行 Claude Code，再安裝任何內容；如果要安裝會與外部服務通訊的外掛，請先閱讀 如何讓 agent 無法存取認證資料。其他 harness 在同一台租用的主機上也會遇到相同限制，因此 值得安裝的 DeepSeek Harness 外掛 多半是支出上限、工具權限規則與 injection 掃描，而不是新增功能。

確實存在一些防護措施，了解其範圍很有幫助。專案範圍的外掛來自 repository，而不是由你提供，因此只有在你信任該 workspace 後才會載入；其 MCP server 仍需要逐一核准；其 LSP server 會等到取得該信任；其背景監控程式則完全不會載入。外掛附帶的 agent 不得宣告 hooks、MCP server 或 permission mode。市集外掛會複製到 cache；若其中的 symlink 指向市集外部，則會被略過，因此外掛無法載入主機上的任意檔案。

這些措施都不能取代你閱讀所安裝的內容。檢查 Will install 清單，優先選擇你能開啟並閱讀原始碼的外掛，將團隊使用的外掛放在由你控制的 marketplace repository 中，並對你自行撰寫的任何內容執行 claude plugin validate。

FAQ

Claude Code 外掛需要額外付費嗎？

不需要。外掛系統、加入 marketplace，或安裝外掛都不收費。費用來自 token 使用量，會像其他 context 一樣，計入你的方案或 API 支出。外掛會在每一輪加入固定的 context；呼叫其中一個 skill 或 agent 時，還會加入更多內容。如果外掛提供 MCP server，且其工具會載入 prompt prefix，還可能強制執行一次昂貴的未快取回合。安裝前，/plugin 詳細檢視畫面會顯示 Context cost 估算值。

外掛和 skill 有什麼差異？

skill 是單一指令單位。外掛則是可包含 skill、agent、hook、MCP server、LSP server 和 monitor 的套件，並具有名稱、版本，以及可供安裝的 marketplace。如果 skill 只供你和這個專案使用，請在 .claude/ 中撰寫獨立的 skill。像 Ponytail，讓 agent 優先採用能運作的最小變更 這類單一用途 skill，就是最明確的例子：它原本只是一個包含一項規則的檔案，直到團隊也需要使用它為止。當其他人也需要使用，且它需要持續更新時，請將它轉換為外掛。外掛中的 skill 具有命名空間，因此其中的 skill 會以 /plugin-name:skill-name 而不是 /skill-name 的形式呼叫。

我的外掛已安裝，但其中的 skill 沒有出現。問題在哪裡？

先查看安裝摘要。如果摘要顯示 Run /reload-plugins to activate.，表示元件尚未載入；如果重新載入時警告會重新讀取對話，請以 /reload-plugins --force 重新執行。如果元件已載入但沒有顯示內容，請開啟 /plugin 並閱讀 Errors 分頁。最常見的結構錯誤，是將 skills/、agents/ 或 hooks/ 放在 .claude-plugin/ 內，而 Claude Code 不會在該處尋找這些項目。請記住，外掛中的 skill 具有命名空間，因此你要在 /help 的 Custom commands 分頁中尋找 /plugin-name:skill-name。最後才使用 rm -rf ~/.claude/plugins/cache，重新啟動後再重新安裝。

不使用互動面板也能安裝外掛嗎？

可以。使用 shell 指令 claude plugin install name@marketplace；除非傳入 --scope project 或 --scope local，否則它會安裝到使用者範圍。這個指令可用於 script、image 和無法使用 /plugin 面板的非互動環境。由於它會在 session 外執行，已開啟的 session 必須先執行 /reload-plugins，外掛才會生效。

從我在 GitHub 找到的 marketplace 安裝外掛安全嗎？

請將它視為以目前使用者身分執行該 repository 的安裝 script，因為實際情況與此相近。外掛可透過 hook 執行 shell 指令、將可執行檔加入 Bash 工具的 PATH，並啟動 MCP server；這些操作都會使用你的使用者權限。Anthropic 不會控制或驗證第三方外掛的內容。請從可閱讀原始碼的來源安裝，確認前先檢視 Will install 清單。在 server 上應比在 laptop 上採取更嚴格的標準，因為 server 上的帳號通常持有值得竊取的 key 和 token。