故事

王小明包第一支 Skill：產生測試案例。

流程七八個步驟、硬規則寫得清楚、範例也附了完整的輸入輸出。

寫完在群組裡說了一聲：「以後要列 case 的時候 AI 會自動照這個格式跑，大家直接問就好。」

然後接下來幾天，開始 Review Test Case 的時候，列出來的測試案例格式還是完全不一樣。

王小明才回頭去查。

查到的原因很簡單：他的 description 寫得太漂亮了？

description 是唯一的入口

因為 AI 不會一次性把所有的 Skill 都讀進來

它看到的是一份清單，清單上每一支 Skill 只有名稱跟 description。

然後它根據你這次講的話語意，決定「要不要把某一支的完整內容載進來」。

也就是說：

description 是檢索條件。

王小明寫的是這種：

description: 提供結構化的測試案例產出協助，確保案例覆蓋率與一致性

看起來很專業，問題是：這句話都在講「我有多完整」，沒講「什麼時候該找我」。

AI 讀完知道它跟測試案例有關，但不知道該在哪個當下把它叫出來。

所以 Skill 「沒被叫到」，本質上就跟不存在是一樣的。

description 該怎麼寫？

只要回答兩件事：

description: |
  <做什麼：這支 skill 的交付物是什麼>
  <什麼時候用：使用者在什麼情況下、想達成什麼>

把王小明那支拿來改，會長這樣：

description: |
  依據需求說明或畫面，產出符合團隊格式的測試案例，
  含正常情境、邊界條件與異常流程。
  當使用者拿到一個新功能、需要知道要測哪些東西，
  或想把既有功能的測試案例補齊時使用。

前者只說明「自己是什麼」，後者說明「使用者處在什麼狀況」。

兩個格式上的細節

1. 多行要用 |，不要用 >

   • YAML 裡 | 會保留換行，> 會把換行全部摺成空格。
   • 分好的句子被摺成一整段，可讀性會直接掉下去。

2. 最重要的用途放最前面

   • 段文字在 skill 清單裡有長度上限，超過會被截掉。
   • 所以寫太長不只是浪費，是後面那段可能根本沒被讀到。

範本：完整的 SKILL.md

五題篩過覺得值得包，就用這份當起手式：

---
name: <kebab-case-名稱>
description: |
  <做什麼：交付物是什麼>
  <什麼時候用：使用者在什麼情況下、想達成什麼>
---

# <標題>

<一句話：這支 skill 的交付物是什麼。寫得越具體越好>

## 硬規則

- <不可違反的事>
- <涉及風險的邊界>
- <一定要留下的證據 / 紀錄>

## 流程

1. **<步驟名>** — <做什麼，怎樣算完成>
2. **<步驟名>** — <同上>
3. **<步驟名>** — <同上>

> 需要人拍板的步驟，在這裡明確標示「停下來問使用者」。

## 驗收標準

- <怎樣算做完，要能被檢查>

## 範例

**輸入**：<實際會拿到的東西>

**輸出**：<期望長成的樣子，直接貼>

延伸：當 SKILL 太長時，你就需要搭配 references/ 方式收斂部分細節資訊，這部分後續文章會再說明

曾經我的誤解區

我曾以為 description 要聚焦的使用的「說法」，也就是要匹配「關鍵字」之類的 AI 才會找得到

ex. description: 幫我列 TC、生產測試案例

但這個理解並不完全正確，因為真的靠的還是「情境」語意理解度

所以如果你列不出多種真實會出現的講法，那通常代表：你其實還沒想清楚這支 skill 什麼時候該被用。

總結

所以「情境」這兩個字可不是隨便說說的！

上一篇提到，團隊一大，一句話就不夠用了，要準備情境和範例，同仁們才能接得住。

那時候的讀者是同事，現在換成 AI，但本質上思路是完全沒變！

所以真的推薦大家要多練習寫文件，畢竟文件要寫得好可不是一件容易的事情XD

像參加 it鐵人賽也是對寫文件能力可以大大的提升！

到這裡，Skill 已經能穩定地在對的時候被叫出來，也能照著我們的標準做事。

它變得很能幹。 而這正是我開始緊張的地方。

因為 AI 很能幹、又會自己動手解決，但是萬一哪一步判斷錯了、失控了，我該怎麼辦？

明天會講我給 AI 的幾個明確的防守界線規則區分