如何用 Markdown 編寫 AI Agent 的 SKILL.md 與工具描述

當 AI 助手能夠遵循穩定的指令、載入特定領域的知識並安全地調用外部工具時，它們才會變得極其有用。Markdown 是編寫這些配置和指令最理想的格式，因為它既能被人類輕鬆閱讀和進行版本控制，又擁有能夠被大型語言模型精確解析的邏輯結構。

本文將詳細探討如何為 AI Agent 編寫基於 Markdown 的 SKILL.md（技能描述檔案）、Agent 系統指令檔案以及工具使用描述。我們這麼做的核心目的並不是為了把提示詞寫得更長，而是為了讓 AI Agent 能夠更加輕鬆地發現、理解並在正確的時機調用其擁有的能力。

什麼是 SKILL.md 檔案

SKILL.md 檔案是一個專門描述某項可複用能力的 Markdown 指令檔案。在 Anthropic 的 Claude Code 等 Agent 系統中，技能（Skills）作為檔案系統中的特殊產物儲存在專門的目錄裡，每一個技能都由一個對應的 SKILL.md 檔案來定義。儘管在不同的 Agent 框架中，此類檔案的具體名稱可能有所不同，但其背後的核心理念是一致的：用一個簡短、結構化的檔案，清晰地告知 Agent在什麼場景下應該使用該項能力、需要遵循什麼樣的工作流程，以及相關的輔助指令碼或參考資料儲存在哪裡。

我們可以建立一個非常簡單直白的心理模型：

• 普通提示詞（Prompt）：告訴 AI 此時此刻具體要做什麼。
• 技能（Skill）：教會 AI 以後如何重複完成某一類特定的任務。
• 工具描述（Tool Description）：告訴 AI 何時以及如何去調用某個具體的外部函數或服務介面。

由於技能主要由行為指令、執行步驟、約束條件和相關參考檔案組成，因此 Markdown 是承載這一內容最天然、最完美的格式。

為什麼 Markdown 如此適合編寫 Agent 技能

Agent 技能指令檔案需要服務於兩位讀者：大型語言模型（LLM）和人類維護者。Markdown 恰好能完美兼顧這兩者。

對於 AI 來說，Markdown 的標題和列表能把觸發條件、執行步驟、約束限制、few-shot 範例以及異常退路清晰地劃分開。對於人類開發者來說，同樣的檔案可以在 Git 中進行版本對比評審（Review），在任意編輯器中輕鬆修改，並且可以直接作為專案檔案的一部分與程式碼儲存在一起。

這一點在設計技能和工具時尤為關鍵，因為含糊不清的指令極易導致自動化工作流程出錯。例如，一個定義模糊的技能可能會在錯誤的場景下被誤觸發；一個粗糙的工具描述可能會導致模型在調用 API 時傳入錯誤的參數；而如果遺漏了安全提示，Agent 甚至可能在沒有充足證據的情況下擅自執行高危操作。

技能（Skills）與工具描述（Tool Descriptions）的區別

技能與工具密切相關，但它們的分工和維度不同：

| 要素 | 核心目的 | 典型範例 | |---|---|---| | 技能 (Skill) | 傳授一套可複用的工作流程或特定領域的標準作業程序 | "如何評審並合併一個 Pull Request" | | 工具描述 (Tool) | 告知模型某個可調用函數的作用、入參格式及返回結果 | "透過查詢語句搜尋 GitHub Issues" | | 系統提示詞 (System Prompt) | 設定助手的全域人設、語氣風格和底層行為準則 | "回答請保持簡明扼要，且必須驗證事實" | | 專案指令檔案 (Project Rules) | 闡述本地程式碼倉庫的特有規範與運行限制 | "請使用 pnpm，且在未要求前不要執行建置" |

根據 OpenAI 的 Function Calling 以及各主流 Agent SDK 的官方文件，工具（Tools）是模型或 Agent 獲取外部資料、調用第三方 API、執行程式碼或越過模型自身邊界進行互動的手段。官方指南強烈建議：工具描述應當保持簡短、精確，聚焦於「工具能幹什麼」以及「何時應該調用它」。這套準則同樣適用於 Markdown 技能：務必對激活場景和核心用途做到極其具體和明確。

一個實用的 SKILL.md 範本結構

一個真正實用的技能描述檔案應該清晰回答以下六個問題：

1. 這個技能能提供什麼能力？
2. Agent 在什麼情況下應當激活該技能？
3. 在什麼情況下絕對不應該使用該技能？
4. Agent 執行該技能時需要遵循哪些具體步驟？
5. 有哪些現成的本地檔案、指令碼或參考資料可供配合使用？
6. 最終輸出內容應該是什麼格式？

以下是一個可以直接套用的標準範本：

---
name: markdown-conversion-review
description: 當使用者需要審查、優化或清理從 PDF、Office 格式或網頁轉換而來的 Markdown 檔案時，請使用該技能。
---

