AIREITER

Claude Skills API 正式版改了什麼？實作方式與版本控管陷阱

最近更新: 2026-08-21 00:26:10

Anthropic 在 2026 年 8 月 20 日正式將 Claude Skills API、computer use 與 Files API 推向 GA。Beta headers 不再需要；computer use 現在可在單次模型呼叫中執行多個動作，也新增了 browser use 工具。不過，GA 並沒有解決一個核心問題：Skill 是否啟用，仍取決於 Claude 自己判斷要不要呼叫。因此，版本釘選與觸發設計依然得由你負責。

Anthropic 宣布 computer use、Skills API 與 Files API 現已正式推出

8 月 20 日 GA 到底帶來哪些改變？

既有的 Beta 整合在遷移期間仍可繼續使用。根據 Anthropic 的發布公告，這次更新不只是拿掉 Beta 標籤，而是一次帶來多項實質調整：

  • 不必再設定 Beta header。目前的Skills guide只列出兩項前提：Claude API key，以及在請求中啟用 code execution。過去 Beta 教學要求的 headers，已不再出現在官方文件中。
  • 單回合可執行多個操作。更新後的 computer use 工具能在每次模型呼叫內處理多個動作，例如點擊、輸入、按鍵與截圖，不再只能一次執行一項。Anthropic 的 @ClaudeDevs 帳號表示，早期存取客戶每項任務的往返次數減少 20–40%。
  • 新增 browser use 工具。它將截圖與頁面結構資訊結合，讓 agent 能鎖定特定欄位或按鈕，而非依賴像素座標；主要適用於保險申請這類網頁入口流程。
  • Files API 擴容。每個 organization 可使用 1 TB 儲存空間，速率限制提高為 5 倍，依 @ClaudeDevs 討論串所述為 500 RPM，並支援檔案自動到期。
  • 合規使用途徑。computer use 現已可在 Anthropic BAA 架構下，用於受 HIPAA 規範的工作負載。
  • 雲端平台支援。Skills API 與 Files API 也已透過 Microsoft Foundry 提供；更新後的 computer use 和 browser use 工具則標示為即將登上 Vertex AI，但尚未公布日期。

Files、Skills、computer use 如何串成一個流程

Anthropic 以理賠 agent 為例，完整展示這三組 API 的搭配方式：先透過 Files API 以檔案 ID 取得申請文件，再由 Skills API 套用包含申報流程的 Skill，接著利用 browser use 填寫保險公司的入口網站，最後把確認結果存回檔案。文件只要上傳一次，之後以 file_id 引用即可，不必每次請求都重新傳送。

這次發布時公布的兩組成效數字，都來自供應商端資料。在發布公告中，研究工程師 Davide Locatelli 表示，最長的理賠工作流程從 32 分鐘降至 13 分鐘，完成率達到 100%。另外，Asteroid 共同創辦人 David Mlčoch 在早期存取階段測試醫療領域的 computer-use 流程，結果如下：

「模型呼叫次數減少 32-52%，每項任務成本降低 25-32%，所有工作流程完成率皆達 100%，高於原本的 77%。」— @MlcochDavid

早期存取客戶所回報的 GA agent 工具導入前後，理賠流程耗時與完成率變化

在 Messages API 請求中掛載 Claude Skills API

要掛載 Skill，只需在 Messages API 請求加入一個參數：container 物件，並在其中放入 skills 陣列。每個項目包含 type（anthropic 或 custom）、skill_id，以及選填的 version。

依照官方 Skills guide，使用這個參數時還有以下規則：

  • 必須啟用 code execution，且模型本身要支援該功能。官方範例使用 claude-opus-5、code_execution_20250825 工具類型，以及 max_tokens=4096。
  • 單一請求最多可帶入 20 個 Skill。
  • Skill 會在 Anthropic 的 code-execution sandbox 中執行：不能連網、不能在執行期間安裝套件。若未跨回合重用回傳的 container.id，每次請求都會建立新的 container；每份回應都會包含 expires_at。
  • 你不需要自行託管 Skill 檔案，Anthropic 會在 container 內執行它們。
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=[{"type": "code_execution_20250825"}],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "20251013"},
            {"type": "custom", "skill_id": "skill_01...", "version": "skver_01..."},
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue summary"}],
)

