Feb 23, 2026

Claude Agent Skills 完整指南：從 Progressive Disclosure 到自定義 Skill 的全面解析

Agent Skills 是 Claude 的模組化能力擴展系統。每個 Skill 封裝了指令、metadata 和選用的資源（腳本、模板），讓 Claude 在相關任務時自動使用。不同於 prompts（一次性的對話級指令），Skills 按需載入，消除了在多次對話中重複提供相同指引的需要。本文將完整解析 Agent Skills 的架構、開發方式與最佳實踐。

一、為什麼需要 Skills

Skills 是可重用的、基於檔案系統的資源，為 Claude 提供領域專業知識。核心優勢：

專精化 Claude：為特定領域任務量身打造能力
減少重複：建立一次，自動在相關場景中使用
組合能力：結合多個 Skills 建構複雜工作流程

Anthropic 提供預建的 Agent Skills（PowerPoint、Excel、Word、PDF），開發者也可以建立自定義 Skills。

二、Skills 的運作機制

Skills 利用 Claude 的 VM 環境運作，在虛擬機器中作為目錄存在。Claude 可以透過 bash 指令與 Skills 互動，就像在電腦上瀏覽檔案一樣。

Progressive Disclosure：三層載入機制

這是 Skills 最核心的設計。Claude 分階段載入資訊，而非一次性消耗所有 context：

Level 1：Metadata（永遠載入）

Skill 的 YAML frontmatter 提供發現資訊：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

這段 metadata 在啟動時載入到 system prompt 中。輕量級的設計意味著可以安裝很多 Skills 而不會造成 context 負擔。每個 Skill 約消耗 100 tokens。

Level 2：Instructions（觸發時載入）

SKILL.md 的主體內容包含程序性知識、工作流程和最佳實踐。當使用者的請求匹配到某個 Skill 的描述時，Claude 才會透過 bash 讀取 SKILL.md。通常低於 5K tokens。

Level 3：Resources 和 Code（按需載入）

Skills 可以捆綁額外的材料：

pdf-skill/
  SKILL.md           # 主要指令
  FORMS.md           # 表單填寫指南
  REFERENCE.md       # 詳細 API 參考
  scripts/
    fill_form.py     # 工具腳本

三種內容類型各有優勢：

Instructions（.md 檔）：靈活的指引
Code（.py 腳本）：確定性操作，不消耗 context
Resources（schema、文件、模板）：事實查找

層級	載入時機	Token 消耗	內容
Level 1	啟動時	~100 tokens/Skill	YAML frontmatter 的 name 和 description
Level 2	Skill 觸發時	< 5K tokens	SKILL.md 主體的指令和指引
Level 3+	按需	實質上無限制	捆綁的檔案，透過 bash 執行不載入 context

載入範例

假設有一個 PDF 處理 Skill：

啟動：system prompt 包含 "PDF Processing - Extract text and tables from PDF files"
使用者請求："Extract the text from this PDF and summarize it"
Claude 呼叫 bash 讀取 pdf-skill/SKILL.md，指令載入 context
Claude 判斷不需要表單填寫功能，不讀取 FORMS.md
Claude 根據 SKILL.md 中的指令完成任務

三、Skill 結構

每個 Skill 需要一個包含 YAML frontmatter 的 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：

最多 64 個字元
只能包含小寫字母、數字和連字號
不能包含 XML 標籤
不能包含保留字："anthropic"、"claude"

description：

不可為空
最多 1024 個字元
不能包含 XML 標籤
應同時描述 Skill 做什麼以及 Claude 何時該使用它

四、預建 Agent Skills

目前可用的預建 Skills：

Skill	功能
PowerPoint (pptx)	建立簡報、編輯投影片、分析簡報內容
Excel (xlsx)	建立試算表、分析資料、生成帶圖表的報告
Word (docx)	建立文件、編輯內容、格式化文字
PDF (pdf)	生成格式化的 PDF 文件和報告

這些 Skills 在 Claude API 和 claude.ai 上都可用。

五、跨平台可用性

Claude API

支援預建和自定義 Skills。在 container 參數中指定 skill_id，搭配 Code Execution 工具使用。需要三個 beta headers：

code-execution-2025-08-25
skills-2025-10-02
files-api-2025-04-14

Claude Code

僅支援自定義 Skills。建立包含 SKILL.md 的目錄，Claude 自動發現和使用。基於檔案系統，不需要 API 上傳。

Claude Agent SDK

透過 .claude/skills/ 目錄中的 SKILL.md 檔案配置。在 allowed_tools 中包含 "Skill" 以啟用。

Claude.ai

支援預建和自定義 Skills。預建 Skills 在建立文件時自動運作。自定義 Skills 透過 Settings > Features 以 zip 檔案上傳。Pro、Max、Team 和 Enterprise 方案可用。

重要限制

自定義 Skills 不會跨平台同步。上傳到 Claude.ai 的 Skills 不會自動出現在 API 中，反之亦然。每個平台需要分別管理和上傳 Skills。

六、安全考量

強烈建議只使用來自可信任來源的 Skills：自己建立的或來自 Anthropic 的。

核心安全考量：

徹底審核 Skill 中所有檔案（SKILL.md、腳本、圖片等）
從外部 URL 擷取資料的 Skills 風險特別高
惡意 Skills 可能以有害方式呼叫工具
擁有敏感資料存取權的 Skills 可能洩漏資訊到外部系統
將安裝 Skills 視為安裝軟體般謹慎

執行環境限制

不同平台有不同的限制：

平台	網路存取	套件安裝
Claude.ai	依使用者/管理員設定而異	-
Claude API	無網路存取	只能使用預安裝套件
Claude Code	完整網路存取	不建議全域安裝

七、自定義 Skill 開發最佳實踐

描述撰寫

description 是 Claude 決定何時使用 Skill 的關鍵依據。應該明確描述：

Skill 做什麼
何時該使用（觸發條件）
使用者可能會如何描述需要這個 Skill 的任務

指令結構

SKILL.md 的主體應該像為新團隊成員撰寫的入職指南：

明確的步驟式指引
具體的範例
常見問題的處理方式
進階功能的參考連結（指向其他捆綁檔案）

Progressive Disclosure 最佳化

將核心工作流程放在 SKILL.md 中（Level 2）
將進階指引放在額外的 .md 檔案中（Level 3）
將確定性操作封裝為可執行腳本（Level 3）
腳本的程式碼不會進入 context，只有輸出會

總結

Agent Skills 透過 Progressive Disclosure 的三層載入機制，巧妙地解決了 context window 效率和能力擴展之間的矛盾。Level 1 的 metadata 讓 Claude 知道有哪些 Skills 可用，Level 2 的指令在需要時才載入，Level 3 的資源和腳本按需存取且不消耗 context。這種架構讓開發者能夠為 Claude 配備豐富的領域專業知識，同時保持 context window 的高效使用。無論是使用預建的文件處理 Skills 還是開發自定義的領域 Skills，理解這套架構都是發揮 Agent Skills 最大效用的關鍵。