前言¶

單個 Agent Skill 很適合封裝「一件事怎麼做」：一份 SKILL.md、若干腳本和參考資料，Agent 按需加載即可。但團隊一旦要把多份 Skill、MCP 連接、生命週期鉤子和展示資源一起分發，再靠零散目錄複製就不穩了——需要一個有穩定身份、可安裝、可進目錄展示的打包單元。

在 Codex / ChatGPT 這套體系裏，這個單元叫 Plugin。OpenAI 官方內置的 plugin-creator Skill，就是專門用來創建和腳手架 Plugin 目錄的：自動生成必填的 .codex-plugin/plugin.json，按需補齊可選組件佔位，並能寫入本地或倉庫級的 marketplace.json，方便你在 Plugins Directory 裏測試和分發。

本文依據 OpenAI 官方倉庫中的 plugin-creator 原文、plugin.json 規範樣例，以及 Build plugins 文檔交叉覈實後整理。

這是什麼¶

plugin-creator 是 OpenAI 維護的系統級 Agent Skill（位於 openai/skills 倉庫的 skills/.system/plugin-creator）。.system 目錄下的 Skill 會隨較新版本的 Codex 自動安裝，一般不必再手動拷貝。

按官方描述，它的職責是：

• 爲 Codex 創建並腳手架 Plugin 目錄；
• 始終生成必填清單 .codex-plugin/plugin.json（含完整 schema 形狀與可編輯佔位）；
• 按需創建 skills/、hooks/、scripts/、assets/、.mcp.json、.app.json 等可選結構；
• 在需要時生成或更新倉庫根（或用戶主目錄）下的 .agents/plugins/marketplace.json，控制插件在 UI 中的排序與可用性元數據。

一句話定位：Skill 解決「怎麼做」；Plugin 解決「怎麼打包、安裝、分發」；plugin-creator 負責把後者從零搭好架子。

核心功能與亮點¶

結合 SKILL.md、腳手架腳本 scripts/create_basic_plugin.py 與官方構建文檔，已覈實的能力如下。

1、標準化清單入口
每個 Plugin 的入口都是 .codex-plugin/plugin.json。只有這份清單應放在 .codex-plugin/ 下；skills/、hooks/、assets/、.mcp.json、.app.json 等放在 Plugin 根目錄。腳手架會按規範寫出完整字段形狀（含 interface 展示塊），便於你後續替換佔位內容。

2、名稱規範化
插件名會歸一化爲小寫連字符形式，且長度不超過 64 字符。例如 My Plugin → my-plugin，連續分隔符會摺疊。生成的文件夾名與 plugin.json 裏的 "name" 必須一致。

3、可選組件一鍵佔位
通過腳本參數可按需創建：

• --with-skills → skills/
• --with-hooks → hooks/
• --with-scripts → scripts/
• --with-assets → assets/
• --with-mcp → .mcp.json（初始爲 {"mcpServers": {}}）
• --with-apps → .app.json（初始爲 {"apps": {}}）

4、Marketplace 登記
加上 --with-marketplace 後，會創建或更新 marketplace.json。倉庫級默認路徑是 <repo-root>/.agents/plugins/marketplace.json；個人級常用 ~/.agents/plugins/marketplace.json。新建條目默認：

• policy.installation: "AVAILABLE"
• policy.authentication: "ON_INSTALL"
• category: "Productivity"

plugins[] 的順序即 Codex 側的展示順序；新條目默認追加到列表末尾。

5、對話內也可直接調用
官方構建文檔說明：在 ChatGPT Work 模式可用 @plugin-creator，在 Codex 中可用 $plugin-creator。不必先手寫目錄，把需求（含 MCP 的 plugin_asdk_app... ID、是否要個人 marketplace 等）說清楚即可。

安裝與啓用¶

在 Codex / ChatGPT 中使用（推薦）¶

plugin-creator 屬於系統 Skill，較新的 Codex 會自動帶上。日常用法是在對話裏顯式調用：

• Codex：$plugin-creator
• ChatGPT（Work 模式）：@plugin-creator

官方示例提示詞（測試帶 MCP 的本地插件時）類似：

@plugin-creator create a plugin for ChatGPT and Codex using my MCP server.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.

生成後按文檔覈對：.app.json 是否指向正確的 plugin_asdk_app... ID；.codex-plugin/plugin.json 的 apps 是否指向 ./.app.json；需要可複用工作流時再在 skills/ 下補充 SKILL.md。

直接跑腳手架腳本¶

若本地已有該 Skill 目錄（例如隨 Codex 安裝到 .agents/skills/plugin-creator，或從官方倉庫檢出），也可直接執行腳本。倉庫版默認在當前倉庫下創建 plugins/<plugin-name>：

# 插件名會歸一化爲小寫連字符，且 <= 64 字符
# 默認輸出到 <repo_root>/plugins/<plugin-name>
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

打開生成的 .codex-plugin/plugin.json，把 [TODO: ...] 佔位替換成真實元數據。

