Cloudflare 在 2026 年 10 月 29 日更新 Agents SDK 的 Agent Skills：技能可直接存成 agent Workspace 內的檔案，也可從 R2 或程式 manifest 載入。對 Think agent 而言，/workspace/.agents/skills/ 下新增或修改的 SKILL.md，下一回合即可被重新列入技能目錄，不必重新 build 或部署。
同日發布的 [email protected] 與 @cloudflare/[email protected] 不只是新增來源，也包含破壞性調整：原有 SkillRegistry 被 loadSkillCatalog() 與 createSkillTools() 取代，agents:skills 的 Vite import 與 compile 路徑移除，runner 的 import 位置也改變。已使用舊版 skills API 的專案，不應只把套件版本升上去就直接發布。
檔案化降低部署摩擦，也擴大變更入口
Cloudflare 的 Agents changelog示範 skills.workspace(this.workspace)：agent 可在 Workspace 讀取技能，甚至寫入自己的 skills。這讓客服 SOP、資料查核流程、發布規則等程序可以與主程式分開更新，也讓不同 agent 共用一套 R2 skill library。
但「不用部署」同時代表程式碼審查與部署審批不再天然涵蓋所有行為變更。如果任何使用者輸入、外部工具或 agent 自己都能寫入 skills 目錄，一段被污染的指令可能在下一回合進入目錄；若又允許 skill script 執行，影響就不只回答內容，還可能包含檔案、網路或憑證可達範圍。
因此先把 skill 視為可執行的營運設定，而不是普通知識文件。定義誰能建立、誰能發布、哪些來源可被正式環境載入、變更如何回滾，以及 script runner 能使用哪些能力。Workspace 適合單一 agent 的暫存或受控自我改善；R2 適合集中發布；manifest 適合必須隨程式版本固定的核心規則，三者不是互相替代的同一種儲存。
先盤點舊 API，再做雙軌驗證
GitHub 官方 release列出 0.32.0 的升級範圍。先搜尋 SkillRegistry、agents:skills、agents/skills/compile、舊 runner import、skillWorkspace 與自訂 context block；建立呼叫位置、測試與 owner 清單。若同時使用 Think，應一起確認相容版本，避免只升其中一個套件後產生型別或執行期差異。
建立一個最小測試 agent，在隔離環境同時載入 Workspace、測試 R2 prefix 與 manifest。準備正常 skill、缺少 description、名稱不符、重複名稱、無法讀取來源與惡意路徑等案例，比對新 catalog 的 diagnostics。Cloudflare 文件說明，部分格式錯誤會以 warning 載入，部分會直接跳過；應明確決定正式環境要接受 warning、阻擋發布，還是只告警。
升級期間可讓舊版與新版針對同一組固定任務做 shadow evaluation，比對啟用的 skill、讀取的 resource、tool calls 與最終結果，但不要讓兩邊同時執行有副作用的工具。需要回滾時，保留舊套件 lockfile、舊 catalog adapter 與已發布 skill snapshot；只回滾應用而保留新版 skill 格式，可能讓舊程式無法載入。
Skill 格式要能被機器驗證
Cloudflare Agent Skills 文件說明，每個 skill 是一個資料夾，以 SKILL.md 為入口，並可包含 references、scripts 與 assets。目錄只先把名稱與 description 放進提示，任務匹配後才載入完整內容，這種 progressive disclosure 能避免所有程序長期佔用 prompt。
正式發布管線至少檢查 frontmatter、資料夾與 name 一致、description 存在、資源路徑不能逃出 skill 目錄、重複名稱、檔案大小、允許的 MIME type 與 script 清單。可使用 SDK 的 parseSkill() 做規格檢查，但仍需要自己的政策檢查；「格式合法」不等於「指令安全或符合公司流程」。
description 也是路由規則的一部分。寫得過度廣泛會讓不相關任務頻繁載入，寫得太窄則不會被選到。測試集應包含應啟用、不可啟用與多 skill 競爭三類案例，並在每次變更後跑選擇率與錯誤啟用回歸。核心安全規則、資料界線與每回合都必須遵守的要求，應留在 system prompt 或固定 context，而不是藏在「可能被選中」的 skill。
Workspace、R2 與 manifest 如何選
Workspace 來源適合 agent 專屬、會在任務中產生或修改的程序，例如特定專案的暫存 runbook。優點是下一回合可讀到新內容；代價是生命週期、租戶隔離與寫入權限必須清楚。多租戶服務不可讓不同客戶共用可寫目錄，也不應把 secret 寫進 SKILL.md 或 resource。
R2 來源適合團隊共同維護的大型技能庫與版本化發布。使用 immutable version prefix，例如 skills/releases/2026-11-02/，再以受控指標切換目前版本，能比直接覆寫同一 key 更容易稽核與回滾。R2 讀取失敗時，應決定 agent 是停用受影響功能、退回上一份快取，還是拒絕高風險任務；不能靜默改用不完整流程。
Manifest 適合登入、付款、刪除與權限核准等必須和程式同版的核心程序。它犧牲即時更新，換得 code review、測試與部署原子性。實務上可混用：核心安全 skill 固定在 manifest，通用營運知識由版本化 R2 提供，Workspace 只允許低風險個人化內容；來源順序與同名衝突策略要固定並監控。
Script runner 必須另設沙箱與能力清單
新的 skill tools 包含 activate_skill、read_skill_resource；只有設定 runner 時才加入 run_skill_script。如果需求只要讀取作業說明，不要因為 skill 資料夾可能有 scripts 就預設開啟執行能力。需要執行時，限制 CPU、時間、記憶體、檔案根目錄、網路目的地與環境變數，並將每次腳本 hash、skill version、輸入與結果寫入稽核紀錄。
腳本不可直接取得整個 Workers environment。為每一類 skill 提供窄化工具，例如只能讀特定 bucket prefix、建立草稿而不能發布、產生查詢計畫而不能直接改正式資料。高影響操作要在 skill 外層再次做身分與參數驗證，不能相信文字指令已要求 agent 先確認。
也要防止資源內容的 prompt injection。從外部網站、使用者上傳或第三方 repository 匯入的文件先進 quarantine，做來源與 license 檢查，再由人員核准成為正式 skill。即使是團隊 R2，寫入憑證也應和執行環境讀取憑證分開，避免 agent 自己覆寫其下一回合會遵循的規則。
用可觀測性判斷升級是否成功
每回合記錄 catalog fingerprint、來源版本、啟用 skill、validation diagnostics、resource 讀取與 tool error，但遮罩使用者資料與憑證。部署後比較 skill 命中率、未知 skill、來源讀取失敗、腳本失敗、token 使用與人工接手率；若只看 HTTP 成功，可能漏掉 agent 已悄悄跳過無效 skill、改用一般推理完成任務。
先在內部 agent 或低風險流程試行，限制可用 skill 與工具，再擴大租戶。驗收包含新增、修改、刪除、同名衝突、R2 暫時不可用、Workspace 被寫入無效檔案、版本回滾與長對話 compaction。Cloudflare 文件仍把此 API 標為 experimental，因此套件升級應固定版本並閱讀 release notes，不宜在正式環境無條件追 latest。
檔案式 Skills 的價值是把可重用程序變成可攜、按需載入的資產；風險則是讓 agent 行為可在應用部署之外改變。把來源分層、格式與政策一起驗證、限制 script runner、版本化發布並保留稽核，才能利用下一回合即生效的速度，而不把供應鏈與權限控制一起省略。