掌握 Agent Skills：教你真正“學會”寫 Skill
整理版優先睇
Agent Skills 係將「點樣做嘢」變成結構化、可複用嘅技能，關鍵係寫好 SKILL.md
呢篇文章係講 Agent Skills 呢個概念，作者想解決嘅問題係點樣令 AI Agent 掌握可複用嘅能力，而唔係靠每次寫 Prompt。整體結論係：Skill 係一個文件夾加一個 SKILL.md，重點係寫清楚 description 同執行步驟。
作者由 Agent Skill 嘅定義開始：一個文件夾加一個畀 AI 睇嘅說明文檔。Skill 唔係教 AI「學」技能，而係喺合適嘅時候畀 AI 發現、加載，然後按說明執行。佢強調呢個係「文檔優先」嘅設計，代碼只係輔助。
跟住作者詳細解釋咗 SKILL.md 嘅結構：YAML 前置元數據同 Markdown 正文。description 係重中之重，因為 AI 係靠佢判斷用唔用呢個技能。正文就係一步一步嘅執行步驟，要寫得清晰、唔好有廢話。最後作者總結咗 Skill 嘅深層意義：Prompt 唔再係最終產物，AI 開始繼承經驗，文檔等於能力。
- Skill 核心係一個文件夾加 SKILL.md，SKILL.md 係畀 AI 睇嘅操作說明書。
- description 係 AI 匹配技能嘅關鍵，寫得唔好技能等於唔存在。
- Skill 係漸進式加載，AI 啟動時只睇 name 同 description。
- 寫 Skill 嘅心法係當成「你唔在場時AI應該點做」，問清三個問題。
- Skill 改變咗三件事：Prompt 唔再係最終產物、AI 開始繼承經驗、文檔等於能力。
內容結構
my-skill/├──
SKILL.md # 必須：技能說明 + 元信息├── scripts/ # 可選：腳本、可執行邏輯├── references/ # 可選：參考資料└── assets/ # 可選：模板、資源文件咩係 Agent Skill？點解咁重要？
Agent Skill 係一種 簡單、可複用、開放 嘅格式，用嚟畀 AI Agent 注入新能力。佢嘅核心目標得一個：將「點樣做嘢」從 Prompt 入面，變成 結構化、可複用、可加載 嘅技能。一句講曬：Agent Skill = 一個文件夾 + 一個寫畀 AI 睇嘅說明文檔。
Skill 嘅基本結構同 SKILL.md 係靈魂
一個 Skill 最基本嘅結構得一個 SKILL.md 檔案，放喺一個文件夾入面。完整嘅結構仲可以包含 scripts、references 同 assets 呢啲可選目錄。關鍵係：Skill 係「文檔優先」，代碼只係輔助。
SKILL.md 係 Skill 嘅靈魂，由兩部分組成：YAML 前置元數據 同 Markdown 正文。YAML 入面嘅 description 極其重要，因為 AI 係靠佢嚟判斷「呢個技能啱唔啱用」，如果寫得唔好，技能就等於唔存在。
正文係畀模型執行嘅指令，應該包含：何時使用、使用目標、執行步驟、注意事項。例如一個 PDF 處理 Skill 嘅正文會講：「當用戶上傳或提及 PDF 文件時使用」，然後一步步說明點樣提取文本、合併 PDF。
點樣用好 Skill？心法同常見陷阱
Skill 嘅使用係 漸進式加載：啟動時 AI 只睇 name 同 description 嚟決定用唔用；命中之後先完整讀取 SKILL.md；執行中如果提到腳本或資源先再加載對應文件。呢個機制令到 description 係技能嘅觸發器。
加入腳本可以令 Skill 有真正執行能力，例如喺 scripts/ 放 extract.py，然後喺 SKILL.md 引用佢。咁樣 Skill 就變成「可讀說明 + 可執行能力」。
Skill 嘅深層意義：改變 Prompt 時代
- 1 Prompt 唔再係最終產物，而係會沉澱成可複用嘅技能
- 2 AI 開始繼承經驗，你寫嘅係流程而唔係一次性對話
- 3 文檔 ≈ 能力，文檔寫得越好，AI 能力越穩定。
🚀 掌握 Agent Skills：教你真正「學識」寫 Skill
Agent Skills 係一種簡單、可以重用、開放嘅格式，用嚟俾 AI Agent 加入新嘅能力或者專業知識。
佢嘅核心目標得一個：
將「點樣做嘢」由 Prompt 裏面，變成結構化、可以重用、可以載入嘅技能。
如果你明白咗 Skill，你就會發現：
呢個係喺度幫 AI 寫「外掛說明書」。
🧠 咩係 Agent Skill？
一句講曬：
Agent Skill = 一個資料夾 + 一份寫俾 AI 睇嘅說明文件
AI 唔係「學識」技能，而係：
喺啱嘅時候 發現它 喺需要嘅時候 加載它 按照你寫嘅指示 一步一步執行
📁 一個 Skill 嘅基本結構
最簡單可用嘅結構得一個檔案：
my-skill/
└── SKILL.md
完整結構通常係：
my-skill/
├── SKILL.md # 必須：技能說明 + 元信息
├── scripts/ # 可選：腳本、可執行邏輯
├── references/ # 可選：參考資料
└── assets/ # 可選：模板、資源文件
重點：
Skill 係「文件優先」嘅 程式碼係輔助，唔係核心
📘 SKILL.md：呢個係 Skill 嘅靈魂
SKILL.md 是一個 俾 AI 睇嘅操作說明書。
佢由兩部分組成：
YAML 前置元數據（等 AI 識別） Markdown 正文（等 AI 知道點做）
1️⃣ YAML 前置元數據（必須）
---
name: pdf-processing
description: 提取 PDF 文本、處理表格、合併文檔。適用於 PDF 相關任務。
---
欄位說明：
name技能唯一標識 細楷字母 + -類似命令名，唔係標題 description- 極之重要
AI 會唔會揀呢個 Skill，主要靠佢 寫清楚「幾時要用佢」
👉 當佢係：AI 嘅技能匹配觸發器
2️⃣ Markdown 正文（真正嘅「技能」）
正文唔係俾人睇，係俾 模型執行嘅指令。
一個好嘅正文通常包含：
# 技能名稱（可選）
## 何時使用
說明在什麼用戶意圖下使用這個技能。
## 使用目標
明確最終要達成的結果。
## 執行步驟
一步一步說明要做什麼。
## 注意事項
容易出錯的點、約束條件。
🧩 Skill 係點樣俾 AI 用嘅？
Skill 唔係一開始就全部載入。
它是 漸進式載入 的：
啓動時
AI 淨係睇到： name + description用嚟判斷「我應唔應該用呢個技能？」 命中後
先至完整讀取 SKILL.md執行中
如果正文入面提到腳本、資源 先會繼續載入對應嘅檔案
👉 即係話：
description 寫得唔好，Skill 等於唔存在。
🛠 一個完整嘅 Skill 示例（核心示範）
目標：PDF 處理 Skill
目錄結構：
skills/pdf-processing/
└── SKILL.md
SKILL.md 示例
---
name: pdf-processing
description: 當用戶需要讀取、提取、合併或分析 PDF 文件時使用。
---
# PDF 處理技能
## 何時使用
當用戶上傳或提及 PDF 文件，並希望獲取其中的內容、結構或進行合併操作時。
## 提取文本
1. 打開 PDF 文件
2. 按頁提取全部文字
3. 清理多餘空行
4. 按順序輸出結果
## 合併 PDF
1. 按用戶給定順序排列文件
2. 合併為單一 PDF
3. 確認頁碼連續無缺失
## 注意事項
- 保留原始文件順序
- 不修改原文件內容
呢個就係一個完整、可以工作嘅 Skill。
冇程式碼，都完全成立。
🧪 加入腳本（可選，但好強大）
如果你需要真正「執行」操作，可以加腳本：
skills/pdf-processing/
├── SKILL.md
└── scripts/
└── extract.py
在 SKILL.md 入面引用佢：
## 提取文本
使用 scripts/extract.py 提取 PDF 中的所有文字，並返回純文本結果。
咁樣 Skill 就變成咗：
「可讀說明 + 可執行能力」
🧠 寫 Skill 嘅真正心法（非常重要）
❌ 錯誤思路
將 Skill 當 README 寫背景、願景、介紹 寫俾「人」睇
✅ 正確思路
將 Skill 當成：
你唔喺度嘅時候，AI 應該點樣做嘢
問自己三個問題：
- 幾時應該用呢個 Skill？
- 目標結果係咩？
- 一步一步應該點做？
📍 Skill 放喺邊？
常見約定路徑：
.claude/skills/
.github/skills/
skills/
每個 Skill 一個資料夾，彼此完全獨立。
🌱 點解 Skill 咁重要？
因為佢改變咗三樣嘢：
1️⃣ Prompt 唔再係最終產物
Prompt 會消失，Skill 會沉澱落嚟。
2️⃣ AI 開始「繼承經驗」
你寫嘅係流程，唔係一次性對話。
3️⃣ 文檔 ≈ 能力
文檔寫得越好，AI 能力越穩定。
🧠 終極總結
一個好 Skill =
清晰的 description明確嘅使用場景 可以執行嘅步驟說明 最少嘅廢話 可選嘅腳本支援
Skill 係新時代嘅「函數定義」，
而 SKILL.md 係寫俾模型睇嘅接口說明。
🚀 掌握 Agent Skills：教你真正“學會”寫 Skill
Agent Skills 是一種簡單、可複用、開放的格式，用於給 AI Agent 注入新的能力或專業知識。
它的核心目標只有一個：
把“怎麼做事”從 Prompt 裏，變成結構化、可複用、可加載的技能。
如果你理解了 Skill，你就會意識到：
這是在給 AI 寫“外掛說明書”。
🧠 什麼是 Agent Skill？
一句話版本：
Agent Skill = 一個文件夾 + 一個寫給 AI 看的說明文檔
AI 不是“學會”技能，而是：
在合適的時候 發現它 在需要的時候 加載它 按你寫的說明 一步步執行
📁 一個 Skill 的基本結構
最小可用結構只有一個文件：
my-skill/
└── SKILL.md
完整結構通常是：
my-skill/
├── SKILL.md # 必須：技能說明 + 元信息
├── scripts/ # 可選：腳本、可執行邏輯
├── references/ # 可選：參考資料
└── assets/ # 可選：模板、資源文件
關鍵點：
Skill 是“文檔優先”的 代碼是輔助，不是核心
📘 SKILL.md：這是 Skill 的靈魂
SKILL.md 是一個 給 AI 看的操作說明書。
它由兩部分組成：
YAML 前置元數據（讓 AI 識別） Markdown 正文（讓 AI 知道怎麼做）
1️⃣ YAML 前置元數據（必須）
---
name: pdf-processing
description: 提取 PDF 文本、處理表格、合併文檔。適用於 PDF 相關任務。
---
字段說明：
name技能唯一標識 小寫字母 + -類似命令名，而不是標題 description- 極其重要
AI 是否選擇這個 Skill，主要靠它 寫清楚「什麼時候該用它」
👉 把它當成：AI 的技能匹配觸發器
2️⃣ Markdown 正文（真正的“技能”）
正文不是給人看的，是給 模型執行的指令。
一個好的正文通常包含：
# 技能名稱（可選）
## 何時使用
說明在什麼用戶意圖下使用這個技能。
## 使用目標
明確最終要達成的結果。
## 執行步驟
一步一步說明要做什麼。
## 注意事項
容易出錯的點、約束條件。
🧩 Skill 是如何被 AI 使用的？
Skill 並不是一開始就全部加載。
它是 漸進式加載 的：
啓動時
AI 只看到： name + description用來判斷“我該不該用這個技能？” 命中後
才完整讀取 SKILL.md執行中
如果正文裏提到腳本、資源 才會繼續加載對應文件
👉 這意味着：
description 寫不好，Skill 等於不存在。
🛠 一個完整的 Skill 示例（核心示範）
目標：PDF 處理 Skill
目錄結構：
skills/pdf-processing/
└── SKILL.md
SKILL.md 示例
---
name: pdf-processing
description: 當用戶需要讀取、提取、合併或分析 PDF 文件時使用。
---
# PDF 處理技能
## 何時使用
當用戶上傳或提及 PDF 文件，並希望獲取其中的內容、結構或進行合併操作時。
## 提取文本
1. 打開 PDF 文件
2. 按頁提取全部文字
3. 清理多餘空行
4. 按順序輸出結果
## 合併 PDF
1. 按用戶給定順序排列文件
2. 合併為單一 PDF
3. 確認頁碼連續無缺失
## 注意事項
- 保留原始文件順序
- 不修改原文件內容
這就是一個完整、可工作的 Skill。
沒有代碼，也完全成立。
🧪 加入腳本（可選，但很強）
如果你需要真正“執行”操作，可以加腳本：
skills/pdf-processing/
├── SKILL.md
└── scripts/
└── extract.py
在 SKILL.md 中引用它：
## 提取文本
使用 scripts/extract.py 提取 PDF 中的所有文字，並返回純文本結果。
此時 Skill 變成了：
“可讀說明 + 可執行能力”
🧠 寫 Skill 的真正心法（非常重要）
❌ 錯誤思路
把 Skill 當 README 寫背景、願景、介紹 寫給“人”看
✅ 正確思路
把 Skill 當成：
你不在場時，AI 該怎麼做事
問自己三個問題：
- 什麼時候該用這個 Skill？
- 目標結果是什麼？
- 一步一步該怎麼做？
📍 Skill 放在哪裏？
常見約定路徑：
.claude/skills/
.github/skills/
skills/
每個 Skill 一個文件夾，彼此完全獨立。
🌱 為什麼 Skill 非常重要？
因為它改變了三件事：
1️⃣ Prompt 不再是最終產物
Prompt 會消失，Skill 會沉澱。
2️⃣ AI 開始“繼承經驗”
你寫的是流程，不是一次性對話。
3️⃣ 文檔 ≈ 能力
文檔寫得越好，AI 能力越穩定。
🧠 終極總結
一個好 Skill =
清晰的 description明確的使用場景 可執行的步驟說明 最少的廢話 可選的腳本支持
Skill 是新時代的“函數定義”，
而 SKILL.md 是寫給模型看的接口說明。