Claude Code 外掛程式是什麼?費用與運作機制解析
Claude Code 外掛程式是封裝技能、MCP 與代理的容器,本身不收費,僅需支付執行時的 Token 費用。本文解析其安裝方式、元件結構及與規則檔案的區別。
什麼是 Claude Code 外掛程式
Claude Code 外掛程式是一個包含多個元件的目錄,由 Claude Code 作為單一單元進行載入與管理。其主要元件包括技能 (skills)、代理 (agents)、掛鉤 (hooks)、MCP 伺服器、LSP 伺服器以及背景監控程式;外掛程式亦可包含指令、輸出樣式、主題、工作流程以及一個 bin/ 可執行檔目錄。安裝外掛程式會一次性新增其所有組成部分,並統一命名;停用時則會一併移除。
外掛程式本身通常不會賦予代理原本不具備的能力。技能、代理、掛鉤與 MCP 伺服器皆可透過手動方式編寫於 .claude/ 目錄中。唯一的例外是程式碼智慧分析所需的語言伺服器以及 mods,這些僅能透過 Claude Code 從外掛程式中載入。對於其他功能而言,外掛程式僅作為封裝層:它提供了一種對這些元件進行版本控制、分發給多人使用,並在後續更新時無需要求他人手動複製檔案的方法。這就是外掛程式的核心概念,大多數關於外掛程式的困惑,皆源於誤將其視為一種全新的能力類型。
位於 .claude-plugin/plugin.json 的選用清單檔案 (manifest) 用於定義外掛程式名稱,該名稱將成為一個命名空間。位於名為 commit-commands 外掛程式中的技能,其呼叫方式為 /commit-commands:commit,因此兩個不同的外掛程式皆可提供名為 commit 的技能,而不會發生名稱衝突。外掛程式代理在 @-mention 清單中的作用域亦採用相同方式,顯示為 plugin-name:agent-name。
Plugin、skill、MCP server 或 rules file
這 4 個詞常被當成彼此競爭的選項。實際上並非如此,這裡一次說明它們的界線。
- skill 是 Claude 在工作需要時載入的一個指示單位。請參閱 Agent Skill 的實際定義。
- MCP server 是透過通訊協定向 agent 提供工具的獨立程序,通常是由你自行執行的網路服務。
- 例如
CLAUDE.md這類 rules file 是在工作階段開始時讀取的專案內容,並套用到所有工作。 - plugin 是由 skills、agents、hooks、MCP servers 或其他元件組成的目錄,Claude Code 會將其作為一個單位安裝並載入。其選用的 manifest 可為 plugin 指定名稱,並加入版本、說明及其他中繼資料。發佈不屬於 plugin 的一部分:marketplace 是獨立的目錄,用來列出 plugins 以及各自的取得來源。
因此,plugin 回答的問題不是「agent 能做什麼」,而是「如何將這些內容提供給團隊,並在下個月更新」。如果你正在前 3 者之間做選擇,skills、MCP servers 與 rules files 的比較會詳細說明這項決策。如果你關注的是 MCP 部分,在 VPS 上執行自有的 MCP servers會說明託管方式。
外掛程式的存放位置與內容
大多數 marketplace 外掛程式會複製到 ~/.claude/plugins/cache 的本機快取中,每個已安裝版本各自使用一個目錄。從本機路徑加入 marketplace 後,其中使用相對路徑的外掛程式會在原位置載入;使用 link mode 的 command-source 外掛程式則會透過連結載入其來源目錄。更新或解除安裝複製的外掛程式時,舊版本目錄會標記為 orphaned,並在約兩週後刪除。因此,已載入舊版本的工作階段仍可繼續執行,不會在工作中途失敗。只有在至少還有一個外掛程式安裝紀錄存在時,才會執行清理;解除安裝最後一個外掛程式後,orphaned 目錄會保留,直到再次安裝外掛程式。
複製的外掛程式每次更新後路徑都會變更,因此外掛程式絕對不可將自己的位置寫死。外掛程式內的 hooks 與 MCP 設定使用 ${CLAUDE_PLUGIN_ROOT},此變數會解析為目前的安裝目錄。必須在更新後保留的狀態應放在 ${CLAUDE_PLUGIN_DATA},此變數會解析為 ~/.claude/plugins/data/ 下的固定目錄。
對於複製的外掛程式,只有外掛程式本身的目錄會複製到快取;同一 marketplace 中位於其他位置的 symbolic link 目標則會複製到對應位置。開發時使用本機路徑,讀取外掛程式根目錄以外路徑的指令碼(例如 ../shared-utils)可以正常運作;但外掛程式複製到快取後便會失效,因為這些檔案從未被複製。若在 plugin.json 中以這種方式宣告 component path,則會更早失敗:Claude Code 在開發階段也會拒絕任何超出外掛程式根目錄的 component path,並顯示 path escapes plugin directory 錯誤。
目錄結構如下。
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── code-review/
│ └── SKILL.md
├── agents/
├── hooks/
│ └── hooks.json
├── .mcp.json
└── bin/只有 plugin.json 會放在 .claude-plugin/ 內。其他所有內容都位於外掛程式根目錄。將 skills/ 或 hooks/ 放在 .claude-plugin/ 內,是外掛程式能順利安裝卻完全沒有作用的最常見原因:Claude Code 會在根目錄尋找這些目錄,但找不到任何目錄,因此載入沒有 components 的外掛程式。
manifest 本身很簡短。
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0"
}如何安裝 Claude Code 外掛程式
安裝分為兩個步驟,且第一個步驟不會安裝任何內容。您要先新增 marketplace,也就是外掛程式目錄,再從中安裝個別外掛程式。除非受管理原則或 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL 阻擋,否則您第一次以互動方式啟動 Claude Code 時,Anthropic 的官方 marketplace claude-plugins-official 會自動為您註冊。其他 marketplace 則需自行新增。
/plugin marketplace add anthropics/claude-plugins-official
/plugin install commit-commands@claude-plugins-officialmarketplace 名稱來自儲存庫內的目錄檔案,不是儲存庫路徑。因此,請先從 /plugin 的 Marketplaces 分頁讀取 marketplace 名稱,再輸入安裝命令。anthropics/claude-code 中舊的 claude-code-plugins marketplace 已淘汰;新的安裝請使用 claude-plugins-official。來自該舊 marketplace 的現有外掛程式會從官方儲存庫更新,因此不需要只為了變更 marketplace 而重新安裝 commit-commands。
安裝後,請閱讀摘要行。Plugin is now active. 表示元件已在目前工作階段載入。Run /reload-plugins to apply. 表示元件未在安裝期間啟用;面板會關閉,Claude Code 會代您執行重新載入。如果重新載入時警告會重新讀取對話內容,外掛程式會維持待處理狀態,您可以重新執行 /reload-plugins --force。接著確認外掛程式確實存在:/plugin 會在 Installed 分頁中顯示該外掛程式,輸入 / 會將其技能列為 /plugin-name:skill-name,而任何載入失敗的項目都會顯示在 Errors 分頁中,並附上原因。
安裝時會要求選擇範圍,而範圍決定哪些人能取得外掛程式。使用者範圍只套用於您,且涵蓋每個專案。專案範圍會將外掛程式寫入儲存庫的 .claude/settings.json 中的 enabledPlugins,讓所有複製該儲存庫的人都能啟用它。但這不會替他們下載外掛程式:每位協作者仍須在自己的電腦上安裝一次,例如執行 claude plugin install name@marketplace --scope project;除非 marketplace 項目是相對路徑,或 seed directory 已經包含該外掛程式。Local 範圍只套用於您在此儲存庫中的使用情境。
對於 script、Dockerfile,或任何無法使用互動式面板的工作階段,請改用 shell 形式。除非傳入 --scope,否則它會安裝到使用者範圍。在尚未有人開啟互動式工作階段的電腦上,官方 marketplace 尚未註冊,因此請先新增它。
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official --scope project
claude plugin listclaude plugin install 會在工作階段外執行,因此已開啟的工作階段不會立即看到新的外掛程式。請執行 /reload-plugins,或啟動新的工作階段。
在這兩個位置管理現有項目的方式相同。/plugin list 會列出已安裝的項目,並接受 --enabled 或 --disabled。/plugin disable name@marketplace 會停用外掛程式但不移除它,/plugin enable 會重新啟用它,而 /plugin uninstall 會移除它。斜線命令形式會開啟外掛程式面板以套用變更,因此在 script 中應使用 claude plugin ... 的 shell 等效命令。
若要將 marketplace 提供給整個團隊,請將它放入專案的 .claude/settings.json,或執行一次 claude plugin marketplace add your-org/claude-plugins --scope project,再提交它寫入的檔案。Claude Code 會在每位成員信任該儲存庫資料夾後,為其註冊 marketplace。
{
"extraKnownMarketplaces": {
"my-team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}在建置自己的外掛程式時,可以完全略過 marketplace。claude --plugin-dir ./my-plugin 會將目錄載入目前工作階段,/reload-plugins 會在不重新啟動的情況下套用您的修改,而 claude plugin validate ./my-plugin 會檢查 manifest、skill 和 agent frontmatter,以及 hooks/hooks.json,再讓其他人使用。分享外掛程式也不需要 marketplace:您可以將資料夾或其 .zip 傳給其他人,讓對方使用 --plugin-dir 載入;但在您提供新副本前,對方不會取得更新。
Claude Code plugin 的費用是多少?
機制本身免費。截至 November 2026,新增 marketplace、安裝 plugin 或維持 plugin 啟用都不收費。官方與社群 marketplace 都是公開的 git repository,而 plugin 則是一個文字檔案目錄。
plugin 真正消耗的是 tokens;subscription 用量或 API 帳單實際計算的也是 tokens。plugin 會消耗哪一種額度,取決於你原本採用哪種方式支付工具費用;各方案的 Claude Code 費用會將 subscription 層級與按 token 計費的 API 價格並列說明。這項費用有 3 種來源,行為也各不相同。
持續性 context 成本。 每個啟用的 plugin 都會將 Claude 可自行呼叫的 skills、agents 和 commands 名稱與說明加入 context;不論實際是否執行,每一輪 session 都會重新讀取這部分內容。並非每個元件都會消耗 tokens:hook 由 harness 執行,不會增加模型的 context。安裝前,/plugin 詳細檢視畫面會顯示 Will install 區段,列出即將新增的 commands、skills、agents、hooks,以及 MCP 和 LSP servers。對於 Anthropic 官方 marketplace 中的 plugin,只要你透過 marketplace 名稱或 Marketplaces tab 開啟 plugin,而不是從 Discover 清單開啟,畫面也會顯示 Context cost 區段,其中包含 Every turn 與 When invoked 預估值。請一併查看這兩個區段。來自自有或第三方 marketplace 的 plugin 不會有 Context cost 區段,但你不必手動估算:在 shell 中執行 claude plugin details name,即可查看任何已載入 plugin 的 Always-on token 數值與各元件明細,包括透過 --plugin-dir 傳入的 plugin。因此,你可以先 clone repository,再執行 claude --plugin-dir ./that-plugin plugin details that-plugin,不必安裝即可取得估算值。這個數值不包含 MCP servers。內含 MCP server 的 plugin 通常最耗用資源,因為 tool definitions 很大;不過,在支援 MCP tool search 的模型上,這些 definitions 會延後到需要使用 tool 時才載入。在啟用該 plugin 的 session 中執行 /context,查看 MCP tools 行即可了解它們增加的內容。
呼叫成本。 執行 plugin 的 skill 時,其 instructions 會附加到對話中,因此只有使用 skill 時才會支付 skill body 的成本。不過,body 只是成本較低的部分;skill 要求 agent 執行的工作可能很耗用 tokens。例如,unlazy skill 的 Depth Tree 方法幾乎將所有 tokens 都花在強制 agent 在允許將 task 判定為完成前執行額外檢查,而不是花在你安裝的檔案上。agent 則有所不同。subagent 會以自己的 system prompt 和 cache 執行獨立對話,開始時沒有任何 cache hits。因此,會產生 agents 的 plugin,其成本可能遠高於 context estimate 所顯示的數值。
Cache 成本。 在 session 中途啟用或停用 plugin,可能會迫使下一個 request 重新處理整段對話。Skills、commands、agents、hooks、monitors 和 themes 都不會造成這種情況:它們新增的內容會附加在既有 history 之後,因此下一個 request 只需支付新內容的成本,先前內容仍會從 cache 讀取。例外是提供 MCP server 的 plugin,以及提供 code intelligence plugin 的 plugin;後者的 language server 會提供 Claude 使用的 LSP tool。MCP 的行為取決於 tool search:如果 tools 延後載入,cache 會保留;如果 tools 載入 prompt prefix,下一個 request 就會將整段對話重新視為未快取的 input。這正是 /reload-plugins 會在 MCP tools 或 LSP tool 的變更可能破壞 cache 時發出警告並拒絕變更的原因,除非你傳入 --force。
你可以直接監看這些數值,而不必猜測。每個 API response 都會回報 cache_read_input_tokens 與 cache_creation_input_tokens,而顯示即時 token 用量的自訂 statusline會將兩者呈現在你面前。健康的 session 讀取量會遠高於產生量。如果產生量連續多輪都偏高,表示 prefix 中有內容在每一輪變更。若要了解哪些內容正在填滿 window,請參閱如何管理 Claude Code context window以及這些 token 計數實際代表什麼。
有一項維護工作能回收自身成本。Installed tab 會將至少 14 天且 10 個 sessions 未使用的 marketplace-installed plugins,歸在 Not used recently 標題下;詳細檢視畫面則會顯示 Last used 行。此標題不包含 managed 和 seed-directory plugins,也不包含具有 theme、output style、monitor 或 workflow 的 plugins;LSP server 在提供 diagnostics 或回應 code navigation request 時,會被視為已使用。設定 strictKnownMarketplaces 後,標題和 Last used: 行都不會出現。這些 plugins 仍會在每個 session 消耗啟動時間與 context。請停用或解除安裝。更省成本的做法是在安裝前先挑選:Matt Pocock 的哪些 skills 值得安裝會逐一檢視 27-skill collection,區分出 solo developer 需要的少數 skills,以及只有在 team 中才有實際效益的 skills。
外掛會以你的權限執行
Anthropic 的官方文件對此說得很直接:你安裝的外掛可以在你的電腦上,以你的使用者權限執行任意程式碼。這不是假設情境。外掛的 hooks 會在工作階段事件發生時執行 shell 指令,包括工具呼叫前後。外掛啟用期間,其 bin/ 目錄會加入 Bash 工具的 PATH。外掛啟動的 stdio MCP servers 都是由外掛建立的程序,而 mod 會直接在 Claude Code 內執行 JavaScript。hooks、監控程序、server 程序及 mod 程序都在 Claude Code 的 sandbox 外執行;但 Claude Code 的權限規則仍會套用至 Claude 發出的工具呼叫。
在筆記型電腦上,這項風險通常受限於桌面使用者可存取的內容。在伺服器上則通常不是如此。執行 agent 的帳號通常持有 SSH keys、deploy tokens、cloud CLI 工作階段,以及 Docker socket 的存取權。因此,「以你的使用者身分執行任意程式碼」實際上可能等同於控制整台機器。如果 Claude Code 執行於 VPS,請先閱讀如何在 VPS 上安全執行 Claude Code,再安裝任何內容;若要安裝會連線至外部服務的外掛,請先閱讀如何讓 agent 無法取得認證資料。其他 harness 在同一台租用的主機上也會遇到相同限制。因此,值得安裝的 DeepSeek Harness 外掛多半是消費上限、工具權限規則及注入掃描功能,而不是新增能力。
確實存在一些防護措施,瞭解其作用範圍會有幫助。專案範圍的外掛來自 repository,而不是來自你,因此只有在你信任該 workspace 後才會載入;其 MCP servers 仍須逐一核准,而背景監控程式則完全不會載入。外掛附帶的 agents 不得宣告 hooks、MCP servers 或 permission mode。Marketplace 外掛被複製到 cache 時,指向 marketplace 外部的 symlinks 會被略過,因此複製的外掛無法透過這些連結載入任意主機檔案。
這些措施都不能取代你對安裝內容的檢查。檢查 Will install 清單,優先選擇其原始碼可開啟及閱讀的外掛,將團隊的外掛放在由你控制的 marketplace repository 中,並對你自行撰寫的內容執行 claude plugin validate。你審查過的內容之後也可能改變:Anthropic 官方 marketplaces 預設會啟用自動更新,但 knowledge-work-plugins 和 first-party-plugins 除外;透過 source 新增的第三方 marketplace 則預設關閉自動更新。啟用自動更新時,Claude Code 會在背景更新外掛檔案。
FAQ
Claude Code 外掛需要額外付費嗎?
不需要。外掛系統、加入 marketplace,以及安裝外掛都不收費。費用來自 token 使用量,會像其他 context 一樣,計入您的方案或 API 支出。外掛每一輪都會加入常駐 context;呼叫其中一項 skill 或 agent 時,還會加入更多內容。如果外掛提供的 MCP server 會將其工具載入 prompt prefix,還可能導致一次昂貴且無法使用快取的回合。對於 Anthropic 官方 marketplace 中的外掛,/plugin 詳細檢視畫面會在安裝前顯示 Context cost 預估值;其他外掛則會在安裝或使用 --plugin-dir 載入後,由 claude plugin details name 顯示其固定的 token 成本。
外掛與 skill 有什麼差異?
skill 是單一指令單位。外掛則是套件,可包含 skills、agents、hooks、MCP servers、LSP servers 與 monitors,並具有名稱,通常也有版本,以及通常用來安裝它的 marketplace;不過,也可以將它分享為資料夾或 .zip,再由其他人使用 --plugin-dir 載入。若 standalone skill 僅供您和此專案使用,請寫在 .claude/ 中。像 Ponytail,將 agent 引導至可運作的最小變更 這類單一用途 skill,就是最清楚的例子:其中只有一個檔案和一項規則,直到團隊也需要使用它為止。當其他人需要使用,且需要持續更新時,請將它轉換為外掛。外掛中的 skills 具有命名空間,因此外掛內的 skill 會以 /plugin-name:skill-name 呼叫,而不是 /skill-name。
我的外掛已安裝,但其中的 skills 沒有顯示。問題在哪裡?
先查看安裝摘要。如果摘要顯示 Run /reload-plugins to apply.,Claude Code 會在面板關閉時執行該重新載入;如果重新載入時警告會重新讀取對話,請以 /reload-plugins --force 重新執行。如果已載入但沒有顯示任何內容,請開啟 /plugin,並閱讀 Errors 分頁。最常見的結構錯誤,是將 skills/、agents/ 或 hooks/ 放在 .claude-plugin/ 中;Claude Code 不會在該位置尋找它們。請記住,外掛 skills 具有命名空間,因此輸入 / 時,應尋找 /plugin-name:skill-name。如果這是其他人的外掛,且載入時沒有錯誤,請在 Installed 分頁開啟其詳細資料窗格:如果外掛在該處未列出任何 skills,就表示它沒有可提供的 skill。如果 Errors 分頁顯示外掛未快取,表示其安裝目錄遺失;請從 shell 使用 claude plugin install name@marketplace 重新安裝,並執行 /reload-plugins。
不使用互動式面板也能安裝外掛嗎?
可以。使用 shell 指令 claude plugin install name@marketplace;除非傳入 --scope project 或 --scope local,否則會安裝到使用者範圍。此指令可在 scripts、images 及無法使用 /plugin 面板的非互動式環境中執行。由於它會在工作階段外執行,已開啟的工作階段必須先執行 /reload-plugins,外掛才會生效。在沒有互動式終端機的工作階段中,外掛 MCP servers 的變更會在下一個工作階段生效。
從我在 GitHub 找到的 marketplace 安裝外掛安全嗎?
請將此操作視為以目前使用者身分執行該 repository 的安裝 script,因為實際情況接近如此。外掛可以透過 hooks 執行 shell 指令,將可執行檔加入 Bash 工具的 PATH,並啟動 MCP servers;這些操作都會使用您目前使用者的權限。Anthropic 不會控管或驗證第三方外掛的內容。請從可讀取原始碼的來源安裝,確認前先檢查 Will install 清單。相較於 laptop,請對 server 採取更嚴格的標準,因為 server 上的帳戶通常持有值得竊取的 keys 與 tokens。