如何撰寫 Agent Skill：SKILL.md 格式完全拆解

大多數每天使用 Claude、ChatGPT 或 Cursor 的人，從未寫過一個 Agent Skill，並且理所當然地認為那需要寫程式。事實並非如此。Agent Skill 就是一個 Markdown 檔案。如果你能為新同事寫一份像樣的交接文件，你今個下午就能寫出第一個 Skill。

這件事之所以重要，是因為 Skill 解決了進階 AI 使用者最惱人的問題：每開一個新對話，就要重新貼一次設定指令。品牌語調規則、報告格式、客戶命名慣例，你一遍又一遍地貼。Skill 把這種重複變成一個檔案，讓 AI 在需要時自己載入。

什麼是 Agent Skill？

Agent Skill 是一個資料夾，裡面放着單一的 SKILL.md 檔案：開頭是 YAML frontmatter，包含名稱與描述，接着是 Markdown 正文，寫明逐步操作指示。AI 先讀描述判斷何時該用，然後才在那一刻載入正文。旁邊可以另外放腳本與參考檔案。

Anthropic 於 2025 年 10 月發佈 SKILL.md 格式，並在官方 Agent Skills 文件中詳細說明。此後這個格式已擴散到 Claude 以外的工具，意味着你寫一次，就能在多個 AI 工具間重用，不需轉換格式。

它與「儲存起來的提示詞」最實質的分別在於觸發機制。儲存的提示詞躺在文件裡，等你記得去貼。Skill 則由 AI 根據描述自行判斷，任務吻合時自動載入。

它與 Custom GPT 或 Project 的分別則在於可攜性與範圍。Project 的指令套用在裡面所有內容之上；Skill 只在它所描述的任務上生效，所以你可以安裝三十個，而每次只載入相關的那一個。

漸進式披露如何運作？為何它關係到你的上下文視窗？

漸進式披露（progressive disclosure）指的是：AI 在啟動時只看見各個 Skill 的名稱與描述，判斷相關後才載入完整的 SKILL.md 正文，需要具體細節時才打開更深層的參考檔案。這讓你安裝三十個 Skill，也不會在你打第一個字之前就把上下文視窗塞滿。

三個層級如下：

--- 第一層，發現層。任何時候都只有 YAML 的名稱與描述留在上下文中，每個 Skill 約佔 80 個 token。二十個 Skill 的常駐成本約為 1,600 個 token。

--- 第二層，啟用層。AI 判定相關後，完整 Markdown 正文才載入。正文長度通常由精簡版的約 275 個 token，到大型 Skill 的約 8,000 個 token 不等。

--- 第三層，參考層。正文所連結的檔案，例如風格指南或資料結構定義，只有在 AI 真正需要時才載入。

這正是官方撰寫指引建議 SKILL.md 正文保持在 500 行以內的原因。超過之後，你就是在為 AI 未必用得上的指令支付啟用成本。多出來的部分應拆成參考檔案。

對你撰寫時的啟示很明確：把「判斷」放進正文，把「查閱資料」放進參考檔案。一份檢查清單屬於正文；一份四十頁的品牌手冊則不屬於。

描述欄位要怎樣寫，Skill 才真的會被觸發？

描述欄位是觸發器，不是說明文件。它必須同時交代這個 Skill 做什麼、以及何時使用，長度須在 1,024 字元以內。描述寫得含糊，是 Skill 永遠不被觸發的頭號原因，因為 AI 就是拿你的請求去比對這段文字，沒有其他依據。

把它當作「比對面」來寫，而不是摘要。務必寫入你實際會打出來的具體名詞與說法。

不會觸發的弱描述：

--- description: Helps with writing tasks.

這裡完全沒有交代是哪一類寫作任務，於是它要與其他所有沾邊的寫作 Skill 競爭，通常都會落敗。

會觸發的強描述：

