Claude Code 自己寫一個插件並發布到 marketplace：plugin.json、marketplace.json、validate 到團隊安裝的完整流程

本文根據 Claude Code 官方文檔《Create a Claude Code plugin》《Publish a plugin》《Create a marketplace》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 已經有自己的 Skill、子智能體或 Hook，想打包後讓團隊一條命令裝上的人；
• 想知道「插件」「marketplace」到底是什麼關係、怎麼自己建一個的人。

怎麼安裝別人的插件，站內已有 /guides/claude-code-plugins-marketplace；本文講自己做、自己發。

結論先說

1. 插件 = 一個目錄 + 一份清單。 官方定義：插件是一組 Skill、子智能體、Hook、MCP 伺服器的目錄，外加 .claude-plugin/plugin.json（清單），Claude Code 把它當作一個整體加載。
2. 什麼時候值得做成插件。 官方說，只給自己或一個項目用，保留 .claude/ 裏的獨立配置就行；想與團隊共享、裝進多個項目或發佈帶版本的發行版，再做插件。
3. 插件裏的 Skill 命令帶前綴。 例如 /my-first-plugin:hello，所以兩個插件都有 hello 也不會衝突。
4. marketplace 就是一個 Git 倉庫裏的 .claude-plugin/marketplace.json。 官方說文件進了倉庫，插件就算發佈了，沒有提交表單；倉庫私有，市場就是私有的。
5. 改了代碼但沒改 version，用戶收不到更新。 這是官方特別提醒的坑。

圖：本站根據 Claude Code 官方文檔：Create a plugin 整理的示意圖

一、目錄結構和 plugin.json

下面用一個演示插件 db-guard，裏面裝站內另一篇講過的 migration-review Skill（見 /guides/claude-code-write-own-skill-auto-trigger）。官方規定每類組件放在固定位置：

text
db-guard/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── migration-review/
│       ├── SKILL.md
│       └── scripts/check.sh
├── agents/            # 可選：子智能體，每個一個 .md
├── hooks/hooks.json   # 可選：Hook 配置
└── .mcp.json          # 可選：MCP 伺服器

官方特別強調：.claude-plugin/ 裏只放 plugin.json，把 Skill 放進去不會加載；插件根目錄是它自己的目錄，不是 ~/.claude/。

bash
mkdir -p db-guard/.claude-plugin db-guard/skills

db-guard/.claude-plugin/plugin.json（字段來自官方示例）：

json
{
  "name": "db-guard",
  "description": "數據庫遷移檢查：Skill 與檢查腳本",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

官方對字段的說明：name 必填，會成為插件裏每個 Skill 和子智能體的前綴，不要有空格；description 是用戶在 /plugin 裏看到的文字；version 可選，設定後用戶停留在該版本，直到你改它；author.name 必填（若寫了 author）。

二、把已有配置搬進插件

如果你已經有 .claude/ 下的配置，官方的遷移做法是複製：

bash
cp -r .claude/skills db-guard/
cp -r .claude/agents db-guard/      # 沒有就跳過
cp -r .claude/commands db-guard/    # 沒有就跳過

Hook 要把 .claude/settings.json 裏的 hooks 對象複製進 hooks/hooks.json，格式相同，外面包一層頂層 "hooks" 鍵。官方提醒兩點：

• 遷移期間原來的 .claude/ 還在，Skill 和子智能體因為帶前綴不會衝突，但 Hook 沒有前綴，兩處都有會各跑一次；確認插件好用後，刪掉原件並從設定裏移除 hooks。
• 腳本路徑在 Hook 命令和 MCP 配置裏要寫成 ${CLAUDE_PLUGIN_ROOT}/...，官方說 validate 會報告不是 ./ 開頭的組件路徑。

三、驗證和本地試跑

官方在發佈前建議的三步：

bash
claude plugin validate ./db-guard
claude --plugin-dir ./db-guard

第一條會檢查清單和 Skill 的 frontmatter，通過時最後一行是 ✔ Validation passed；失敗時每條消息會指出要改的字段。第二條只在這次會話裏加載插件，不寫入你的設定。進去後運行帶前綴的命令：

text
/db-guard:migration-review

邊改邊測時，官方說在會話裏運行 /reload-plugins 加載改動。發佈前再用 claude plugin validate --strict ./db-guard，它會把「未知字段」「缺少 version」之類的警告也當失敗（退出碼 1），適合放進 CI。

四、寫 marketplace.json 並推到 Git

官方給了最省事的發佈方式：插件自己的倉庫裏就放一份市場文件，位置在 .claude-plugin/marketplace.json，source 寫 "./" 表示倉庫根：

json
{
  "name": "acme-tools",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "db-guard", "source": "./" }
  ]
}

