Agent Plugins 讓工具包可交付

1 個文件夾就能把技能、MCP 配置和插件清單一起打包，直接交給別的智能體客戶端用。

我最近一直被一個很煩的事卡住：工具明明做出來了，交出去卻像散件。今天補 OpenAI 這套格式，明天補一份 MCP，後天又要為 Cursor、VS Code、GitHub Copilot 各寫一版說明。功能不是沒做，是交付方式太爛。你可以把它想成一個能跑的工具箱，但每次打開都要先找螺絲起子，誰都會煩。

我是在這篇 AI Weekly 8.3-8.9 看到 OpenAI 8 月 7 日推出 Agent Plugins 1.0.0 的整理，還點名 Microsoft、AWS、Cursor、Vercel、Google 這批人一起進來。原文沒給瀏覽數或收藏數，我就不亂編。

把插件當成一個可搬走的文件夾

一個插件就是一個文件夾，裡面放 plugin.json、技能文件，還有 MCP 伺服器配置。

這句話我很買單，因為它直接把問題講死了：插件不是一堆散落的腳本，也不是 README 寫得很熱鬧的倉庫。它就是一個可搬運的交付單元。你拿走這個資料夾，理論上就該知道怎麼讀、怎麼啟、怎麼接。

翻譯一下就是，別再把「可用」和「可交付」混在一起。可用只代表你本機能跑；可交付代表別人拿到也能跑。這中間差的不是幾行代碼，是包裝方式。

我之前做過一個內部知識庫助手，功能其實不差，但每次給別的團隊，都要口頭補一輪：先裝什麼、環境變數放哪、哪個端口、哪個 client 才能接。最後大家都懶得碰。Agent Plugins 這個方向至少先把形狀定下來，讓「拿走就能跑」變成第一件事。

實操上，我會先把每個插件的責任切小：一個資料夾只做一件事，比如查工單、整理會議、拉知識庫。目錄越乾淨，別的 client 越容易直接吃進去。你要的是穩定交付，不是把一個 repo 塞到爆。

• 把插件目錄當發布單元，不要當雜物間。
• 一個插件只對應一個明確場景。
• 先讓別人讀懂，再談自動安裝。

plugin.json 是身份證，不是裝飾

這次最核心的文件是 plugin.json。我喜歡這種設計，因為它很直白：你想讓機器認識你，就先把身份講清楚。沒有清單，client 不知道你叫什麼、會做什麼、能不能信任你。

也就是說，插件的名字、版本、入口、權限、依賴，最好都壓進這份機器可讀的清單。別把這些資訊丟在 README、腳本註解，甚至聊天記錄裡。人會忘，機器根本不會去翻。

我踩過最多的坑，就是作者以為「大家都懂」。結果換一個環境，路徑不對；換一個 client，認證欄位不對；換一個人接手，整包就卡死。清單文件的價值，就是把這些默認知識變成顯式規則。

實操寫法很簡單：我會把清單拆成四塊，名稱、能力、入口、權限。名稱要穩定，能力要一句話講完，入口要能直接執行，權限要盡量小。別寫空話，別寫形容詞，別讓人看完還要猜。

• 名稱要唯一，方便搜尋和引用。
• 能力描述要短，最好能直接對應使用場景。
• 入口要明確，命令、URL、MCP endpoint 擇一寫清。
• 權限要最小化，能只讀就別寫入。

技能文件寫的是會什麼，不是怎麼吹

摘要裡提到插件包含「技能文件」，這點我覺得很重要。很多人一做智能體能力包，就開始寫介紹文案，像在賣 SaaS。問題是，模型不吃這套。模型要的是可執行的技能說明，不是漂亮話。

翻譯一下就是，技能文件要回答三件事：它能做什麼、什麼時候該叫它、叫完會得到什麼。它是給模型看的操作說明，不是給市場看的產品頁。寫得越像說明書，越有用；寫得越像廣告，越容易誤導。

我以前調過一個自動整理會議紀要的 agent，前期失敗率很高。後來我把技能描述改得很死：輸入是會議原文，輸出是三段式摘要，缺參會人就先回缺口，不准瞎補。就這樣一改，調用穩定很多。不是模型突然變聰明，是我終於把邊界寫清楚。

實操上，我會要求每個技能文件固定有五段：用途、輸入、輸出、失敗條件、示例。尤其是示例，別省。模型會從示例裡學到調用節奏，工程師也能直接驗格式。你要的是可重用，不是看起來很完整。

如果你要把插件交給別的團隊，技能文件其實比代碼更值錢。代碼能改，技能邊界寫錯了，整個包都會被誤用。

MCP 配置直接打包，別讓人手工補洞

這次最實際的一點，是插件包裡直接帶 MCP 伺服器配置。對我來說，這比「支援多少 client」更重要。因為只要接入方式一起打包，插件就不只是工具，而是一個完整的上下文服務入口。

也就是說，你不是只發一個功能，你是在發「功能 + 接法」。client 不用猜你怎麼連，開發者也不用再手搓一次設定。這件事很瑣碎，但真的省命。