輸入文件則走相反方向：先經由 Files API 上傳，再於 container upload 區塊中引用。請求結構仍是標準的 Anthropic Messages API，因此可直接使用 API key，也能透過 Anthropic 相容的轉送服務，例如 AIReiter's Claude API。

內建 Skill 採用簡短、易讀的 ID，例如 pptx、xlsx、docx、pdf；版本則可使用 20251013 這類日期格式，或 latest。自訂 Skill 則會取得限定於你的 workspace 的 skill_01... ID。

上線自訂 Skill 前，先看這些會被拒絕的規則

自訂 Skill 是一個目錄，最上層必須有 SKILL.md，內含 YAML frontmatter，例如 name 與 description；同一目錄下也可以放腳本與參考檔案。最小可用版本如下：

---
name: eu-claims-filing
description: Use when filing or amending EU insurance claims. Loads the
  carrier-specific submission procedure, required fields, and rejection
  codes before filling any portal form.
---

# EU claims filing procedure
1. Pull the intake document by file_id ...

上傳時可使用 ZIP 封存檔，或分別上傳個別檔案；Python SDK 提供 files_from_dir。不過在 Skill 執行前，Anthropic 就會依Skills guide套用以下硬性限制：

項目限制
name≤64 個字元；限小寫英文字母、數字與連字號；anthropic 和 claude 為保留字
description1–1,024 個字元，不可為空，且不得包含 XML tags
display_name（選填）≤255 個字元
Bundle 大小解壓縮後須小於 30 MB
每次請求的 Skill 數量20
每個 organization 的 workspace 數量預設 100 個

同一份文件指出，管理工作可透過 ant CLI 或其背後的 API endpoints 處理。從本機檔案建立到釘選版本的流程如下：

ant skills create ./eu-claims-filing   # returns skill_01...
ant skills:versions create skill_01...  # returns skver_01... — pin this in production

團隊第一次使用時，常會忽略兩件事：新版本是完整快照，你必須重新上傳全部檔案，沒有上傳的檔案不會自動保留；此外，刪除一個 Skill 會一併刪除它的所有版本。

正式環境檢查表：釘選、隔離、快取

在正式環境最容易出問題的地方，包括可變動的版本、workspace 範圍的權限，以及快取失效；Skills guide對這三點都有明確說明。

  1. 釘選版本。若使用 latest 或根本不指定版本，只要有 workspace 存取權的人上傳新版本，已部署的 agent 執行內容就會立即改變。正式環境應釘選 skver_... ID；latest 留給持續開發中的情境。
  2. 把 workspace 視為租戶隔離邊界。同一個 workspace 內的每把 API key，都能讀取、呼叫及刪除其中所有自訂 Skill。隔離邊界是 workspace，不是使用者或 session。多租戶應用程式應為每個租戶建立一個 workspace，同時注意預設上限為 100 個 workspace。
  3. 維持 Skill 清單固定，才能吃到快取。只要變更 Skill 清單，包含調整順序，都會改變 system-prompt prefix，進而讓 prompt cache 失效。釘選自訂版本同樣能保護這個 prefix，因為重新上傳的 latest 描述內容可能改寫它。採按 token 計費時，請求之間若 Skill 清單不斷變動，快取命中節省的成本會在不知不覺間消失。
  4. 處理 pause_turn。執行時間較長的 Skill 會回傳 stop_reason: "pause_turn"；請在後續請求中重新傳送回傳內容以繼續執行，或調整對話內容來中斷流程。
  5. 確認資料保留政策。Agent Skills 不包含在 zero-data-retention 安排中；Skill 定義與執行資料均遵循 Anthropic 的標準資料保留政策。啟用 Compliance API 後，Activity Feed 會記錄 Skill 與 Skill version 的建立、刪除活動，但只涵蓋啟用之後的事件。
  6. 捕捉正確的錯誤類型。呼叫時應包裝處理 anthropic.BadRequestError，並將 Skill 相關失敗與其他無效請求錯誤分開處理。
  7. 別掛上不會用到的 Skill。官方文件直接指出，帶入未使用的 Skill 會影響效能。

