本文聚焦兩個問題：

• SKILL.md 應該怎麼寫，結構如何設計。
• 如何寫出高品質、可維護、可重用的 Skills。

1. SKILL.md 規範詳解

SKILL.md 是一個技能的核心描述檔。它通常由兩部分組成：

• YAML Frontmatter：定義技能中繼資訊。
• Markdown 正文：定義執行說明與實作方法。

1.1 Frontmatter 示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
# === 必填欄位 ===
name: skill-name
# 技能的唯一識別符，建議使用 kebab-case 命名

description: >
  簡潔但精確地說明：
  1) 這個技能做什麼
  2) 什麼時候應該使用它
  3) 核心價值是什麼
# 注意：description 通常是智能體選擇技能的關鍵依據，必須寫清楚

# === 可選欄位 ===
version: 1.0.0
allowed_tools: [tool1, tool2]
required_context: [context_item1]
license: MIT
author: Your Name <email@example.com>
tags: [database, analysis, sql]
---

1.2 正文建議結構

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 技能標題

## 概述
（技能介紹、適用場景、技術背景）

## 前置條件
（執行環境、依賴項、權限要求）

## 工作流程
（分步驟說明：輸入、處理、輸出）

## 最佳實踐
（經驗總結、注意事項、常見陷阱）

## 示例
（典型任務示例，便於快速上手）

## 故障排查
（常見問題與解決方案）

2. 撰寫高品質 Skills 的原則

結合官方文件與社群實踐，建議遵循以下四條原則。

2.1 Description 要精準

description 是技能匹配的關鍵入口，建議做到：

• 明確適用範圍，避免「幫助處理資料」這類泛化描述。
• 包含觸發關鍵詞，便於匹配使用者意圖。
• 說明獨特價值，與其他技能形成邊界。

不佳示例：

1

description: 處理資料庫查詢

推薦示例：

1
2
3
4

description: >
  將中文業務問題轉換為 SQL 查詢，並分析 MySQL employees 示例資料庫。
  適用於員工資訊查詢、薪資統計、部門分析、職位變動歷史等場景。
  當使用者詢問員工、薪資、部門相關資料時使用此技能。

2.2 模組化與單一職責

一個 Skill 應聚焦一個明確任務域。若一個 Skill 試圖覆蓋過多能力，通常會導致：

• Description 變寬，匹配精度下降。
• 指令變長，增加上下文負擔。
• 維護與迭代成本上升。

建議將「通用大技能」拆分為多個專用技能，例如：

• mysql-employees-analysis
• sales-data-analysis
• user-behavior-analysis

2.3 確定性優先

對於複雜且要求精確的任務，優先採用「腳本執行」，不要完全依賴 LLM 文字生成。

例如在資料匯出場景，與其讓 LLM 直接生成 Excel 二進位內容，不如使用專用腳本處理；SKILL.md 只需說明觸發條件與調用方式。

2.4 漸進式揭露

將資訊按重要性和頻率分層，避免無效上下文占用：

• SKILL.md 主體：核心工作流與常用模式
• 附加文件（如 advanced.md）：進階用法與邊緣場景
• 資料文件：大型參考資料，透過腳本按需讀取

總結

高品質 Skills 的目標不是「寫得多」，而是「邊界清晰、觸發準確、執行穩定、可持續維護」。

從規範化 SKILL.md 開始，再結合單一職責與漸進式揭露，你就能構建出更高效的技能體系。