需要同時寫入 marketplace 時：

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

個人主目錄下的本地插件，可顯式指定路徑：

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path ~/plugins \
  --marketplace-path ~/.agents/plugins/marketplace.json \
  --with-marketplace

一次性補齊常用可選結構：

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

覆蓋已有文件或同名 marketplace 條目時才使用 --force，避免誤覆蓋。

關於其他 AI 編程工具¶

plugin-creator 本身是標準 SKILL.md 格式，Cursor、Claude Code 等同樣能讀取並按說明執行腳手架邏輯。但生成的 Plugin 包（.codex-plugin/plugin.json + marketplace）面向的是 Codex / ChatGPT Plugins Directory；在其他工具裏應把它理解爲「按 OpenAI Plugin 規範搭目錄」，而不是等價於各工具自己的擴展市場。

補充：openai/skills 倉庫 README 已提示示例與文檔正向 openai/plugins 與 Build plugins 遷移；系統 Skill 的調用方式仍以 Codex / ChatGPT 內置的 $plugin-creator / @plugin-creator 爲準。

典型用法示例¶

1. 最小可用 Plugin 結構（手工對照）¶

官方文檔給出的最小形態與腳手架目標一致：

mkdir -p my-first-plugin/.codex-plugin
mkdir -p my-first-plugin/skills/hello

.codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

skills/hello/SKILL.md：

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

再用 @plugin-creator 或手動編輯，把該插件登記進 marketplace。

2. Marketplace 條目形狀¶

腳手架寫入的插件條目形如：

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

全新 marketplace 文件還會帶上根級元數據：

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": []
}

注意：displayName 屬於 marketplace 根上的 interface，不要寫進單個 plugins[] 條目。source.path 相對 marketplace 根目錄 解析（不是相對 .agents/plugins/ 文件夾本身）。

策略字段允許值（來自 Skill 原文）：

• policy.installation：NOT_AVAILABLE | AVAILABLE | INSTALLED_BY_DEFAULT
• policy.authentication：ON_INSTALL | ON_USE
• policy.products 僅在明確要求按產品門控時再寫

3. plugin.json 裏常見字段¶

規範樣例（references/plugin-json-spec.md）中，除基礎身份字段外，常見還有：

• skills / hooks / mcpServers / apps：相對路徑，建議以 ./ 開頭；
• interface.displayName、shortDescription、longDescription：目錄與詳情頁展示；
• interface.defaultPrompt：最多 3 條，單條建議約 50 字符、上限 128 字符；
• interface 下的圖標、截圖等資源路徑，截圖需爲 PNG 且放在 ./assets/。

路徑類字段是「在默認發現之外的補充」，不會替換默認組件發現規則。

4. 用 CLI 管理 marketplace 源¶

官方文檔還提供了不手改配置的 marketplace 管理命令（與腳手架互補）：

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

本地插件改完後，通常需要重啓 ChatGPT 桌面端或按當前環境的刷新流程，才能在 Plugins Directory 看到更新。

適用場景與注意事項¶

適合：

• 要把多份 Skill、MCP、鉤子打成「可安裝包」給團隊複用；
• 想在倉庫裏維護 .agents/plugins/marketplace.json，給同事統一插件清單；
• 個人本機試驗插件，再決定是否發佈到公共 Plugin Directory；
• 已有 MCP 連接（含 plugin_asdk_app... ID），需要快速接線成 Plugin。

使用時注意：

1. 先問清落點：Skill 要求在位置不明確時，先確認是倉庫內插件還是個人主目錄插件，再寫 marketplace。
2. 佔位不要當成品：倉庫版腳手架會留下 [TODO: ...]，發佈或認真測試前必須改成真實元數據。
3. 目錄約定：僅 plugin.json 放在 .codex-plugin/；其它組件放在插件根目錄。
4. 謹慎 --force：覆蓋已有清單或同名 marketplace 條目時才用。
5. 個人目錄示例不唯一：文檔示例常見 ~/.codex/plugins/，Skill 腳本示例常用 ~/plugins/；真正生效的是 marketplace 裏 source.path 相對 marketplace 根的解析結果，兩邊對齊即可。
6. 公開分發另有流程：本地 / 倉庫 marketplace 主要用於創作、測試與團隊內分發；公開發布到通用插件目錄需遵循官方 Build plugins 後續步驟，本文不展開未覈實細節。

小結¶

plugin-creator 把 Codex Plugin 從「記得一堆目錄約定」變成「一條命令或一次對話就能搭好骨架」。對已經會寫 Skill 的開發者來說，它是邁向可安裝、可排序、可團隊分發的標準下一步；對剛接觸 Plugin 的人來說，它也是對照官方規範最快的入門路徑。

官方 Skill 目錄：
https://github.com/openai/skills/tree/main/skills/.system/plugin-creator

構建與打包文檔：
https://developers.openai.com/codex/plugins/build

Skills 總覽：
https://developers.openai.com/codex/skills