參考文件

marketplace.json 結構描述

marketplace 清單檔案位於儲存庫根目錄下的 .claude-plugin/marketplace.json。

頂層欄位

欄位	必填	說明
`$schema`	否	用於驗證的 JSON Schema URL
`name`	是	唯一的 marketplace 識別碼
`version`	否	Marketplace 結構描述版本（semver）
`metadata.description`	是	人類可讀的 marketplace 說明
`owner.name`	是	擁有該 marketplace 的組織或使用者
`owner.url`	否	擁有者個人檔案或網站的 URL
`owner.email`	否	聯絡電子郵件
`plugins`	是	外掛程式項目陣列

外掛程式項目欄位

欄位	必填	說明
`name`	是	外掛程式識別碼（須與 `plugin.json` 相符）
`description`	是	外掛程式的簡短說明
`version`	是	語意化版本字串
`author.name`	是	外掛程式作者
`source`	是	外掛程式的路徑或 URL（請參閱來源類型）
`category`	是	外掛程式分類（例如：`productivity`）
`homepage`	否	外掛程式文件或首頁的 URL
`license`	否	SPDX 授權識別碼
`keywords`	否	搜尋關鍵字陣列
`tags`	否	用於篩選的標籤陣列
`repository`	否	儲存庫 URL

外掛程式來源類型

marketplace.json 中的 source 欄位支援多種格式：

類型	範例	說明
相對路徑	`./plugins/example-plugin`	位於同一儲存庫中的外掛程式
GitHub 簡寫	`owner/repo`	位於儲存庫根目錄的外掛程式
GitHub 含路徑	`owner/repo/path/to/plugin`	位於子目錄中的外掛程式
Git URL	`https://github.com/owner/repo.git`	Git 儲存庫
npm 套件	`npm:@scope/package`	已發佈的 npm 套件

plugin.json 結構描述

每個外掛程式在其目錄內的 .claude-plugin/plugin.json 中均有一份清單檔案。

欄位	必填	說明
`name`	是	外掛程式識別碼
`description`	是	外掛程式的功能說明
`version`	是	語意化版本
`author.name`	是	外掛程式作者
`author.url`	否	作者個人檔案或網站的 URL
`homepage`	否	文件 URL
`keywords`	否	搜尋關鍵字
`license`	否	SPDX 授權識別碼
`repository`	否	儲存庫 URL

外掛程式目錄結構

plugins/example-plugin/
  .claude-plugin/
    plugin.json          # 外掛程式清單（必要）
  skills/
    skill-name/
      SKILL.md           # 技能定義（每個技能必要）
      references/        # 參考資料檔案（選用）
  commands/
    command-name.md      # 指令定義（每個指令一個）
  agents/
    agent-name.md        # 代理程式定義（每個代理程式一個）
  README.md              # 外掛程式文件（建議提供）

環境變數

外掛程式可在其技能和指令檔案中使用以下變數：

變數	說明
`$\{CLAUDE_PLUGIN_ROOT\}`	外掛程式根目錄的絕對路徑

驗證

在本地端驗證您的 marketplace 和外掛程式清單：

claude plugin validate .

此指令會檢查：

marketplace.json 結構描述合規性
所有參考的外掛程式目錄是否存在
每個外掛程式是否具有有效的 plugin.json
技能的 SKILL.md frontmatter 格式是否正確
指令是否具有必要的 frontmatter 欄位

團隊配置

預先配置 marketplace

在任何儲存庫的 .claude/settings.json 中新增：

{
  "extraKnownMarketplaces": [
    "f5-sales-demo/marketplace"
  ]
}

預先啟用外掛程式

{
  "enabledPlugins": [
    "f5xc-docs-tools@f5-sales-demo-marketplace"
  ]
}

疑難排解

找不到 Marketplace

確認 marketplace 已新增：

/plugin marketplace list

若缺失，請重新新增：

/plugin marketplace add f5-sales-demo/marketplace

外掛程式未啟動

確認外掛程式已安裝： /plugin list
確認您的 Claude Code 版本支援外掛程式（v1.0.33+）
確認技能的觸發條件與您目前的情境相符

技能未自動觸發

技能根據 SKILL.md frontmatter 中的 description 欄位進行啟動。若技能未如預期觸發：

確認說明內容是否準確描述了觸發情境
直接使用指令（例如：/f5xc-docs-tools:review-mdx）作為替代方案

審閱後出現建置錯誤

外掛程式會回報問題，但不會自動修正。請手動套用建議的修正方案，然後重新執行審閱以確認問題已解決。