Let's Write

Posted on Aug 18 Originally published at letswrite.tw

公司內部自架 Claude Code Marketplace，讓團隊共用 skill

#claude #marketplace #skill #ai

本篇要解決的問題

有些 skill 只適合在公司內部使用，而這個 skill 又想讓其他同事能一起使用的話，就需要一個可以讓大家方便安裝、更新的平台。

本篇主要筆記，用自架的 Gitea 建立一個內部專用的 Claude Code plugin marketplace，讓團隊裡每個人寫的 skill 不再各自散落在自己電腦裡，而是能集中在一個地方統一發布、安裝、更新版本。

其他同事只要裝一次就能共用、之後改版也能一起同步拿到最新版。

這篇整理實作過程中每一個能正確跑通的步驟，讓大家避免在這過程中踩到的坑。

可用 GitHub、GitLab、Gitea，主要是專案可以有版控就行。

本篇示範的是在自架的 Gitea 上實作。

建立 marketplace 專案結構

Gitea 上新建一個 repo（例如 claude-plugins），本機目錄結構：

claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── your-plugin-name/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── your-skill/
                └── SKILL.md

讓 Claude Code 直接產生 SKILL.md、plugin.json、marketplace.json

看到上面的架構，有一堆的檔案要建立時，不用感到驚慌失措或是害怕。

因為我們只需要把上面的架構貼給 Claude Code，讓它讀取之前已經寫好的 skill 內容，依照結構把 SKILL.md、plugin.json、marketplace.json 都建出來即可。

底下附上完整的 marketplace.json 範例，供對照參考：

{
  "name": "claude-plugins",
  "owner": { "name": "August" },
  "plugins": [
    { "name": "ai-tools", "source": "./plugins/ai-tools" },
    { "name": "ai-tools2", "source": "./plugins/ai-tools2" }
  ]
}

必要欄位：name（kebab-case，公開可見）、owner、plugins。
每個 plugin entry 至少要有 name 和 source。
若 source 是同一個 repo 內的相對路徑，要以 ./ 開頭，不可用 ../ 跳出去。
一個 plugin 可以裝多個 skill：skills/ 資料夾下每個子資料夾都是獨立一個 skill，不需要每個 skill 各自開一個 plugin。

Host 到 Gitea

不限 GitHub，GitLab、Bitbucket、自架伺服器都支援。把整個 claude-plugins repo push 到 Gitea 即可，不需要額外設定。

驗證

claude-plugins 專案上打開終端機，輸入：

claude plugin validate .

會檢查 JSON schema、重複的 plugin 名稱、路徑穿越等問題。

檔案寫的有問題，就會看到哪邊寫錯、哪邊建議要寫，再照著回應讓 Claude 繼續做修改即可。

本機測試安裝

/plugin marketplace add ./claude-plugins
/plugin install ai-tools@claude-plugins

安裝語法格式固定是 plugin名稱@marketplace名稱，分別對應 plugin.json 的 name 和 marketplace.json 的 name。

有幾個 plugin 就要執行幾次安裝指令。

要注意的是，這步可以跳過嗎？技術上可以，因為下一步的遠端安裝跟這步沒有依賴關係，直接對 Gitea 網址下指令一樣裝得起來。但跳過等於少了一層「出包前先在本機攔下來」的保護。

正式指向 Gitea

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git

讓團隊自動加入（選用，非必要步驟）

最直接的方式：手動下指令。

同事不需要碰任何設定檔，兩行指令就能裝好：

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git
/plugin install ai-tools@claude-plugins
/plugin install ai-tools2@claude-plugins

裝完就能直接用，缺點是每次換電腦、換專案，或新同事加入，都要重新打一次這幾行。

如果不想讓同事記指令、手動輸入，才需要往下看設定檔自動化這條路。

進階：讓同事 trust 專案資料夾就自動裝好。

以下的內容，要放在每一個開發中的專案裡的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "claude-plugins": {
      "source": {
        "source": "url",
        "url": "https://gitea.你們公司.internal/team/claude-plugins.git"
      }
    }
  },
  "enabledPlugins": {
    "ai-tools@claude-plugins": true,
    "ai-tools2@claude-plugins": true
  }
}

extraKnownMarketplaces 只負責自動註冊 marketplace 來源。
enabledPlugins 才是真正讓 plugin 自動裝上並啟用的關鍵，兩者要同時寫，同事 trust 專案資料夾後才會完全不用手動 /plugin install。
如果目前還沒有同事需要同步使用，這一步可以先跳過，不影響前面步驟的成果，等有需要再回頭補上即可。

Gitea 上有新版本時，同事怎麼更新

如果有發佈新版本，記得 plugin.json 裡的 version 要往上加一版，沒改版號的話，其他同事那邊不會被判斷成有更新。

同事更新分兩步，順序不能反：

/plugin marketplace update claude-plugins
/plugin update ai-tools@claude-plugins

第一行只是刷新 marketplace 目錄，讓 Claude Code 知道有新版本存在。

第二行才是真正把新內容拉下來、覆蓋本機快取。

也可以用互動面板 /plugin → 選到該 plugin → Update now 達到一樣效果。

參考資料

這篇文章記錄的是目前版本觀察到的行為，Claude Code 的 plugin 系統仍在快速迭代中，實際行為可能隨版本更新而改變，建議操作前對照當下的官方文件再確認一次。

DEV Community