如何寫 Skill

最重要的信念：寫技能就是 TDD

Superpowers 的 writing-skills 技能有一個鐵律：沒有失敗的測試，就不准有技能。

翻譯成白話：如果你沒看過「沒有這個技能時，代理會搞砸」，你就不知道這個技能教的到底是不是對的東西。流程是——

1. RED：先寫一個壓力情境（用子代理跑測試），看代理在沒有技能時怎麼失敗、用什麼藉口合理化。
2. GREEN：寫最小技能，只針對那些具體的失敗模式。
3. REFACTOR：再跑一次，代理找到新藉口？補上去，再測，直到打不穿。

技能是什麼、不是什麼

• 是：可重用的技術、模式、工具的參考指南。
• 不是：你某次解決問題的敘事。

SKILL.md 的長相

每個技能是一個資料夾，內含 SKILL.md（必要）+ 支援檔案（需要才放）。

skills/
  skill-name/
    SKILL.md              # 主文件（必要）
    supporting-file.*     # 只有在需要時才加

frontmatter 只有兩個必填欄位：name 與 description（合計最多 1024 字元）。

description 的唯一任務：決定「何時用」

這是 Superpowers 花最多力氣講的地方。description 是未來代理「要不要讀這個技能」的判斷依據，所以：

• 以「Use when...」開頭，只描述觸發情境。
• 絕對不要在 description 裡總結技能的工作流。測試發現：description 一旦總結流程，代理就會照著 description 做，而不去讀技能正文——技能正文就變成被跳過的文件。
• 用具體的觸發詞、症狀、情境，而不是技術名詞或過程。

# ❌ 不好：總結了工作流
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ 好：只寫觸發情境
description: Use when executing implementation plans with independent tasks in the current session

針對失敗形式，選擇正確的寫法

同一段建議，對某種失敗有效、對另一種會適得其反：

堵住每個漏洞

紀律類技能（像 TDD）要能抵抗合理化。幾招：

• 明確禁止每個繞路：不只說「寫測試前先寫程式？刪掉」，要補「不要留著當參考」「不要邊寫測試邊改寫它」「刪掉就是刪掉」。
• 建立合理化藉口表：把測試時抓到的每個藉口寫成一張「藉口 → 事實」表。
• 建紅旗清單：讓代理能自我檢查「我是不是正在合理化」。

多長才算好

• 開場工作流：<150 字
• 常用技能：<200 字
• 其他技能：<500 字

重的參考資料（API docs、語法大全）拆到獨立檔案，別塞進 SKILL.md。技能的 token 成本是永久的——每個用到它的 session 都要付。

對本教學站的意義

本站每個技能頁面左欄英文、右欄繁中，逐段對照。如果你想為自己的專案寫新技能，writing-skills 的完整規則在 writing-skills 技能頁；想理解它怎麼測技能，見附屬的 testing-skills-with-subagents。