Claude Skills 實作指南：用 SKILL.md 建立 Agent Skills（claude.ai、Claude Code、API）

Claude Skills 的官方名稱是 Agent Skills：一個資料夾，核心是一份 SKILL.md。檔案開頭用 YAML 寫 name 與 description，下面寫做事的步驟，資料夾裡還可以放腳本、範本和參考文件。Claude 平時只讀每個 Skill 的名稱與描述，判斷你的需求用得到時，才把完整內容載入（Agent Skills 官方文件）。它可以在 claude.ai、Claude Code 和 Claude API 使用，三個地方的建立與安裝方式各不相同；它也和「工具使用」（tool use）是兩回事，後面會分開說明。

適合做成 Skill 的，是那些你一再貼進對話的固定流程：公司的簡報格式、週報結構、程式碼審查清單、資料整理步驟。寫一次放進 Skill，之後 Claude 遇到相關需求會自動套用。

查看相關日報

易變資訊總表（截至 2026 年 10 月）

方案、介面位置與限制都可能調整，集中放在這張表。

一個 Skill 長什麼樣子

最小的 Skill 只要一個資料夾加一份 SKILL.md。內容比較多時，可以把細節拆到其他檔案，在 SKILL.md 裡指明什麼情況要讀哪一份：

weekly-report/
├── SKILL.md          必要：中繼資料＋主要指示
├── TEMPLATE.md       選用：週報範本
└── scripts/
    └── count_tasks.py  選用：Claude 用 bash 執行的腳本

SKILL.md 的開頭是 YAML 前置資料，下面接 Markdown 指示：

---
name: weekly-report
description: 依團隊格式整理每週工作週報，包含本週完成、下週計畫與風險。使用者提到週報、週會報告或每週進度整理時使用。
---

# 週報整理

1. 先讀 TEMPLATE.md，照裡面的段落順序輸出。
2. 「本週完成」每項附上負責人與完成日期。
3. 「風險」只列會影響下週交付的事項，沒有就寫「無」。
4. 使用者提供任務清單檔案時，先執行 scripts/count_tasks.py 統計數量。

欄位規則依官方文件：

• name：最多 64 字元，只能用小寫英文字母、數字與連字號，不能包含 XML 標籤，也不能包含保留字「anthropic」「claude」。
• description：不可空白，最多 1,024 字元，不能包含 XML 標籤。要同時寫「做什麼」和「什麼時候用」，因為 Claude 是拿你的需求和這段描述比對，決定要不要啟用這個 Skill。claude.ai 說明中心寫的描述上限則是 200 字元，要上傳到 claude.ai 的 Skill，描述寫在 200 字元內比較保險。

三層載入：Skill 為什麼不會塞滿對話

官方文件把 Skill 的內容分成三層，各在不同時間載入，這個設計稱為漸進式揭露（progressive disclosure）：

所以可以同時裝很多 Skill，沒被觸發的只佔名稱和描述的空間。腳本的好處也在這裡：Claude 執行 count_tasks.py 時，腳本本身不會載入對話，只有執行結果會進來，比讓 Claude 臨時寫一段同樣功能的程式更省、也更穩定。

在 claude.ai 使用

依 Claude 說明中心的使用說明與建立說明：

1. 開啟程式碼執行。 Free、Pro、Max 方案到 Settings > Capabilities，開啟「程式碼執行與檔案建立」。Team 與 Enterprise 由組織擁有者到 Organization settings > Plugins & skills 的 Policy 分頁，開啟程式碼執行與 Skills；Team 方案預設已在組織層級開啟。
2. 開啟內建 Skills。 到 Customize > Skills 開啟需要的項目。Excel、Word、PowerPoint、PDF 這幾個 Anthropic 內建 Skills 會在相關需求出現時自動使用，例如請 Claude 做一份第三季成果簡報，它就會用 PowerPoint Skill。
3. 打包自訂 Skill。 資料夾名稱和 Skill 名稱一致，整個資料夾壓成 ZIP，ZIP 打開後的第一層必須是這個資料夾，不能把檔案直接放在 ZIP 根目錄。
4. 上傳。 在 Customize > Skills 按「+」，選「+ Create skill」，再選「Upload a skill」上傳 ZIP。上傳後會出現在清單裡，可以隨時開關。
5. 測試。 換幾種說法提出應該觸發它的需求，查看 Claude 的思考過程是否有載入這個 Skill；沒有被用到，就回頭修改 description。

使用 Claude for Mac 的 Pro、Max、Team 方案，另外可以在 Cowork 裡錄下自己操作一次的畫面，讓 Claude 依錄影提出一份 Skill 草稿；這個功能不支援一般對話、Windows，以及 Free 與 Enterprise 方案。

在 Claude Code 使用

Claude Code 的 Skill 是放在電腦上的資料夾，不需要上傳（Claude Code Skills 文件）。以官方範例來說，建立一個整理未提交變更的個人 Skill：

mkdir -p ~/.claude/skills/summarize-changes

在這個資料夾放一份 SKILL.md，寫好 description 與指示。之後有兩種用法：直接問「我改了什麼？」，Claude 會依描述自動載入；或輸入 /summarize-changes 直接執行。資料夾名稱（或 frontmatter 裡的 name）就是斜線指令的名稱。

幾個實用設定：