# 技能名稱：Markdown 轉換品質評審

## 激活場景 (Use This Skill When)
- 使用者要求對轉換後的 Markdown 進行清理或潤色。
- 使用者需要將某份檔案轉換為適合 README、官方文件、部落格或 AI 提示詞使用的格式。
- 源文字中包含排版殘缺的表格、混亂的標題層級、丟失的連結或閉合錯誤的程式碼區塊。

## 排除場景 (Do Not Use This Skill When)
- 使用者只是在詢問 Markdown 語法的概念或基礎教學。
- 任務需要修改當前處理檔案之外的其他不相關源檔案。

## 標準執行工作流程 (Workflow)
1. **第一步：結構審查**。檢查轉換後的 Markdown 是否存在層級混亂、表格變形、連結失效和程式碼區塊閉合錯誤等問題。
2. **第二步：意圖保護**。在清理過程中必須嚴格保留作者的原始邏輯和表達順序，除非使用者明確要求你進行重寫。
3. **第三步：規範化排版**。使用簡潔、標準的 Markdown 語法規範標題、列表、超連結和表格的格式。
4. **第四步：局限性標註**。如果發現某些源檔案的排版格式實在無法可靠還原，必須在檔案末尾予以標註。
5. **第五步：輸出成果**。向使用者返回清理規範後的 Markdown 正文以及簡短的修改備註。

## 品質要求與約束 (Quality Bar)
- 嚴禁捏造源檔案中不存在的資訊。
- 除非使用者特別要求，否則必須完整保留原始程式碼區塊的內容。
- 優先選用簡潔的純 Markdown 語法，儘量避免嵌套複雜的 HTML 標籤。

## 期望輸出格式 (Output Format)
按以下順序返回：
1. 規範清理後的 Markdown 文本。
2. 修改備註與轉換決策說明。
3. 遺留或無法解決的排版問題清單。

上面的 Frontmatter（前置元資料）欄位可以根據你使用的具體 Agent 系統（例如 Claude Code 的 skills 規範）進行調整。檔案主體的邏輯框架（觸發條件、排除場景、執行工作流程、品質邊界、輸出格式）則是完全通用的。

如何撰寫高品質的描述（Description）欄位

在技能或工具的定義中，description 描述欄位往往是最核心的要素，因為 Agent 通常正是基於該欄位來進行語意路由，從而決定是否載入某項能力。

糟糕的描述寫法：

description: 幫助處理 Markdown。

優秀的描述寫法：

description: 當使用者需要對轉換後的 Markdown 檔案進行清理、排版規範化，或者將其整理用於技術文件、專案 README、部落格文章及 AI 提示詞上下文時，請調用該技能。

一個合格的描述應該包含：

• 觸發時機：「當使用者需要……時」
• 核心操作：「清理、排版規範化，或者將其整理用於……」
• 處理對象：「轉換後的 Markdown 檔案」
• 適用場景：「技術文件、專案 README、部落格文章及 AI 提示詞上下文」

如何編寫工具使用描述（Tool Descriptions）

相比於技能檔案，工具（Tool）的描述應該更加短小精悍。工具是一種具體的 API 操作，因此大型語言模型只需要三個極其明確的答案：

• 該工具具體做什麼？
• 什麼時候該用它（以及什麼時候不該用）？
• 它需要什麼樣格式的輸入參數？

JSON 格式的工具定義範例：

{
  "name": "convert_file_to_markdown",
  "description": "當使用者上傳了 PDF、DOCX、PPTX、XLSX、HTML 或圖片檔案，並希望將其轉換為可編輯的文本或適合 AI 讀取的結構化內容時，使用該工具將其轉換為 Markdown 格式。",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "已上傳檔案的唯一標識 ID。"
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "是否嘗試將檔案中的表格提取並轉換為 Markdown 格式的表格，預設為 true。"
      }
    },
    "required": ["file_id"]
  }
}

上面的描述沒有假大空的修飾詞，而是直奔主題地寫清了支援的檔案類型、觸發意圖和參數細節。這樣可以顯著降低 AI 的誤用率，並提升傳參的準確度。

技能文件化：用 Markdown 記錄工具手冊

如果你的專案中有許多在程式碼中定義的 API 工具，用 Markdown 為它們編寫一份面向 AI 的「使用手冊」是一個非常聰明的做法：

# 工具參考手冊：convert_file_to_markdown

## 核心功能
將支援的檔案轉換為 Markdown 格式。

## 推薦調用場景
- 使用者上傳了檔案，並直接要求轉換為 Markdown。
- 使用者希望對某份檔案的內容進行 LLM 分析、生成 README、編寫官方文件或部落格。

## 禁用場景
- 使用者僅僅是在諮詢關於 Markdown 的概念性問題。
- 輸入資料已經是乾淨的 Markdown，不需要做任何二次轉換。

