Agent Skills

為什麼使用 Skills

Skills 是可重複使用、基於檔案系統的資源，為 Claude 提供特定領域的專業知識：工作流程、上下文和最佳實踐，將通用代理轉變為專家。與提示（針對一次性任務的對話級指令）不同，Skills 按需載入，無需在多次對話中重複提供相同的指導。

主要優點：

• 專業化 Claude：為特定領域任務量身定制能力
• 減少重複：一次創建，自動使用
• 組合能力：結合 Skills 構建複雜工作流程

使用 Skills

Anthropic 為常見文件任務（PowerPoint、Excel、Word、PDF）提供預建的 Agent Skills，您也可以創建自己的自定義 Skills。兩者的工作方式相同。Claude 會在與您的請求相關時自動使用它們。

預建 Agent Skills 可供 claude.ai 上的所有用戶以及通過 Claude API 使用。請參閱下方的可用 Skills 部分以獲取完整列表。

自定義 Skills 讓您封裝領域專業知識和組織知識。它們可在 Claude 的各個產品中使用：在 Claude Code 中創建、通過 API 上傳，或在 claude.ai 設置中添加。

Skills 的工作原理

Skills 利用 Claude 的虛擬機環境提供僅靠提示無法實現的能力。Claude 在具有檔案系統訪問權限的虛擬機中運行，允許 Skills 以包含指令、可執行代碼和參考材料的目錄形式存在，就像您為新團隊成員創建的入職指南一樣。

這種基於檔案系統的架構實現了漸進式披露：Claude 按需分階段載入信息，而不是預先消耗上下文。

三種 Skill 內容類型，三個載入層級

Skills 可以包含三種類型的內容，每種在不同時間載入：

第一層：元數據（始終載入）

內容類型：指令。Skill 的 YAML 前置元數據提供發現信息：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Claude 在啟動時載入此元數據並將其包含在系統提示中。這種輕量級方法意味著您可以安裝許多 Skills 而不會消耗上下文；Claude 只知道每個 Skill 的存在以及何時使用它。

第二層：指令（觸發時載入）

內容類型：指令。SKILL.md 的主體包含程序性知識：工作流程、最佳實踐和指導：

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

當您請求與 Skill 描述匹配的內容時，Claude 通過 bash 從檔案系統讀取 SKILL.md。只有在那時，此內容才會進入上下文窗口。

第三層：資源和代碼（按需載入）

內容類型：指令、代碼和資源。Skills 可以捆綁額外的材料：

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

指令：包含專業指導和工作流程的額外 markdown 文件（FORMS.md、REFERENCE.md）

代碼：Claude 通過 bash 運行的可執行腳本（fill_form.py、validate.py）；腳本提供確定性操作而不消耗上下文

資源：參考材料，如數據庫架構、API 文檔、模板或示例

Claude 僅在被引用時才訪問這些文件。檔案系統模型意味著每種內容類型都有不同的優勢：指令用於靈活指導，代碼用於可靠性，資源用於事實查詢。

漸進式披露確保在任何給定時間只有相關的 Skill 內容佔用上下文窗口。

Skills 架構

Skills 在代碼執行環境中運行，Claude 在其中具有檔案系統訪問、bash 命令和代碼執行能力。可以這樣理解：Skills 作為目錄存在於虛擬機上，Claude 使用與您在計算機上導航文件相同的 bash 命令與它們交互。

Claude 如何訪問 Skill 內容：

當 Skill 被觸發時，Claude 使用 bash 從檔案系統讀取 SKILL.md，將其指令帶入上下文窗口。如果這些指令引用了其他文件（如 FORMS.md 或數據庫架構），Claude 也會使用額外的 bash 命令讀取這些文件。當指令提到可執行腳本時，Claude 通過 bash 運行它們，只接收輸出（腳本代碼本身永遠不會進入上下文）。

此架構實現的功能：

按需文件訪問：Claude 只讀取每個特定任務所需的文件。一個 Skill 可以包含數十個參考文件，但如果您的任務只需要銷售架構，Claude 只載入那一個文件。其餘文件保留在檔案系統上，消耗零個 token。

