OpenAI API 最近推出了一組新的 agentic 原語，核心概念叫做「Skills」，搭配升級版的 Shell tool 和 server-side compaction，目標是讓 AI agent 能夠真正執行長時間、多步驟的知識工作。

這個方向蠻值得關注的，因為它代表了一個明確的產業趨勢: 我們正從「單次問答」走向「agent 持續執行真正的工作」。

Skill 是什麼?

簡單講，就是你可以把一包工作流程（指令 + 腳本 + 範例資料）註冊到 OpenAI API 上，變成一個有版本控制的「skill」。OpenAI 會自動把這些 skill 的 name 和 description 插入 system prompt，讓模型知道有哪些 skill 可以用，然後由模型自動判斷什麼時候該挑選和執行哪個 skill。

你可以把它想成是給 model 用的「SOP 手冊」——每個 skill 裡面有一個 SKILL.md 作為 manifest，定義什麼時候用、怎麼跑、預期產出是什麼。

關鍵特性:

  1. 可重複使用: 同一個 skill 可以掛載到不同的 agent 和 prompt 上
  2. 有版本控制: 支援 version pinning，production 環境可以釘死特定版本
  3. 按需載入: 不用的 skill 不會消耗 token，只有被觸發時才會讀入指令
  4. 相容開放標準: 遵循 Agent Skills 開放標準（這個標準早於 OpenAI 的這個 API 功能）

三個原語搭配使用

OpenAI API 這次推出的其實是三個互相搭配的東西:

🔹 Skills: 把穩定的工作流程打包成可複用的 bundle，註冊到 OpenAI API，由平台自動注入 system prompt 讓模型選用

🔹 Shell tool (升級版): 提供真正的執行環境。Hosted shell 讓 agent 在 OpenAI 託管的 container 裡安裝套件、跑腳本、寫產出物；也支援 local shell 模式，在你自己的機器上跑

🔹 Server-side compaction: 長時間對話會超過 context window，compaction 會自動壓縮歷史對話，讓 agent 不會因為跑太久就中斷

三個加起來，agent 就能做到: 依照 SOP 執行 → 在真正的環境裡跑程式 → 長時間持續工作不中斷。

Skills 的定位: 介於 Prompt 和 Tool 之間

OpenAI 提出了一個蠻清楚的三層架構:

  • System prompt: 全域行為和限制，每一輪都會生效的東西（安全規則、語氣等）
  • Tools: 對外界做事的能力（呼叫 API、查資料庫、寄信）
  • Skills: 可打包的程序（指令 + 腳本 + 資源），只有需要時才載入

以前很多人把複雜的工作流程塞在 system prompt 裡，結果 prompt 越來越肥、越來越脆弱。Skills 的定位就是把這些穩定的程序抽出來，變成獨立的、可版本控管的 bundle。

實務上怎麼用

建立 Skill

一個 skill 就是一個資料夾:

csv_insights_skill/
├── SKILL.md          # manifest + 指令
├── requirements.txt  # 相依套件
├── run.py           # 執行腳本
└── assets/
    └── example.csv  # 範例資料

SKILL.md 的 frontmatter 定義 name 和 description，內文則是完整的執行指令。

上傳和掛載

透過 API 上傳 skill bundle（zip 或 multipart），然後在呼叫 Responses API 時把 skill 掛載到 shell tool 的環境裡:

response = client.responses.create(
    model="gpt-5.2",
    tools=[{
        "type": "shell",
        "environment": {
            "type": "container_auto",  # hosted shell
            "skills": [
                {"type": "skill_reference", "skill_id": "<id>"},
            ],
        },
    }],
    input="分析上傳的 CSV 並產出報告"
)

也支援 local 模式，把 container_auto 改成 local 就好，skill 的行為一樣，只是在你自己的機器上執行。

幾個值得注意的設計 Tips

