一台全新的機器，還沒有人在上面開過互動式的 Claude Code。你寫了一支裝機腳本，要替它把 plugin 裝好。官方文件〈Install from your shell〉那一段剛好替這個場景留了一句提醒：這時候連官方的 marketplace 都還沒註冊，所以腳本在 install 之前，得先跑一行 claude plugin marketplace add anthropics/claude-plugins-official。

官方自家的都要多一行。換成同事自己架的 marketplace，多出來的就不只一行，還多一個名字要記。

我在 3 月那篇〈Claude Code Skill 開發標準與 Plugin Marketplace 完整攻略〉的常用指令表裡，列的也是這套兩步式：先 marketplace add，再 install <plugin>@<marketplace>。marketplace 的目錄結構、plugin.json 那些那篇講過了，這篇補的是一步裝完的新寫法，還有一步跟兩步之間到底差在哪。

以前：先登記，再用登記的名字叫它

第一步是讓 Claude Code 認識那個 marketplace。官方文件的說法是：「Claude Code has to know about a marketplace before you can install from it. You add a marketplace once.」來源可以是 GitHub 的 owner/repo、完整的 git URL、本機目錄，或一個放在網路上的 marketplace.json。文件的範例長這樣：

1
2
3
4
5
/plugin marketplace add anthropics/claude-code
/plugin marketplace add your-org/plugins#v1.2.0
/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0
/plugin marketplace add ./my-marketplace
/plugin marketplace add https://example.com/marketplace.json

第二步才是安裝，格式是 <plugin>@<marketplace>。重點在 @ 後面那個字。文件寫得很清楚，它是「the name the marketplace registered under」，也就是 marketplace 登記進來時用的名字，不是你剛剛貼的那串來源位址。shell 版的範例：

1
claude plugin install formatter@your-org --scope project

成功的話會印出 Successfully installed plugin: formatter@your-org (scope: project)。

這套流程很像手機通訊錄。你先把一支電話號碼存進去，取個暱稱叫「阿明」，之後打電話只要喊阿明就好。在你自己的手機上，這很方便。

麻煩出在你要把它交代給別人的時候。你跟新同事說「打給阿明」，他的手機裡根本沒有阿明。formatter@your-org 就是那個阿明：只有在已經加過那個 marketplace 的機器上，這行指令才有意義。所以以前的安裝說明一定是兩行，第一行負責把號碼存進對方的通訊錄，第二行才是撥號。

現在：把電話號碼直接寫進指令

--marketplace 做的事，就是讓你直接報號碼。文件的範例：

1
/plugin install deploy-helper --marketplace your-org/plugins

deploy-helper 和 your-org/plugins 是文件拿來示意的名字，不是真的有這個 plugin。

這行指令把兩個資訊一起交代了：要裝哪個 plugin，從哪裡來。照文件的描述，如果那個 marketplace 你還沒加過，Claude Code 會先顯示它解析出來的來源，請你確認之後再加入；加好之後打開這個 plugin 的詳情，讓你選安裝的 scope。如果來源對得上一個你已經加過的 marketplace，就跳過確認，直接打開它在那個 marketplace 裡的詳情。

在 session 裡，/plugin install 本來就不會立刻安裝。文件的原文是「it opens the /plugin panel on that plugin’s details so you can review it and choose a scope first」。所以 session 版的 --marketplace，省掉的主要是先跑一次 marketplace add 跟記名字這兩件事，面板該看的照樣要看。

版本要分開記，兩邊差了一段。session 內的 /plugin install <plugin> --marketplace <source> 是 CHANGELOG 2.1.275 加入的，文件也註明「Requires Claude Code v2.1.275 or later」；shell 的 claude plugin install <plugin> --marketplace <source> 要到 CHANGELOG 2.1.292 才加入。

以 10 月 7 日抓到的 CHANGELOG 為準。我這台 macOS 上 claude --version 印的是 2.1.292 (Claude Code)，剛好是 shell 版能用的第一版。

我比較在意 shell 那一半

session 裡的人看得到面板，多一步少一步差別有限。裝機腳本、README 裡的安裝說明、給新人的 onboarding 文件，才是兩步式最卡的地方，因為寫的人和跑的人不是同一台機器。這次加進 shell 的版本，正好打在這裡。

我沒有用 --marketplace 實際裝過任何東西，下面是 claude plugin install --help 輸出的節錄，我只看了說明：

1
2
3
4
5
6
7
8
Usage: claude plugin install|i [options] <plugin>
  --marketplace <source>     Install <plugin> (its bare name) from the
                             marketplace at this source: owner/repo, a git or
                             https URL, or a path. A marketplace not added yet
                             is added first, in user settings, under the same
                             checks as 'plugin marketplace add'
  -s, --scope <scope>        Installation scope: user, project, or local
                             (default: "user")