規則（來自官方）：

• 市場的 name 要起得別人不容易重名，因為一個用戶不能裝兩個同名市場；
• 條目的 name 要和 plugin.json 裏的 name 一致，否則按清單名安裝會報 Plugin "<manifest-name>" not found in marketplace；
• 相對路徑從市場根目錄寫，不要用 ..；
• 官方保留了一批名字（例如 claude-plugins-official），添加叫這個名字的市場會被拒絕。

如果一個倉庫裏放多個插件，官方的目錄是 my-marketplace/plugins/<插件名>/，條目 source 寫 ./plugins/<插件名>。

先在本機走通一遍再推送，官方的本地迴路是：

bash
claude plugin validate .
claude plugin marketplace add ./
claude plugin install db-guard@acme-tools
claude plugin list

install 的 id 是「條目名 + @ + 市場名」；list 裏應看到 db-guard@acme-tools 且狀態為 enabled。想從頭再來，用 claude plugin marketplace remove acme-tools，它會移除市場並卸載其中的插件。然後 git push 到你的 GitHub 或其他 Git 倉庫即可，官方說誰能克隆倉庫誰就能安裝，所以私有倉庫就是私有市場。

圖：本站根據官方文檔整理的示意圖

五、同事怎麼裝

官方給的幾種寫法，把來源和名字換成你的：

bash
claude plugin marketplace add your-org/acme-tools
claude plugin install db-guard@acme-tools

會話裏也可以一條命令完成：/plugin install db-guard --marketplace your-org/acme-tools（官方標註需要 v2.1.275 或更高）；在 shell 裏一步完成的寫法需要 v2.1.292 或更高。安裝前請同事先看看你的倉庫裏放了什麼，原因見 /guides/agent-skills-security-audit-before-install。

六、發新版本

官方的規則是二選一：

• 每次發佈都遞增 plugin.json 裏的 version。 如果你設了 version，之後只推提交不改版本，用戶運行 claude plugin update 會看到 is already at the latest version，仍然用舊的；
• 或者在 Git 託管的市場裏乾脆不寫 version，這時 Claude Code 用提交的 SHA 當版本。此時 --strict 會因缺少 version 報警，官方說那就去掉 --strict。

用戶拿更新有兩條路：自己運行 claude plugin update db-guard@acme-tools；或者為你的市場開自動更新，官方說預設是關的，由用戶一側設定。

七、要發給更多人怎麼辦

按官方「Publish a plugin」的對比：

提交到 Anthropic 目錄需要一個 GitHub 倉庫和付費的 claude.ai 方案，在開發者門戶提交；官方還說本地 validate 通過不保證門戶一定通過，門戶有額外規則。官方的 claude-plugins-official 市場不接受通過這個門戶提交。這部分流程以 claude.com 官方頁面為準，本文不展開。

常見問題

Q：只想給自己用，需要 marketplace 嗎？

不需要。官方說可以用 --plugin-dir，或者把帶 .claude-plugin/plugin.json 的目錄放到 ~/.claude/skills/ 下，之後每次啟動自動加載（除非管理員禁用了）。目錄優先級見 /guides/claude-code-skills-directory-location-priority。

Q：claude plugin validate 過了，安裝還是失敗？

官方說兩者查的東西不同：validate 只讀市場目錄內的文件。條目的 source 指向不存在的目錄時 validate 會通過，但安裝時報 Source path does not exist；github、git-subdir 這類遠程來源寫錯，也只會在安裝時暴露。

Q：裝好了沒看到我的 Skill？

先 claude plugin details <插件名> 看 Component inventory 裏有沒有列出；再對照第一節的目錄結構，確認 Skill 在 skills/<名字>/SKILL.md，而不是放進了 .claude-plugin/（官方說放在那裏的組件不會加載）。

訂閱和額度

插件裏的 Skill 和子智能體運行時用的是你自己的 Claude Code 額度。訂閱選擇見 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

• /guides/claude-code-plugins-marketplace：怎麼安裝插件、加 marketplace
• /guides/claude-code-custom-skill-slash-command-example：先寫好 Skill 再打包
• /guides/claude-code-install-superpowers-plugin：一個第三方插件的安裝實例

參考資料

• Claude Code 文檔：Create a Claude Code plugin — https://code.claude.com/docs/en/plugins/create
• Claude Code 文檔：Publish a plugin — https://code.claude.com/docs/en/plugins/publish
• Claude Code 文檔：Create a marketplace — https://code.claude.com/docs/en/plugin-marketplaces