OpenAI 的 blog 分享了從內部和早期客戶 Glean 得到的經驗:

  1. Skill 的 description 要寫成路由邏輯: 包含「什麼時候用」和「什麼時候不用」，加上 negative examples。Glean 發現加了 negative examples 之後，觸發準確率明顯提升

  2. 模板和範例放在 skill 裡面: 不用時不佔 token，用到時才載入。Glean 說這帶來了最大的品質和延遲改善

  3. 要確定性就直接指定: 預設是 model 自己決定用不用 skill，但 production 環境想要確定性的話，直接在 prompt 說「Use the XXX skill」

  4. 網路存取要小心: Skill + 開放網路 = 高風險的資料外洩路徑。預設應該嚴格控制 allowlist

  5. 用 domain_secrets 處理認證: model 只看到 placeholder，實際的 credential 由 sidecar 注入，避免洩漏

Glean 的實戰數據

早期客戶 Glean 的案例蠻有參考價值:

  • 一個 Salesforce 導向的 skill 把 eval 準確率從 73% 拉到 85%
  • Time-to-first-token 降低 18.1%
  • 他們用 skills 來編碼企業內部的反覆工作流: 客戶規劃、升級分流、品牌內容產出

ihower 的實際測試心得 (2025/2)

ihower 實際測試了一下，有幾點觀察:

運作機制: 把 skill 註冊上去之後，OpenAI 會自動在 system prompt 插入 skill 的列表（name、description、path），讓模型自行判斷要不要用。概念很直覺，但實際的透明度有待加強。

透明度問題: 自動插入的 system prompt 在 OpenAI 後台看不到 log，到底精確長什麼樣子不知道，只知道會是 skills list。而且當模型挑選了某個 skill 之後，在 log 中也看不出來是否真的發生了「載入 skill」這個步驟，只看到模型直接去執行了。Hosted shell 這樣的行為不太透明，debug 起來會比較困難。

Local shell 還不穩定: 實際測試 local shell 模式時，會碰到 API 錯誤:

openai.BadRequestError: Error code: 400
Missing required parameter: 'tools[0].environment.skills[0].name'

看起來 local shell 搭配 skill_reference 的參數驗證還有 bug，目前用起來沒有文件描述的那麼順暢。

整體來說，概念方向是對的——把穩定工作流從 prompt 裡抽出來做成可複用的 bundle，這個需求確實存在。但目前的實作在透明度和穩定度上還需要打磨，特別是對於需要精確控制和 debug 的 production 場景。

Updated: 文件有更新

Skills API 文件有更新。Local shell 不支援用 skill_reference，必須要傳 name、description、path，而且 skill 檔案也要放本機。但 cookbook 上的範例仍是錯的。

Coding Agent vs. Agent 框架: Skills 是兩回事

ihower 在這個 OpenAI API 功能推出之前，就在 OpenAI Agents Python SDK 提了一個 agent skills pattern 的 PR，研究過程中有一個重要的觀察: coding agent 的 skills 和一般 agent 框架的 skills，其實是兩個很不同的東西。

底層都是 progressive disclosure: 不管是 Pydantic AI 的 list_skills/load_skill，還是 Codex 透過 bash 讀檔載入 skill，本質上都是同一個 pattern——讓模型需要時才載入指令，而不是一開始就全塞進 prompt。差別在於載入的方式和 skill 存放的位置。

兩個場景的需求差很多:

  • Coding agent（如 Codex）: skill 是檔案系統上的一包檔案，有腳本可以直接執行。因為 coding agent 本來就有 shell 存取能力，讀檔和跑腳本都是自然的操作。Agent Skills 標準主要就是對應這個場景。

  • 非 coding agent（一般 agent 框架）: skill 不一定要存在檔案系統，可能從資料庫來，腳本執行也是 optional 的。讓 agent 可靠地使用 skill，本質上是 prompt 設計的問題，用 function calling 就能實作，不需要特殊的 SDK 內建支援。

而 OpenAI 這次推出的 Skills API，其實提供了另一種選擇: skill 存在 OpenAI 後台，載入 skill 發生在 server-side，不需要額外的 API 往返。相比 coding agent 從本機檔案讀取、或透過 function call 回傳 skill 內容，這種方式在速度上會更快一點。

這裡有個潛在的期望落差: 開發者聽到「skills」容易聯想到像 Codex 那樣的完整系統——安裝社群 skill、開箱即用。但對一般 agent SDK 來說，使用場景不同，與其叫「agent skills」，不如把它理解為「progressive disclosure」這個設計模式，更不容易產生誤解。

參考連結: