grahama1970/plugin-creator

外掛建立工具

快速開始

1. 執行搭建腳本：

# 外掛名稱正規化為小寫連字符號，且不得超過 64 個字元。
# 產生的資料夾和 plugin.json 名稱始終一致。
# 從技能根目錄（包含此 `SKILL.md` 的目錄）執行。
# 預設在 `~/plugins/<plugin-name>` 建立。
python3 scripts/create_basic_plugin.py <plugin-name>

2. 當請求指定特定中繼資料時，編輯 <plugin-path>/.codex-plugin/plugin.json。 搭建的起始值為有效預設值，且不得包含 [TODO: ...] 佔位符。

3. 當外掛應出現在 Codex UI 排序中時，產生或更新個人商店條目：

# 個人商店條目預設為 `~/.agents/plugins/marketplace.json`。
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

僅在預設的 personal 商店名稱已被佔用或已安裝，且你需要建立一個不同的新商店檔案時，才指定 --marketplace-name <name>：

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

僅在使用者明確要求該目的地時，才使用儲存庫/團隊商店：

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

當使用者指定商店路徑時，請確保該商店實際上已安裝，然後再指示使用者從中重新安裝。預設的個人商店檔案位於 ~/.agents/plugins/marketplace.json 會隱含地被發現，但其他商店路徑則不會。在 Windows 上，請使用使用者設定檔下的對應路徑。

4. 根據需要產生/調整選用的附屬資料夾：

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> 是將建立外掛資料夾 <plugin-name> 的目錄（例如 ~/plugins）。

5. 在交出產生的外掛之前，執行：

python3 scripts/validate_plugin.py <plugin-path>

對於開發期間對現有本機外掛的更新，請保持搭建流程不變，並使用參考而非手動編輯商店檔案：

python3 scripts/update_plugin_cachebuster.py <plugin-path>

偏好使用輔助的預設快取破壞器，除非使用者明確要求特定的覆蓋。請參閱 references/installing-and-updating.md 以了解在迭代現有本機外掛時預期的快取破壞器與重新安裝流程。

這項技能建立的內容

• 預設的商店支援搭建使用 ~/.agents/plugins/marketplace.json 的個人商店檔案，外掛通常儲存在 ~/plugins/<plugin-name>/。
• 在 /<parent-plugin-directory>/<plugin-name>/ 建立外掛根目錄。
• 始終建立 /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json。
• 使用接收路徑接受的驗證模式形狀填入清單。
• 當設定 --with-marketplace 時，建立或更新 ~/.agents/plugins/marketplace.json。
  • 如果商店檔案尚不存在，請在加入第一個外掛條目前先建立個人商店根目錄。
• <plugin-name> 使用技能建立工具的命名規則進行正規化：
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • 底線、空格和標點符號會轉換為 -
  • 結果為小寫連字符號分隔，連續的連字符會合併
• 支援選擇性建立：
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

商店工作流程

• 個人商店的建立預設為 ~/.agents/plugins/marketplace.json。此處的「個人商店」指的是檔案位於該路徑的商店。
• 儲存庫/團隊商店的建立是透過 --path 和 --marketplace-path 選擇性加入的，僅在使用者特別要求時使用。
• --marketplace-name 是一個例外路徑。僅當預設的 personal 商店名稱已被佔用，且你需要建立一個不同的新商店檔案時才使用。
• 請勿使用 --marketplace-name 重新命名現有的商店檔案。如果檔案已存在，其頂層 name 必須已經相符。
• 如果使用者指定了不同的商店路徑，請將該商店視為需要透過 codex plugin marketplace add 明確安裝。
• 當你需要從任何 marketplace.json 檔案取得商店名稱時，偏好使用 scripts/read_marketplace_name.py。不帶參數時，它會讀取預設的個人商店；帶有明確路徑時，它也可用於儲存庫/團隊商店。
• 在任一位置，產生的來源路徑仍為 ./plugins/<plugin-name>。
• 商店根中繼資料支援頂層 name 以及選用的 interface.displayName。
• 將 plugins[] 中的外掛順序視為 Codex 中的呈現順序。除非使用者明確要求重新排序列表，否則將新條目附加到結尾。
• displayName 屬於商店 interface 物件內部，而非個別的 plugins[] 條目。
• 每個產生的商店條目必須包含以下所有項目：
  • policy.installation
  • policy.authentication
  • category
• 新條目的預設值為：
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• 僅在使用者明確指定另一個允許的值時，才覆蓋預設值。
• 允許的 policy.installation 值：
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• 允許的 policy.authentication 值：
  • ON_INSTALL
  • ON_USE
• 將 policy.products 視為覆蓋項。除非使用者明確要求產品閘道，否則請省略它。
• 產生的外掛條目形狀為：

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• 僅在有意取代現有商店中相同外掛名稱的條目時，才使用 --force。

• 如果目標商店檔案尚不存在，請使用頂層 "name"、包含 "displayName" 的 "interface" 物件和一個 plugins 陣列來建立它，然後加入新條目。

• 對於全新的商店檔案，根物件應如下所示：

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

必要行為

• 外部資料夾名稱和 plugin.json 的 "name" 始終是相同的正規化外掛名稱。
• 請勿移除必要的結構；保持 .codex-plugin/plugin.json 存在。
• 請勿在外掛清單中留下 [TODO: ...] 佔位符。
• 除非其實際建立了 apps 和 mcpServers 的附屬檔案，否則將它們排除在 plugin.json 之外。
• 省略驗證拒絕的不受支援外掛清單欄位，包括 hooks。
• 如果在現有外掛路徑內建立檔案，僅在有意覆寫時才使用 --force。
• 保留任何現有的商店 interface.displayName。
• 產生商店條目時，即使其值為預設值，也務必撰寫 policy.installation、policy.authentication 和 category。
• 僅在使用者明確要求該覆蓋時，才加入 policy.products。
• 保持商店 source.path 相對於所選商店根目錄的 ./plugins/<plugin-name>。
• 僅在建立新商店檔案且其名稱不應為 personal（因為該名稱已被佔用或安裝在其他地方）時，才使用 --marketplace-name。
• 如果 Codex 需要核准才能寫入商店檔案，請在繼續之前要求該核准。如果使用者偏好自己執行寫入，請提供確切的搭建命令，然後繼續進行驗證或後續的外掛編輯，而不是讓工作流程含糊不清。
• 對於開發期間對現有本機外掛的更新，請勿手動編輯商店配置或 marketplace.json。請使用 references/installing-and-updating.md 和 scripts/update_plugin_cachebuster.py 中記錄的更新流程。
• 請勿指示使用者為預設的個人商店流程執行 codex plugin marketplace add。該命令用於明確的非預設商店配置，而不是標準的 ~/.agents/plugins/marketplace.json 路徑。
• 如果使用者提供了非預設的 --marketplace-path，請在提供重新安裝指示之前，確保該商店已安裝。當該明確的商店尚未配置時，請使用 codex plugin marketplace add <path-to-marketplace-root>。
• 當工作流程建立或更新了商店支援的外掛時，請以簡短的 Codex 應用程式交接來結束最終的使用者面向回應。說 To view this in the Codex app: 並將 View <normalized plugin name> 和 Share <normalized plugin name> 撰寫為 Markdown 連結，而非原始 URL 或程式碼範圍。
• 檢視深度連結使用 codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>。 分享深度連結使用相同的 URL，但附加 &mode=share。
• 將佔位符替換為來自搭建外掛的真實正規化外掛名稱和絕對 marketplace.json 路徑。必要時對路徑片段和查詢值進行 URL 編碼。
• 請勿將 pluginName 或 hostId 查詢參數加入這些深度連結。Codex 在使用者點擊連結後會推導出這兩個值。
• 如果未建立或更新任何商店條目，請勿發出 View <normalized plugin name> 或 Share <normalized plugin name> 連結。

參考精確規格範例

有關外掛清單和商店條目的精確規範 JSON 範例，請使用：

• references/plugin-json-spec.md
• references/installing-and-updating.md 以獲取在迭代現有本機外掛時的更新/重新安裝指南，以及重新安裝後的新執行緒拾取行為

驗證

編輯 SKILL.md 後，執行：

python3 ../skill-creator/scripts/quick_validate.py .

在交出產生的外掛之前，執行：

python3 scripts/validate_plugin.py <plugin-path>