高效腳本執行：當 Claude 運行 validate_form.py 時，腳本的代碼永遠不會載入到上下文窗口中。只有腳本的輸出（如「驗證通過」或特定錯誤消息）消耗 token。這使腳本比讓 Claude 即時生成等效代碼效率高得多。

捆綁內容無實際限制：由於文件在訪問之前不消耗上下文，Skills 可以包含全面的 API 文檔、大型數據集、大量示例或您需要的任何參考材料。未使用的捆綁內容不會有上下文損耗。

這種基於檔案系統的模型使漸進式披露得以實現。Claude 像您參考入職指南的特定部分一樣導航您的 Skill，精確訪問每個任務所需的內容。

示例：載入 PDF 處理 Skill

以下是 Claude 載入和使用 PDF 處理 Skill 的方式：

1. 啟動：系統提示包含：PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. 用戶請求：「從這個 PDF 中提取文本並總結它」
3. Claude 調用：bash: read pdf-skill/SKILL.md → 指令載入到上下文
4. Claude 確定：不需要填寫表單，因此不讀取 FORMS.md
5. Claude 執行：使用 SKILL.md 中的指令完成任務

圖表顯示：

1. 預載入系統提示和 Skill 元數據的默認狀態
2. Claude 通過 bash 讀取 SKILL.md 觸發 Skill
3. Claude 根據需要可選地讀取額外的捆綁文件，如 FORMS.md
4. Claude 繼續執行任務

這種動態載入確保只有相關的 Skill 內容佔用上下文窗口。

Skills 的適用範圍

Skills 可在 Claude 的各個代理產品中使用：

Claude API

Claude API 支持預建 Agent Skills 和自定義 Skills。兩者的工作方式完全相同：在 container 參數中指定相關的 skill_id，以及代碼執行工具。

前提條件：通過 API 使用 Skills 需要三個 beta 標頭：

• code-execution-2025-08-25 - Skills 在代碼執行容器中運行
• skills-2025-10-02 - 啟用 Skills 功能
• files-api-2025-04-14 - 上傳/下載文件到/從容器所需

通過引用預建 Agent Skills 的 skill_id（例如 pptx、xlsx）來使用它們，或通過 Skills API（/v1/skills 端點）創建和上傳您自己的。自定義 Skills 在整個組織範圍內共享。

要了解更多，請參閱使用 Skills 與 Claude API。

Claude Code

Claude Code 僅支持自定義 Skills。

自定義 Skills：將 Skills 創建為包含 SKILL.md 文件的目錄。Claude 會自動發現並使用它們。

Claude Code 中的自定義 Skills 基於檔案系統，不需要 API 上傳。

要了解更多，請參閱在 Claude Code 中使用 Skills。

Claude Agent SDK

Claude Agent SDK 通過基於檔案系統的配置支持自定義 Skills。

自定義 Skills：在 .claude/skills/ 中將 Skills 創建為包含 SKILL.md 文件的目錄。通過在 allowed_tools 配置中包含 "Skill" 來啟用 Skills。

Agent SDK 中的 Skills 在 SDK 運行時會自動被發現。

要了解更多，請參閱 SDK 中的 Agent Skills。

Claude.ai

Claude.ai 支持預建 Agent Skills 和自定義 Skills。

預建 Agent Skills：當您創建文件時，這些 Skills 已在後台工作。Claude 無需任何設置即可使用它們。

自定義 Skills：通過設置 > 功能以 zip 文件形式上傳您自己的 Skills。在啟用代碼執行的 Pro、Max、Team 和 Enterprise 計劃上可用。自定義 Skills 對每個用戶是個人的；它們不在整個組織範圍內共享，也不能由管理員集中管理。

要了解有關在 Claude.ai 中使用 Skills 的更多信息，請參閱 Claude 幫助中心中的以下資源：

• 什麼是 Skills？
• 在 Claude 中使用 Skills
• 如何創建自定義 Skills
• 使用 Skills 教導 Claude 您的工作方式

Skill 結構

每個 Skill 都需要一個帶有 YAML 前置元數據的 SKILL.md 文件：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

必填字段：name 和 description

字段要求：

name：

• 最多 64 個字符
• 只能包含小寫字母、數字和連字符
• 不能包含 XML 標籤
• 不能包含保留詞：「anthropic」、「claude」

description：

