參考文件

marketplace.json 綱要

市集清單位於儲存庫根目錄的 .claude-plugin/marketplace.json。

頂層欄位

欄位	必填	說明
$schema	否	用於驗證的 JSON Schema URL
name	是	唯一的市集識別碼
version	否	市集綱要版本（semver）
metadata.description	是	人類可讀的市集描述
owner.name	是	擁有此市集的組織或使用者
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\}	外掛程式根目錄的絕對路徑

驗證

在本機驗證您的市集和外掛程式清單：

claude plugin validate .

此指令會檢查：

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

團隊配置

預先配置市集

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

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

預先啟用外掛程式

{
  "enabledPlugins": [
    "f5xc-docs-tools@f5-sales-demo-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）

審查後發生建置錯誤

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