構建自己的外掛

Codex plugin 是分發單元，用來把 skills、MCP 配置、app integration 或其他能力打包給別人安裝。它不是“把一段 prompt 包起來”。

新手最常見的錯誤，是本來只需要本地 skill，卻一上來做 plugin、marketplace 和釋出目錄。

自己用先寫 skill；團隊複用再考慮 plugin；需要 Codex 發現和安裝一組 plugin，才需要 marketplace。

Build plugins

檢視官方 plugin manifest、目錄結構和 marketplace 說明。

Plugins

理解 plugin 的安裝、管理和使用方式。

Skills

如果只是複用流程，先做 skill。

三個概念

flowchart LR
    Skill["Skill<br/>工作方法"]
    Plugin["Plugin<br/>分發包"]
    Marketplace["Marketplace<br/>發現和安裝目錄"]

    Skill --> Plugin
    Plugin --> Marketplace

Skill 解決：

Codex 在某類任務上應該怎麼做。
觸發條件、步驟、輸出和驗證。

Plugin 解決：

把一組能力打包給別人安裝。
可以包含 skills、MCP、hooks、app mappings 等。

Marketplace 解決：

Codex 從哪裡發現 plugin。
團隊或個人如何維護可安裝清單。

什麼時候該做 plugin

適合：

能力已經被反覆使用。
有清楚名稱、說明、輸入邊界和使用場景。
安裝後別人能直接在 Codex 裡發現。
需要一起分發 skill、MCP 或其他配置。
願意維護版本、相容性和變更記錄。

不適合：

只是一次性 prompt。
skill 還沒跑穩。
只服務當前儲存庫的臨時任務。
還沒想清楚許可權和外部依賴。
只是為了目錄看起來更工程化。

第一版應該儘量小

第一版 plugin 建議只包含一個穩定 skill。

最小結構：

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md

說明必須寫清：

外掛解決什麼任務。
什麼時候應該呼叫。
什麼時候不應該呼叫。
是否需要 token、MCP、外部網路或賬號。
安裝後如何確認生效。

不要第一版就塞多個 skills、多個 MCP servers 和複雜 hooks。包越大，排錯越難。

最小 manifest 放在 .codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow for one stable Codex task.",
  "skills": "./skills/"
}

name 使用穩定 kebab-case。Codex 會把它當成 plugin identifier 和 component namespace。

Marketplace 怎麼放

Marketplace 是 JSON catalog，不是 plugin 本身。常用位置：

範圍	檔案
Repo marketplace	`$REPO_ROOT/.agents/plugins/marketplace.json`
Personal marketplace	`~/.agents/plugins/marketplace.json`

本地 repo marketplace 的最小條目：

{
  "name": "local-repo",
  "interface": {
    "displayName": "Local Repo Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

source.path 必須相對 marketplace root，並以 ./ 開頭。修改 marketplace 或 plugin 後要重啟 Codex；local plugin 會被安裝到 Codex cache 中，Codex 讀取的是安裝後的副本，而不是你剛編輯的源目錄。

也可以用 CLI 新增 marketplace：

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

釋出前檢查

釋出前確認：

plugin name 穩定。
version 清楚。
description 能觸發正確任務。
不包含金鑰、token、私有 URL。
外部依賴寫明。
禁止事項寫明。
關閉 plugin 後不會留下全域性副作用。

如果外掛會呼叫外部系統，還要說明許可權、資料流和審計方式。

安裝後怎麼驗證

本地驗證不要只看檔案存在，要在 Codex 裡確認：

/plugins 能看到對應 marketplace。
plugin details 能展示名稱、說明和 category。
安裝後 bundled skills 能被呼叫。
需要認證的 app 或 MCP 會在 install 或首次使用時提示。
停用 plugin 後，相關能力不再觸發。

如果外掛包含外部 app、MCP server 或 hooks，還要單獨確認許可權提示和失敗路徑。安裝 plugin 只是讓 workflow 可用，Codex 現有 approval settings 仍然生效，外部服務仍受自己的認證和隱私策略約束。

常見坑

marketplace 路徑寫錯。
修改後忘記重啟或重新整理 Codex。
description 太泛，導致誤觸發。
把敏感配置打進外掛。
缺少版本和變更記錄。
安裝說明只適用於作者機器。
skill 和 plugin 職責混在一起。

Plugin 的目標是分發穩定能力，而不是提前包裝不穩定流程。