## 入參說明
| 參數名 | 類型 | 是否必填 | 備註與說明 |
|---|---|---:|---|
| file_id | string | 是 | 上傳檔案的唯一識別碼 |
| preserve_tables | boolean | 否 | 是否儘可能保留表格結構 |

## 期望輸出
轉換後的 Markdown 純文字以及轉換備註。

## 異常與失敗處理
- 如果傳入了不支援的檔案類型，向使用者友善地提示所支援的格式列表。
- 如果無法還原原始佈局，返回最佳的文字提取結果，並如實註明格式局限性。

這種做法在工具定義寫在程式碼裡，但 Agent 需要額外的「操作指南」來避免犯錯時非常管用。

什麼樣的技能才是真正高效的

一個寫得好的技能應該是極具實操性的，能夠切實幫助 Agent 在複雜的執行過程中做出正確的決策。

1. 觸發界限極其清晰

不要使用寬泛、抽象的標題，明確告知觸發的时機。

糟糕的觸發定義：

# SEO 技能

優秀的觸發定義：

## 激活場景
- 使用者要求優化某個頁面以提升其在搜尋引擎中的表現。
- 內容需要補充 Meta 標題、Meta 描述、清晰的 H2/H3 標題、內部連結或常見問題解答（FAQ）。
- 使用者提到了 E-E-A-T 原則、搜尋引擎有用內容（Helpful Content）評估或低品質內容整改。

2. 明確劃定非目標（Non-Goals）

明確寫出「不該做什麼」往往和「該做什麼」一樣重要，這能有效防止 Agent 越界或濫用能力。

## 禁用場景
- 使用者在諮詢法律、醫療或財務等需要專業執照的建議。
- 任務要求虛構使用者好評、捏造統計數據、偽造參考文獻或使用者留存資料。
- 目標頁面與我們的產品線或使用者實際意圖毫無關明。

3. 提供可落地的步驟

技能中應該包含在複雜或高壓環境下也清晰可執行的工作流程。步驟應當具體到能指導行為，但又不至於細碎到容易讓 Agent 失去彈性。

4. 提供「好」與「壞」的具體樣例

在與 AI 溝通時，具體的範例（Example）往往勝過一萬個形容詞。

## 文案風格範例

- **避免使用（糟糕的寫法）**：
  “我們革命性的轉換器保證能完美無瑕地轉換任何類型的檔案。”
  *(原因：措辭誇張虛浮，容易引起不信任感。)*

- **推薦使用（優秀的寫法）**：
  “該轉換器能夠將檔案內容提取為 Markdown 格式。當源檔案擁有清晰的標題、規則的表格和純文字內容時，轉換效果最佳。”
  *(原因：實事求是，同時指明了價值和局限性。)*

5. 明確安全與權限的邊界

如果你的技能涉及運行本地指令碼、調用 API 或修改敏感檔案，務必確立安全邊界：

## 安全邊界與權限
- 在對任何檔案進行編輯寫入前，必須先完整讀取其內容。
- 絕不主動刪除使用者的本地檔案，除非收到了非常明確的刪除指令。
- 在向外部不受信任的 API 發送資料前，必須徵得使用者的確認。

常見設計誤區

• 誤區 1：把一個技能塞得太滿：一個技能應當只聚焦於一件連貫的事。如果把 SEO 優化、流量分析、文案撰寫、廣告政策審核和郵件分發都塞進一個“行銷技能”裡，Agent 很容易在理解上發生混亂。
• 誤區 2：使用假大空的修飾詞：避免在指令中寫“請寫出世界一流的程式碼”或“讓文案看起來驚艷”。AI 根本無法量化這些形容詞。使用可觀測的指標代替，例如“確保包含來源超連結”、“列出核心假設”、“字數少於 150 字”。
• 誤區 3：把關鍵規則藏在長篇大論中：如果一條規則至關重要，請用無序列表（Bullet points）單獨列出。AI 和人類一樣，對於列表的關注度遠遠高於冗長段落中間的句子。
• 誤區 4：缺失異常與失敗處理：工具有時會超時，輸入有時會殘缺，檔案有時會損壞。確保在技能中包含一項“如果失敗了，下一步該怎麼辦”的指示。

總結

基於 Markdown 的 SKILL.md 和工具描述，是教導 AI Agent 掌握專業技能、同時避免其偏離軌道的最佳方案。最優秀的描述檔案往往簡短、聚焦且完全以執行為導向。

如果你正在圍繞檔案轉換、知識庫建置或自動化工具開發 AI 工作流程，編寫規範的 SKILL.md 將是連接人類流程經驗與 AI 穩定執行之間最穩固的橋梁。

參考資料與延伸閱讀

• Claude 官方文件：Agent Skills 技能設計
• Claude Code 開發指南：Agent SDK 中的 Skills
• OpenAI API：Function Calling 函數調用指南
• OpenAI Agents SDK：工具設計規範