有兩句值得多看一眼。一句是「under the same checks as ‘plugin marketplace add’」，CHANGELOG 那條也寫了「under the same policy checks」。照字面看，一步完成沒有繞過任何檢查：需要的話先照 marketplace add 那套檢查把 marketplace 加進來，再接著安裝。

另一句是「in user settings」。用 --marketplace 順手加進來的 marketplace，落在 user settings。marketplace add 自己則有 --scope <user|project|local> 可以選。至於 plugin 本身裝在 user、project、local 時各寫進哪個檔，文件〈Choose an install scope〉有列。

要寫給別人照抄的安裝指令，從現在起我會寫成 --marketplace 這種。理由很單純，指令自己帶著出處，讀的人不需要先知道那個 marketplace 在他機器上叫什麼。

有兩種情況會讓我改回兩步式。第一，團隊想把 marketplace 登記在 project scope、跟著 repo 一起走。照 help 的寫法，--marketplace 會把它加進 user settings，這時候我會回去用 marketplace add --scope project 再 install。不過我沒試過 --marketplace 搭配 -s project 時 marketplace 落在哪裡，help 只寫了 user settings 這一句。

第二，非互動環境。help 裡的 -y 是用來接受 marketplace 宣告的指令、略過確認提示，而且「required when stdin or stdout is not a TTY」。單純從 GitHub 加一個 marketplace，在 CI 裡跑需不需要也帶 -y，我不知道，沒測過。如果答案是每次都得補旗標，腳本裡一步式的優勢會小一點。

兩步式和一步式最後寫出的設定檔是否完全相同，官方沒有明說，我也沒比對過。

號碼和暱稱，不能混著填

既然以前是喊暱稱、現在是報號碼，最容易出錯的就是兩種寫法混在一起。文件特別交代了幾條：

--marketplace 後面接的是來源，plugin 名稱只給名字本身，文件原話是「without an @marketplace suffix」。deploy-helper@某某 --marketplace your-org/plugins 這種寫法，等於電話號碼跟暱稱同時報，不要這樣寫。

來源「can’t contain spaces」。路徑裡有空白的本機目錄，就不能直接塞進 --marketplace。

本機路徑如果是相對路徑，要用 ./ 或 ../ 開頭。原因是 name/name 這種形狀會被當成 GitHub 的 owner/repo。照這條規則推，你本機有個 tools/plugins 資料夾，不加 ./ 的話，它會被當成 GitHub 上 tools 帳號底下的 plugins repo。

除了 tools/plugins 是我照規則推出來的例子，這幾條都是從文件抄的，沒有實際撞過。

少掉的是手續，審查還在

一步完成很容易讓人覺得「反正一行就好，貼上去跑」。文件在這裡放了一句我覺得該抄下來的話：「A plugin can run hooks and MCP servers, so read the pane before you install」。

在 session 裡，新的 marketplace 第一次出現時，Claude Code 會把它解析出的來源秀給你確認，詳情面板也還是會打開，這些都沒有因為指令變短而消失。shell 版照 help 的說法，走的是跟 marketplace add 同一套檢查。

裝完要確認有沒有生效，文件給的方法是在 session 裡輸入 / 看有沒有 /<plugin>:<skill>，或在 shell 跑 claude plugin list，它會列出 Version、Scope、Status。安裝摘要的最後一句決定接下來要做什麼：Plugin is now active. 表示已經生效，Run /reload-plugins to apply. 表示要重新載入，The plugin couldn't be loaded 就是沒載入成功。從 shell 裝的 plugin，會在下次啟動 Claude Code 時載入，已經開著的 session 要跑一次 /reload-plugins。

還有一件事 --marketplace 沒有改變。scope 設成 project，只是把啟用項目寫進要 commit 的 .claude/settings.json，不會替同事下載。文件說每位同事仍然要自己跑一次 claude plugin install <name>@<marketplace> --scope project。

安裝說明是寫給誰的

以前的安裝指令，其實是寫給自己的備忘：formatter@your-org 預設讀的人通訊錄裡已經有 your-org 這個人。在你的機器上它一直是對的，所以你很少察覺它依賴一份別人沒有的狀態。

--marketplace 改掉的就是這個預設。指令從「喊一個我這邊登記過的名字」，變成「報一個不靠對方通訊錄也撥得出去的號碼」。功能上它只是把兩行併成一行，可是寫安裝說明的人，從此得先想清楚這行字會在誰的機器上跑，而不是只想自己的。

原文來源：Discover and install plugins（Add a marketplace、Add a marketplace and install in one command、Install from your shell、Choose an install scope、Confirm the plugin works 各節）、Claude Code CHANGELOG（2.1.275、2.1.292 條目，以 2026 年 10 月 7 日讀取的版本為準）；claude plugin install --help 輸出取自本機 2.1.292