GA 無法替你解決的：Skill 觸發問題

GA 升級的是 Skill 周邊基礎設施，不是 Claude 選擇 Skill 的邏輯。從以下使用者討論可看到一項反覆出現的疑慮：Skill 比較像由條件觸發的程序，不是第二層 system prompt。

「我對 Claude Skills 的問題是，它們根本不是 skills。沒有任何機制強制 Claude 真正使用它們。Claude 愛怎麼做就怎麼做……這些就只是 md 檔。」— @Yampeleg，發言於 GA 前；呼叫機制至今未變

r/ClaudeAI 關於 Skills 是否真的有效的討論串，整理出幾個實務上的改善方向：

「userstyle 每回合都會被前置加入，但 skills 只有在 Claude 根據 description 判定需要呼叫時才會啟用。」— u/samxu01

「Skills 必須具備簡單明確的 metadata description，並聚焦在 Claude 正在執行的動作。」— u/Chadum

從這些討論可歸納出四條原則：

  • description 應圍繞觸發語句與要執行的動作，而不是塑造角色人設。
  • 把步驟、檢查項目、規則與工具選擇放在正文。u/MartinMystikJonas 的判準是：「如果你的 skills 定義了 agent 應執行的步驟、該檢查的內容、應遵守的規則與應使用的工具，它就是有用的。」
  • 依 u/Actual_Committee4670 的建議，將 Claude 原生表現不佳的事情編碼進 Skill。
  • 每回合都必須套用的要求，應放進 system prompt 或 CLAUDE.md；如同上面 u/samxu01 所述，它們每回合都會被前置加入。Hook 則保留給 commit 前這類生命週期節點。

常見問題快速回答

Skills API 還需要 Beta headers 嗎？

不需要。自 2026 年 8 月 20 日 GA 後，目前文件列出的前提只有 Claude API key 與已啟用的 code execution，不再要求 Beta header。

Skill 會吃掉 context window 嗎？

一開始只會占用 metadata。根據Skills guide，Claude 會先收到各 Skill 的 frontmatter，將檔案複製到 container，只有在任務需要時才載入完整指令。這也是文件提醒不要附加未使用 Skill 的原因。

Skill 和 MCP 有何不同？

Skill 是在 Claude sandbox 中執行的指令與腳本套件，無法連網；MCP 則讓 Claude 連接即時的外部系統。這是 Anthropic 在其Skills overview中所做的區分。理賠工作流程可以同時使用兩者：用 MCP server 連接保單資料庫，用 Skill 處理申報程序。

同一份 SKILL.md 能在 Claude.ai、Claude Code 和 API 執行嗎？

SKILL.md 格式通用，但不同介面的交付方式不同：API 使用上傳至 workspace 的 Skill；Claude Code 使用 .claude/skills 目錄；Claude.ai app 則採用方案層級的上傳機制。

Skills API 可用於 zero data retention 嗎？

不行。Agent Skills 不包含在 zero-data-retention 安排內；Skill 定義與執行資料適用標準資料保留政策。

不同需求該用哪一種機制？

關鍵在於你希望它何時被呼叫：

需求適合的機制
在特定條件下執行的專門任務，例如「申報理賠時，遵循以下步驟」Skill
每一回合都必須套用的規則System prompt（API）／CLAUDE.md（Claude Code）
生命週期特定節點的動作，例如工具執行後、commit 前Hook
與外部系統建立即時連線MCP server
一次性的任務要求Plain prompt

8 月 20 日讓 Skill 機制具備了正式環境可用性，但沒有讓這張表中的各種機制變得可以互相替代。

延伸閱讀：Claude API pricing per model and token 與 recording a Claude skill in Claude Code。