--- description: Draft and edit LinkedIn posts in the company voice. Use when the user asks to write a LinkedIn post, turn an article into a post, rewrite a draft for LinkedIn, or mentions "LinkedIn", "social post", "thought leadership post". Covers hook, body structure, and hashtag rules.

三個習慣造成關鍵差別。第一，指名產出物本身，寫「LinkedIn post」而不是「content」。第二，用你自己的說法列出觸發字眼，包括那些不夠工整的口語表達。第三，明確劃出邊界，讓 AI 知道這個 Skill 不負責什麼。

另有一點值得留意：描述寫得太廣，與寫得太含糊同樣糟糕。如果你寫「適用於任何內容任務」，它就會攔截自己根本處理不好的請求。

SKILL.md 正文應該寫什麼？一份可直接複製的範本

正文是 Skill 載入後 AI 要跟隨的程序。有效的正文通常包含四個部分：何時該用與何時不該用、所需輸入、編號步驟，以及品質檢查清單。要把它寫成給一位能幹新人的指示，而不是對流程的描述。

以下是一個完整的 Skill，你可以直接複製、改名，大約十五分鐘就能調整成自己的版本。

試試看：儲存為 .claude/skills/meeting-notes/SKILL.md

---
name: meeting-notes
description: Turn a raw meeting transcript or rough notes into a structured summary with decisions, owners and deadlines. Use when the user pastes a transcript, uploads meeting notes, or asks to "summarise the meeting", "write up the call", "pull the action items", or "what did we decide". Produces a fixed 4-section format.
---

# Meeting Notes

## When to use
Use when the input is a transcript, recording summary or rough notes from a real meeting.
Do NOT use for drafting an agenda before a meeting, or for one-to-one performance conversations.

## Inputs required
- The transcript or notes.
- If missing, ask once: who attended, and what was the meeting for?

## Steps
1. Read the whole input before writing anything.
2. Produce exactly four sections: Decisions, Action items, Open questions, Context.
3. Decisions: one line each, past tense, no hedging. Only what was actually agreed.
4. Action items: format as "Owner - task - deadline". If no owner was named, write "UNASSIGNED" rather than guessing.
5. Open questions: anything raised and left unresolved.
6. Context: maximum 3 sentences, for someone who missed the meeting.

## Quality checklist
- Every action item has an owner field, even if UNASSIGNED.
- No invented deadlines. If a date was not stated, write "no date set".
- Total output under 400 words.

留意這份正文沒有寫什麼：沒有解釋「會議是什麼」，沒有鋪陳式的開場白，也沒有「你是一位樂於助人的助手」。每一行不是規則，就是限制。

也請留意當中兩道防線。「寧可寫 UNASSIGNED 也不要猜」與「不得杜撰限期」之所以存在，是因為模型在資料缺口處會很有信心地自行填補。防線要寫成明確指令，而不是心存僥倖。

不寫程式的話，如何安裝與測試 Skill？

把資料夾放進 .claude/skills/ 即可套用於單一專案，放進 ~/.claude/skills/ 則全域可用。沒有編譯步驟，沒有終端機指令，沒有套件要安裝。之後就用你平時的說法提出請求，看 Skill 會不會被載入。

測試是最多人略過的一步，也正是 Skill 悄悄失效的地方。請執行以下三項檢查。

--- 觸發測試。用三種不同的自然說法提出同一個請求。如果只有其中一種觸發成功，代表你的描述欠缺你實際會用的詞彙，補上去便是。

--- 誤觸測試。提出一個相鄰但不應該由它處理的請求。以上面的會議記錄 Skill 為例，試試「幫我草擬明天會議的議程」。如果它被觸發，代表描述太廣，需要收緊「Do NOT use」那一行。

--- 輸出測試。用三份確實不同的輸入去跑，其中一份要故意雜亂。只在乾淨輸入下有效的 Skill 是示範品，不是工具。

