Claude Code 外掛上架：我的提交經驗與避坑指南

我維護一個開源的 Claude Code 外掛，它包含 B2B SaaS 的行銷代理，以及一個為 Claude Code 增加即時面板的模組。我於 10 月 8 日將其提交至 Anthropic 的外掛目錄，但約一週內，每個版本在掃描前就被拒絕了。

直到 11 月 3 日，它才通過安全掃描並進入人工審核階段。以下是我在提交前會檢查的事項，依序排列；這些內容要麼發生在我的提交過程中，要麼來自 Anthropic 的官方文件。

首先，單純通過 claude plugin validate 驗證是不夠的。這個指令僅檢查你的檔案格式是否正確，但目錄審核會檢查更多項目，例如是否有 README 和授權檔案、名稱是否已被佔用、檔案大小以及你的 hooks 執行了什麼。

在提交之前，請務必使用開發者入口網站（claude.ai/directory/manage）中的「驗證」步驟。提交前檢查清單會列出所有發現的問題，以及它們是否會阻擋你的提交。

其次，請將 README 檔案放在外掛資料夾內。這個資料夾是指包含 .claude-plugin/plugin.json 的那個。如果你的外掛位於儲存庫的子資料夾中，那麼儲存庫根目錄的 README 是不算數的。檢查清單的規定是：README 必須至少 40 個字，且位於外掛資料夾中，程式碼區塊內的文字不計入字數。

缺少它會導致驗證失敗。此外，目錄會將此 README 作為你的上架說明，因此請為那些考慮安裝外掛的使用者撰寫。

第三，檢查你的 .gitattributes 檔案中的換行符號規則。這是我花費一週時間才解決的問題。我的儲存庫原本設定為：* text=auto、*.bat text eol=crlf 等。入口網站將每個新版本標記為「掃描前拒絕」，並指向 .gitattributes 檔案。

解決方法是將設定改為：* text=auto eol=lf、*.ps1 text eol=lf，並將 *.bat -text 和 *.cmd -text 放在所有匹配規則之後。有兩點需要注意：這項資訊來自入口網站對我提交的訊息，而公開的檢查清單則另外指出 export-ignore、export-subst 和 filter 等內容重寫屬性（包括 Git LFS）會阻礙驗證。

請務必同時檢查這兩點。推送修復後，請在外掛頁面選擇「檢查新提交」，否則目錄會等待下一次排程檢查。

第四，如果你有 hooks 或模組，請寫下每個 hook 的作用。檢查清單要求你在 README 中描述外掛執行、傳送或獲取的所有內容。我在外掛的 README 中增加了一個簡短的區塊，每行說明一個 hook：例如 session.start 會註冊 /campaign-board 指令並檢查專案資料夾中是否存在 brand-context.md。

tool.call 用於 Write 和 Edit，它會先執行呼叫，然後讀取寫入的文字以尋找 [NEEDS INPUT] 標記並顯示在面板中；ui.render 則負責繪製面板。

我的掃描通過了，但版本隨後因「此外掛包含模組」而被暫停進行內容政策審核。文件明確指出，暫停並非拒絕：審核人員會在版本上線前進行審查，而且每個新上架的外掛都會經過人工審核。

第五，每次發布時都要更新 plugin.json 中的版本號。如果 plugin.json 設定了版本但你沒有更改它，已安裝的使用者將保留他們的快取副本。我的外掛版本 1.3.0 停滯了兩週，導致已安裝的副本錯過了 47 次提交。提交指南和外掛版本控制文件都建議每次發布時都要提高版本號。

第六，告知使用者如何更新外掛。更新需要兩個指令，然後重新啟動：claude plugin marketplace update <marketplace> 和 claude plugin update <plugin>@<marketplace>。第一個指令只會重新整理市集，它本身並不會更新已安裝的外掛。第三方市集的自動更新功能預設是關閉的，所以請將這兩行指令放在你的 README 中。

第七，了解入口網站的狀態含義。根據「追蹤你的目錄提交」頁面，狀態說明如下：「掃描中」表示 Anthropic 正在執行安全掃描，你無需採取任何行動。「需要更改」表示最新版本未通過或無法獲取，頁面會說明需要更改的內容。「審核中」表示審核人員正在檢查，如果版本被暫停，卡片會顯示類別。「已核准」表示版本已通過但尚未上線，這不代表使用者可以安裝它。「已發布」表示已在目錄中上線。

我的外掛目前處於「審核中」，因模組而被暫停。當審核人員做出決定後，我會在此處更新結果。如果你想要一個可供參考的範例，我的儲存庫中包含帶有 hook 列表的外掛資料夾 README、已修復的 .gitattributes 檔案，以及每次發布都會更新版本號的 plugin.json。