• 必須非空
• 最多 1024 個字符
• 不能包含 XML 標籤

description 應包括 Skill 的功能以及 Claude 應何時使用它。有關完整的撰寫指導，請參閱最佳實踐指南。

安全注意事項

我們強烈建議僅使用來自可信來源的 Skills：您自己創建的或從 Anthropic 獲取的。Skills 通過指令和代碼為 Claude 提供新能力，雖然這使它們功能強大，但也意味著惡意 Skill 可以指示 Claude 以不符合 Skill 聲明目的的方式調用工具或執行代碼。

主要安全注意事項：

• 徹底審計：審查 Skill 中捆綁的所有文件：SKILL.md、腳本、圖像和其他資源。尋找異常模式，如意外的網絡調用、文件訪問模式或與 Skill 聲明目的不符的操作
• 外部來源有風險：從外部 URL 獲取數據的 Skills 存在特別風險，因為獲取的內容可能包含惡意指令。即使是值得信賴的 Skills，如果其外部依賴項隨時間變化，也可能被破壞
• 工具濫用：惡意 Skills 可以以有害方式調用工具（文件操作、bash 命令、代碼執行）
• 數據暴露：可以訪問敏感數據的 Skills 可能被設計為向外部系統洩露信息
• 像安裝軟件一樣對待：只使用來自可信來源的 Skills。在將 Skills 集成到可以訪問敏感數據或關鍵操作的生產系統時要特別小心

可用 Skills

預建 Agent Skills

以下預建 Agent Skills 可立即使用：

• PowerPoint (pptx)：創建演示文稿、編輯幻燈片、分析演示文稿內容
• Excel (xlsx)：創建電子表格、分析數據、生成帶圖表的報告
• Word (docx)：創建文件、編輯內容、格式化文本
• PDF (pdf)：生成格式化的 PDF 文件和報告

這些 Skills 可在 Claude API 和 claude.ai 上使用。請參閱快速入門教程開始在 API 中使用它們。

自定義 Skills 示例

有關自定義 Skills 的完整示例，請參閱 Skills cookbook。

數據保留

Agent Skills 不在 ZDR 安排的涵蓋範圍內。Skill 定義和執行數據根據 Anthropic 的標準數據保留政策保留。

有關所有功能的 ZDR 資格，請參閱 API 和數據保留。

限制和約束

了解這些限制有助於您有效規劃 Skills 部署。

跨平台可用性

自定義 Skills 不會跨平台同步。上傳到一個平台的 Skills 不會自動在其他平台上可用：

• 上傳到 Claude.ai 的 Skills 必須單獨上傳到 API
• 通過 API 上傳的 Skills 在 Claude.ai 上不可用
• Claude Code Skills 基於檔案系統，與 Claude.ai 和 API 都是分開的

您需要為每個想要使用 Skills 的平台單獨管理和上傳 Skills。

共享範圍

Skills 根據使用位置具有不同的共享模型：

• Claude.ai：僅限個人用戶；每個團隊成員必須單獨上傳
• Claude API：工作區範圍；所有工作區成員可以訪問上傳的 Skills
• Claude Code：個人（~/.claude/skills/）或基於項目（.claude/skills/）；也可以通過 Claude Code Plugins 共享

Claude.ai 目前不支持自定義 Skills 的集中管理員管理或組織範圍分發。

運行時環境約束

您的 Skill 可用的確切運行時環境取決於您使用它的產品平台。

• Claude.ai：
  • 網絡訪問各異：根據用戶/管理員設置，Skills 可能具有完整、部分或無網絡訪問。有關更多詳細信息，請參閱創建和編輯文件支持文章。
• Claude API：
  • 無網絡訪問：Skills 無法進行外部 API 調用或訪問互聯網
  • 無運行時包安裝：只有預安裝的包可用。您無法在執行期間安裝新包。
  • 僅預配置依賴項：查看代碼執行工具文檔以獲取可用包列表
• Claude Code：
  • 完整網絡訪問：Skills 具有與用戶計算機上任何其他程序相同的網絡訪問
  • 不鼓勵全局包安裝：Skills 應僅在本地安裝包，以避免干擾用戶的計算機

規劃您的 Skills 以在這些約束條件下工作。

後續步驟