觸發不準時，先修描述；輸出不對時，才修正文。把兩者混在一起改，正是很多人最後得到一個三百行卻依然不會觸發的 Skill 的原因。

Agent Skill 在哪些地方會失效？

Skill 的失效方式有四種，而且相當可預測：描述含糊到無法觸發、正文膨脹超過 500 行、多個 Skill 範圍重疊互相競爭，以及指令假設了 AI 並不掌握的背景。這四項都不是模型能力的限制，全部都是撰寫問題，你都可以修正。

範圍重疊是最令人意外的一項。當你有八、九個 Skill 之後，總會有兩個描述到相近的領域，而 AI 的選擇會變得不穩定。解法是在每一段描述中寫明邊界：講清楚它不涵蓋什麼，並指名由哪一個同類 Skill 處理。

Skill 不會把弱模型變強。它提供的是程序與限制，不是能力。如果底層模型連在一個寫得好的一次性提示中都無法穩定完成該任務，把它包裝成 Skill 也改變不了結果。

Skill 同樣不保證輸出完全一致。同一個 Skill 處理同一份輸入，每次的輸出不會逐字相同。如果你需要嚴格重現，例如固定的表格結構，就要在正文中明確寫出結構，並加進品質檢查清單。這能讓你接近一致，但不等於零變異。

還有一個值得養成的安全習慣：Skill 本質上是會被執行的指令文字。從公開目錄下載的 Skill，安裝前請先讀一遍，就像你會查看瀏覽器擴充功能索取的權限一樣。

立即動手：20 分鐘寫出你的第一個 Skill

回想過去一個月，你最常貼進對話的那段指令是什麼。那就是你的第一個 Skill。整個練習約需 20 分鐘，而每一次省下貼上的動作，回報都會累積。

用以下提示詞取得初稿，然後自己動手改。不要直接使用初稿，因為模型並不知道你真正的觸發詞彙。

可直接複製的提示詞：

I want to turn a repeated instruction set into an Agent Skill in SKILL.md format.

Here is what I paste into chat every time:
[PASTE YOUR USUAL INSTRUCTIONS]

Here are three ways I actually phrase the request:
1. [PHRASING 1]
2. [PHRASING 2]
3. [PHRASING 3]

Write a complete SKILL.md with:
- YAML frontmatter: name (kebab-case) and description under 1024 characters that states what it does AND when to use it, incorporating my three phrasings verbatim.
- A body under 150 lines with these sections: When to use / Do NOT use, Inputs required, Steps (numbered), Quality checklist.
- At least two explicit guardrails against the model inventing information.

Then list three adjacent requests that should NOT trigger this skill, so I can test for false positives.

儲存輸出、安裝、跑完三項測試，然後寫第二個。第二個只需十分鐘。

如果你挑中的重複任務主要是在不同應用之間搬資料，而不是處理文字，Skill 未必是合適的容器。我們對 Zapier、Make 與 n8n 的比較說明了什麼情況下無程式碼自動化平台才是更好的選擇。

核心結論

用得不錯與用得很好的分別，很少來自提示詞寫得多巧妙，而在於一件事：你那些好指令，究竟是存在 AI 找得到的檔案裡，還是留在你不斷重貼的草稿本上。

Agent Skill 用純 Markdown 就能補上這道落差。描述當作觸發器來寫，正文控制在 500 行以內，測試誤觸情況，並且誠實面對一點：Skill 提供的是程序，不是能力。

最後這一點最值得記住。工具應該減少你需要記住的事，而不是增加。懂AI，更懂你 UD相伴，AI不冷。

本文由 UD AI 團隊審閱。

把一個 Skill 變成一整套運作系統

寫出第一個 Skill 是最容易的部分。真正令人卡住的，是把整個團隊的工作跑在 Skill 之上，並接上你實際使用的工具與資料。UD 團隊手把手帶你完成每一步，由盤點哪些任務值得封裝，到配置、測試與正式部署。