AgentSkillsCN

Skill Creator

技能创作者

SKILL.md

技能建立器

語言規範：本文件使用繁體中文撰寫。

用於建立結構完善、易於維護的技能的元技能。

技能結構範本

每個技能應有以下結構：

code
skill-name/
└── SKILL.md

SKILL.md 必要區段

markdown
# 技能名稱

> **語言規範**：本文件使用**繁體中文**撰寫。

## 概述
簡述此技能的功能。

---

## 資料來源（如適用）
資料來源位置、網址、API 端點。

---

## 工作流程
AI 應遵循的逐步指示。

---

## 錯誤處理
如何優雅地處理失敗情況。

---

## 使用範例
使用者請求與預期行為的具體範例。

核心設計原則

單一職責原則

每個技能只做一件事，不要在技能中：

  • •寫與其他技能的整合邏輯
  • •預設特定使用場景去做額外處理
  • •替其他技能準備資料格式

範例：

markdown
❌ 錯誤：學校行事曆技能
- 取得行事曆 PDF
- 解析假日清單供工時技能使用  ← 不應該有這個
- 提供特殊格式給其他技能      ← 不應該有這個

✅ 正確：學校行事曆技能
- 取得行事曆 PDF
- 提供完整內容
（由呼叫方自行決定如何使用）

提供完整資料，不預設用途

技能應提供完整的原始資料，讓 AI 根據實際問題自行判斷如何使用。

markdown
❌ 錯誤：
## 輸出格式
回傳假日清單陣列：['114/12/25', '115/1/1']

✅ 正確：
## 輸出方式
載入完整 PDF 內容，由 AI 根據使用者問題從中找到相關資訊。

資料分類規則

✅ 可以寫死

類型原因範例
網址格式很少變動，若失效也容易更新https://example.com/api/v1/{resource}
API 端點結構性的，有版本控制/workhour/Hours/Create
解析模式（正規表達式）格式規則，非資料/(\d{1,2})\/(\d{1,2})\s+放假/
表單欄位 ID頁面結構document.getElementById('WorkDay')
工作流程邏輯流程，非內容「步驟 1：登入，步驟 2：導航...」
要偵測的錯誤訊息UI 字串"登入失敗"、"Session expired"

❌ 絕對不要寫死

類型原因替代做法
特定日期每年變動從來源取得
假日清單每年變動從官方行事曆解析
價格/費用隨時可能變動取得目前資料
人員姓名人員會換職位查詢目錄
版本號碼頻繁更新執行時檢查
任何「目前」的資訊會過時永遠取得即時資料
作為參考的範例輸出可能被誤用為快取資料明確標示「僅為範例」

⚠️ 謹慎使用

類型指引
預設值若確實是穩定的預設值則可，但不可用於「目前」的值
參考範例必須明確標示為說明用途，非權威資料
逾時/限制可以，但需註明可能需要調整

反面模式

1. 寫死時效性資料

markdown
❌ 錯誤：
### 114 學年度假日
- 10/10 國慶日
- 12/25 行憲紀念日

✅ 正確：
### 假日偵測
解析 PDF 尋找模式：`M/D ... 放假`

2. 偽「動態」但實際過時的範例

markdown
❌ 錯誤：
API 回傳資料如下：
{
  "holidays": ["2024/10/10", "2024/12/25"]  // AI 可能會誤用這些！
}

✅ 正確：
API 回傳資料如下：
{
  "holidays": ["...從 API 解析..."]
}

3. 缺少時效性指標

markdown
❌ 錯誤：
目前費用為 $500。

✅ 正確：
從此處取得目前費用：https://example.com/fees

4. 資料來源不明確

markdown
❌ 錯誤：
使用標準假日。

✅ 正確：
從學校行事曆 PDF 取得假日（參見資料來源區段）。

5. 跨技能耦合

markdown
❌ 錯誤：
## 與工時技能整合
當 workhour 技能需要排除假日時，回傳以下格式...

✅ 正確：
（不寫整合邏輯，讓各技能獨立運作）

6. 預設特定使用場景

markdown
❌ 錯誤：
## 輸出格式
擷取假日清單並回傳陣列。

✅ 正確：
## 輸出方式
提供完整資料，由 AI 根據問題自行判斷如何使用。

命名慣例

項目慣例範例
技能目錄小寫，連字號分隔academic-calendar
SKILL.md大寫SKILL.md
INDEX 中的觸發關鍵字中文 + 英文行事曆, academic calendar

INDEX.md 項目範本

markdown
### skill-name

| 欄位 | 值 |
|------|-----|
| 路徑 | `./skill-name/SKILL.md` |
| 說明 | 一行說明 |
| 觸發關鍵字 | keyword1, keyword2, 關鍵字1, 關鍵字2 |

**載入時機**：描述具體的觸發條件。

發佈前檢查清單

完成技能前，請確認：

設計

  • • 單一職責：只做一件事
  • • 無跨技能耦合：不寫與其他技能的整合邏輯
  • • 提供完整資料：不預設特定使用場景

內容

  • • 無寫死的日期、價格或時效性資料
  • • 所有範例標示為說明用途（非參考資料）
  • • 資料來源已明確指定網址
  • • 工作流程步驟可由 AI 執行

結構

  • • 所有必要區段都存在
  • • 已記錄錯誤處理方式
  • • 已提供使用範例
  • • 已加入語言規範標注

整合

  • • 已加入 INDEX.md 且路徑正確
  • • 觸發關鍵字涵蓋中英文

維護

  • • 無需每年手動更新的區段
  • • 解析邏輯可處理格式變化
  • • 失敗時能優雅降級

範例：建立新技能

使用者請求：「建立一個查詢學費的 skill」

流程：

  1. •

    確認單一職責

    • •這個技能只做什麼？→ 取得學費資訊
    • •不應該做什麼？→ 不替其他技能計算費用
  2. •

    識別資料來源

    • •學費資料從哪裡來？
    • •→ https://academic.nutn.edu.tw/...（動態）
  3. •

    分類資料

    • •學費金額 → ❌ 絕對不要寫死
    • •頁面網址 → ✅ 可以寫死
    • •表格解析邏輯 → ✅ 可以寫死
  4. •

    草擬 SKILL.md

    markdown
    # 學費查詢

> **語言規範**：本文件使用**繁體中文**撰寫。

## 概述
取得南大學費資訊頁面內容。

## 資料來源
學費頁面：https://academic.nutn.edu.tw/...

## 工作流程
1. 取得學費頁面
2. 載入完整內容
3. 根據使用者問題提供相關資訊

## 錯誤處理
...

## 使用範例
...
  5. •

    對照檢查清單驗證

    • •✅ 單一職責
    • •✅ 無寫死金額
    • •✅ 已指定來源網址
    • •✅ 範例不包含實際數字
  6. •

    加入 INDEX.md

更新現有技能

修改技能時：

  1. •檢查是否維持單一職責
  2. •檢查變更是否引入寫死的時效性資料
  3. •確認範例不會變成過時的參考資料
  4. •若觸發關鍵字變更，更新 INDEX.md
  5. •以全新對話測試（不記得舊版本）