• 放在哪裡決定誰用得到。 放在 ~/.claude/skills/ 是個人的，所有專案都能用；放在專案的 .claude/skills/ 並提交到版本庫，團隊成員都會拿到。
• 有副作用的流程不讓 Claude 自己啟動。 在 frontmatter 加上 disable-model-invocation: true，Claude 就不會自行觸發，只能由你輸入斜線指令執行，適合部署、送出訊息這類動作。反過來，user-invocable: false 會讓指令選單隱藏這個 Skill，只讓 Claude 在相關時自行參考，適合放背景知識。
• 舊的自訂指令照樣能用。 .claude/commands/ 裡的檔案已經併入 Skills 機制，原本的指令不用改。
• 跨工具的開放標準。 Claude Code 的 Skills 遵循 Agent Skills 開放標準。要上傳到 claude.ai 或 Skills API 的 Skill，frontmatter 只能使用標準欄位（name、description、license、compatibility、metadata、allowed-tools），用了 Claude Code 專屬欄位會上傳失敗。

透過 Claude API 使用

在 API 上，Skills 透過程式碼執行工具運作：在 Messages API 的 container 參數指定要用的 Skill，同時在 tools 放入程式碼執行工具（API 使用指南）。以下是用內建 PowerPoint Skill 產生簡報的 Python 寫法：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "做一份介紹再生能源的簡報"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

自訂 Skill 要先上傳到工作區。Python SDK 提供 files_from_dir，可以直接指定資料夾：

from anthropic.lib import files_from_dir

skill = client.skills.create(files=files_from_dir("weekly-report"))
print(skill.id)

拿到的 skill.id 放進 container 時，type 改成 custom。幾個要注意的地方：

• 上傳的 Skill 整個工作區共用。 同一工作區的成員都能使用。
• 產生的檔案要另外下載。 Skill 產出的 Excel、PowerPoint、PDF、Word 檔會以 file_id 回傳，要用 Files API 下載。
• 執行環境是封閉的。 沒有網路、不能在執行時安裝套件，只能用預先安裝的套件。需要呼叫外部服務的流程，要改用其他方式處理。
• 各平台分開管理。 上傳到 claude.ai 的 Skill 要另外上傳到 API，反之亦然。Claude Code 以 claude.ai 帳號登入時會單向同步帳號裡的 Skills，但在 Claude Code 資料夾裡建立的 Skill 不會反向上傳。

Skills 和工具使用（tool use）差在哪

兩者常被混在一起。依工具使用官方文件，工具使用（也稱 function calling）是讓 Claude 呼叫你定義、或 Anthropic 提供的函式：Claude 依需求和工具描述決定何時呼叫，回傳結構化的呼叫內容，再由你的應用程式（用戶端工具）或 Anthropic（伺服器工具）執行。

兩者也會一起出現：在 API 上使用 Skills，本身就要搭配程式碼執行工具。簡單說，工具給 Claude 能做的動作，Skill 告訴 Claude 某類工作該怎麼做。

安全注意事項

官方文件建議只使用可信來源的 Skill，也就是自己寫的，或來自 Anthropic 的。Skill 會透過指示和程式碼讓 Claude 做事，惡意的 Skill 可能引導 Claude 以不符合宣稱用途的方式呼叫工具或執行程式。安裝前：

• 逐一檢查所有檔案。 包括 SKILL.md、腳本、圖片與其他資源，留意不尋常的網路連線、檔案存取或和用途不符的操作。
• 小心會抓外部網址的 Skill。 抓回來的內容可能夾帶惡意指示；原本可信的 Skill，也可能因為外部來源改變而出問題。
• 不要把 API key 或密碼寫死在 Skill 裡。
• 當成安裝軟體看待。 要接上含敏感資料或關鍵作業的系統時更要謹慎。Enterprise 方案的組織可以開啟 Skill 內容掃描，上傳或修改的第三方 Skill 會先檢查再允許執行。

想寫出更容易被正確觸發的 Skill，可以參考官方的 Skill 撰寫最佳實務；在 Claude Code 裡建立 Skill 前，對 Claude Code 本身還不熟的話，可以先看 Claude Code 完整指南。

常見問題 FAQ

Claude Skills 是什麼？和提示詞有什麼不同？

Claude Skills 的官方名稱是 Agent Skills，是一個以 SKILL.md 為核心的資料夾，裡面放指示、範本、參考文件或腳本。提示詞是每次對話各自給的一次性指示；Skill 建立一次之後，Claude 平時只讀它的名稱和描述，判斷用得到才載入完整內容，不必在每段對話重貼同樣的說明。

免費方案可以用 Claude Skills 嗎？

可以。依 Claude 說明中心，claude.ai 的 Free、Pro、Max、Team、Enterprise 方案都能使用 Skills，前提是開啟「程式碼執行與檔案建立」，並在 Customize > Skills 開啟或上傳。Claude Code 可以直接在資料夾裡建立 Skill；透過 Claude API 使用則需要搭配程式碼執行工具。

Skills 和工具使用（tool use）有什麼不同？

工具使用是讓 Claude 呼叫你定義、或 Anthropic 提供的函式，Claude 回傳結構化的呼叫內容，再由你的應用程式或 Anthropic 執行。Skills 則是一包指示與資源，Claude 在程式碼執行環境裡讀取 SKILL.md、需要時執行附帶的腳本。在 API 上使用 Skills，本身就要搭配程式碼執行工具。