我踩過的坑幾乎都在這裡。工具本身沒問題，問題是每個環境都要重寫配置。今天本地能連，明天 CI 失敗，後天換 client 又要改 port、改認證、改路徑。最後大家直接放棄。MCP 配置如果能跟插件一起交付，至少能把這類重工砍掉一大截。

實操上，我會把 MCP 配置當成預設接入層，而不是後補文件。把服務地址、認證方式、暴露能力寫進包裡，讓 client 能直接讀。再另外提供覆蓋項，給進階使用者改環境變數或本地配置。預設值要能跑，覆蓋項要能改，這才像能維護的包。

• 預設配置放包內，方便開箱即用。
• 敏感資訊用外部注入，不要硬編碼。
• 提供覆蓋項，別把使用者鎖死。

這次真正值錢的是多方一起對齊

這份整理裡最有意思的，不只是 OpenAI 發了標準，而是 Microsoft、AWS、Cursor、Vercel 都被拉進同一套交付語言裡。再加上 Google 以 Core Maintainer 身份加入，還丟出 Agents CLI 和 Data Agent Kit，這就不是單點產品更新了。

翻譯一下就是，如果一個插件只能在單一 client 裡跑，它的價值會被鎖死。反過來，如果多個 client 都認同同一套打包方式，你的維護成本就會掉下來。你不用每個平台重寫一次，只要把包做對。

我最在意的是 Google 的位置。它不是站旁邊喊加油，而是直接以 Core Maintainer 身份進來，還把生產工具一起補上。這代表標準化的不只是消費端，連產出端也在收斂。生產端一旦統一，工具鏈才真的會省事。

實操上，我會先看自己的工具能不能塞進這套結構。就算不能完全照搬，也至少要保證包結構、清單、服務配置能被別的 client 理解。別把自己做成孤島，不然你永遠都在維護自己的私有協議。

我會怎麼把它落地到專案

如果是我來做，我不會先急著補功能。我會先把插件目錄設計成最小可發布單元。意思是，這個資料夾一出來，就應該能被別人讀、改、跑。先把包裝做好，再談能力擴張。

第一步，我會定義邊界，一個目錄只服務一個場景。第二步，我會寫清單文件，把名稱、版本、入口、權限寫死。第三步，我會把技能文件寫成機器友好的說明，帶輸入輸出示例。第四步，我會把 MCP 配置放進目錄，並提供環境覆蓋。最後才接 Cursor、VS Code、ChatGPT 這些 client。

這個順序很重要，因為大多數失敗不是功能不夠，而是別人接不進來。你要先讓別人能接，再談別人願不願意用。順序錯了，後面全是返工。

我也會給每個插件加一個最小自檢腳本。讀清單、檢查 MCP、跑一個 sample call，三步過一遍。別等使用者報錯才處理。只要你開始分發，測試就不是加分題，是基本功。

可抄的模板

agent-plugin-name/
├── plugin.json
├── skills/
│   ├── README.md
│   └── summarize.md
├── mcp/
│   └── server.json
├── scripts/
│   └── self-check.sh
└── examples/
    └── invoke.md

# plugin.json
{
  "name": "agent-plugin-name",
  "version": "1.0.0",
  "description": "One-line description of what this plugin does.",
  "entry": {
    "type": "mcp",
    "config": "mcp/server.json"
  },
  "skills": [
    {
      "id": "summarize",
      "file": "skills/summarize.md",
      "purpose": "Turn raw input into a structured summary"
    }
  ],
  "permissions": {
    "network": "read-only",
    "filesystem": "scoped"
  },
  "clients": ["VS Code", "Cursor", "GitHub Copilot", "ChatGPT", "Codex", "Kiro"]
}

# skills/summarize.md
## Purpose
Summarize input into a short, structured output.

## Input
- source_text: raw text
- tone: concise | neutral | technical

## Output
- title
- bullets
- action_items

## Failure conditions
- Missing source_text
- Input too large for configured context

## Example
Input: meeting notes
Output: 3 bullets + 2 action items

# mcp/server.json
{
  "name": "agent-plugin-name-mcp",
  "command": "node",
  "args": ["dist/server.js"],
  "env": {
    "PORT": "${PORT:-3000}",
    "API_KEY": "${API_KEY}"
  }
}

# scripts/self-check.sh
#!/usr/bin/env bash
set -euo pipefail

echo "1) validate plugin.json"
cat plugin.json >/dev/null

echo "2) validate MCP config"
cat mcp/server.json >/dev/null

echo "3) run a sample invocation"
./run-sample.sh

echo "OK"

# examples/invoke.md
1. Install the plugin folder.
2. Read plugin.json.
3. Start the MCP server.
4. Call the summarize skill with sample input.
5. Verify the output matches the example.

這份模板不是官方原文，我是根據 原始整理，再加上我自己的工程化拆法寫出來的。原始來源 URL 我放在這裡：https://zhuanlan.zhihu.com/p/2069889254105392703。我寫的是可直接拿去改的版本，不是逐字搬運。