writing-skills

writing-skills 技能概覽

writing-skills 是做什麼的

writing-skills 是一套 Skill Authoring 指南，用來以測試驅動的工作流程建立、編修與驗證 agent 技能。它的核心想法很簡單，但立場很明確：把技能撰寫當成流程文件版的 TDD。不是先把建議寫出來再期待它有效，而是先設計高壓情境、觀察在沒有技能時會怎麼失敗，然後只寫那些真的能改變行為的指引。

誰適合使用 writing-skills

最適合的讀者，是正在為 Claude Code、Codex 風格的 agent 設定，或其他本機技能目錄撰寫技能的人。特別是當你寫的技能需要強制紀律、驗證步驟，或要求 agent 在時間壓力下也不能略過某些流程時，writing-skills 會特別有幫助。

真正要解決的工作是什麼

多數使用者其實不是需要「幫我寫 markdown」，而是需要一套可重複的方法，產出 agent 真的找得到、願意遵循，而且在趕時間、過度自信或已投入太多成本時，仍會持續遵守的 SKILL.md。writing-skills 就是為了這個問題而設計的。

為什麼這個技能和一般 prompt 不一樣

一般 prompt 可以幫你起草技能；writing-skills 則提供一套方法，證明這個技能是否真的改變了行為：

• 定義高壓情境
• 在沒有技能的情況下先做 baseline 測試
• 依照實際觀察到的失敗模式撰寫文件
• 重新測試並重構，補上漏洞

因此，對 Skill Authoring 來說，它比一次性的「幫我寫個技能」指令更有價值。

重要前提與取捨

採用 writing-skills 最大的門檻，是它預設你已經理解這個 repository 的 TDD framing。這個技能明確要求你先具備 superpowers:test-driven-development 的背景。如果略過這個基礎，裡面的寫作建議可能會讓人覺得過於嚴格，或顯得過度偏向測試。

相對的取捨也很清楚：這套流程比靠直覺起草要慢，但如果失敗成本高，或 agent 很可能替自己找理由跳過技能，那這種方法會可靠得多。

如何使用 writing-skills 技能

writing-skills 的安裝情境

這個 repository 提到，個人技能會放在各 agent 專屬的目錄中，例如 Claude Code 用 ~/.claude/skills，Codex 用 ~/.agents/skills/。如果你是透過 skill manager 從 obra/superpowers repo 安裝，請確認最後技能真的落在你的 agent 會掃描的目錄裡。

如果你想在安裝前先手動評估，建議先從這些檔案開始看：

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

先讀這些檔案

如果你想最快判斷 writing-skills 是否適合自己，建議照這個順序讀：

1. SKILL.md：看主流程與定位
2. testing-skills-with-subagents.md：看怎麼把 RED/GREEN/REFACTOR 用在技能測試上
3. anthropic-best-practices.md：看精簡版的撰寫原則
4. examples/CLAUDE_MD_TESTING.md：看真實感較高的高壓情境示例
5. 如果你的技能需要對抗合理化，就看 persuasion-principles.md
6. 只有你需要圖表時，再看 graphviz-conventions.dot 和 render-graphs.js

這條閱讀路線帶來的資訊密度，會比只快速掃過 SKILL.md 前半部高得多。

writing-skills 需要你提供什麼輸入

writing-skills 在你帶著具體證據來用時效果最好，而不只是丟一個題目。好的輸入包括：

• 你想建立或修改的確切技能
• 你想改變的 agent 行為
• 沒有技能時實際發生的失敗例子
• agent 容易想跳過流程的情境
• 技能預計放置的目錄與平台

弱的輸入：
「幫我寫一個 testing skill。」

強的輸入：
「建立一個技能，強制在資料庫 migration 部署前做驗證。現在 agent 常在覺得修正很明顯時，直接略過 rollback 檢查。」

把模糊目標變成可用的 prompt

一個好用的 writing-skills usage 方式，是一次要求四個部分：

1. 高壓情境
2. baseline 失敗預期
3. 技能結構
4. 驗證計畫

範例：

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

這會比單純要求「幫我寫一份精緻的技能文件」強很多，因為它把技能必須修正的失敗模型一起提供進去了。

建議的 writing-skills 使用流程

實務上，一套好用的流程會像這樣：

1. 定義你要強制的行為
2. 寫出 2–5 個高壓情境
3. 在沒有技能時先測一次 agent
4. 記錄精確的合理化說詞與偷懶捷徑
5. 只針對這些失敗來起草 SKILL.md
6. 載入技能後重新測試
7. 在 agent 仍會滑過去的地方收緊措辭
8. 刪掉所有沒有提升遵循度的說明

最後一步很重要，因為這份 repository 內建的最佳實務特別強調 token 效率與指令精簡。

什麼時候最需要這種測試驅動方法

當技能本身有明顯的遵循成本時，就很適合用 writing-skills for Skill Authoring：

• 需要額外測試
• 驗證流程會變慢
• 需要做文件檢查
• 需要重啟或重做流程
• 規則本身和追求速度的誘因衝突

如果只是純參考型技能，例如 API 語法速查表，agent 本來就沒什麼動機去繞過內容，這種方法的重要性就低很多。

如何使用 subagent 測試參考文件

testing-skills-with-subagents.md 是很實用的搭配文件。它幫你測的不是技能「看起來對不對」，而是技能在真實壓力下能不能撐得住。當你需要以下內容時，就應該讀它：

• 情境格式
• RED/GREEN/REFACTOR 的對應方式
• 如何記錄合理化說法
• 壓力驅動下不遵循規則的例子

如果你的第一版看起來沒問題，但實際採用效果很弱，這個檔案通常是最快的改進入口。

可以參考範例情境，但不要直接照抄

examples/CLAUDE_MD_TESTING.md 有價值，是因為它展示了高壓情境實際長什麼樣：時間壓力、沉沒成本、權威壓力，以及熟悉感偏誤。常見錯誤則是把那些情境原封不動套到不相關的技能上。

更好的做法，是把壓力類型改寫成符合你自己工作流程的版本。例如：

• deployment skill → 緊急性與害怕 rollback
• review skill → 過度自信與速度偏誤
• security skill → 「就這一次」的合理化
• style skill → 採用成本低，因此測試可以較輕

persuasion 指南在流程中的角色

persuasion-principles.md 不是湊數用的；它存在的原因是，有些技能即使流程寫得很清楚，還是會失敗。如果你的技能要強制執行某些 agent 常抗拒的行為，更強的措辭有時確實有幫助。這份檔案提供的是具體模式，例如權威、承諾，以及明確宣告。

但這部分要小心使用。重點不是把技能寫得更大聲，而是讓必要動作更不容易被合理化成「可以先跳過」。

會影響輸出品質的精簡規則

這個 repository 最有價值的地方之一，就是提醒你技能會共享 context budget。writing-skills 不是叫你寫更多，而是只寫那些真的會改變行為的內容。

好的跡象：

• 具體的觸發條件
• 明確俐落的必要動作
• 直接對應真實失敗的短例子
• 最少量的背景說明

不好的跡象：

• 很長的動機型說明
• 重複定義
• 流程歷史
• Claude 本來就知道的泛泛「best practices」

可選的圖表工具

這個技能目錄包含 render-graphs.js，可以從 SKILL.md 擷取 dot 區塊，並在系統已安裝 graphviz 時渲染成 SVG 圖表。這是可選功能，主要在你的流程有分支狀態或審查關卡，且需要人類用視覺方式檢查時才特別有用。它不是使用 writing-skills skill 的必要條件，但對維護者理解與除錯流程複雜度會有幫助。

writing-skills 技能常見問題

如果我本來就會寫 prompts，還值得安裝 writing-skills 嗎？

值得，前提是你的問題在於可靠性，而不是起草速度。一般 prompt 可以很快產出一份看起來不錯的技能；writing-skills 的價值，在於它讓你更有把握：最後的技能在壓力下也真的能改變 agent 的行為。

writing-skills 對新手友善嗎？

算是部分友善。文字本身不難讀，但整個方法預設你已熟悉 TDD 式的思考。剛接觸 Skill Authoring 的使用者，通常需要先看 repository 裡和 TDD 相關的內容，不然很容易把這套流程誤認為不必要的繁文縟節。

什麼情況下 writing-skills 不適合？

以下情況可以跳過 writing-skills：

• 只是簡單的參考型技能
• 不打算重複使用的一次性筆記
• 幾乎沒有現實誘因會讓人違反指引的主題
• 無法做任何前後測試的情境

這些情況下，用更輕量的撰寫流程通常就夠了。

writing-skills 和 Anthropic 的技能最佳實務有什麼不同？

內附的 anthropic-best-practices.md 重點在於技能撰寫要精簡、容易被發現、節省 context。writing-skills 則多加了一層更強的行為改變視角：先觀察失敗，再只寫那些能修正失敗的內容。兩者是互補，不是互相取代。

writing-skills 需要額外的 repository 工具嗎？

不需要任何大型工具才能從這套方法中受益。真正關鍵的是測試指引與範例。圖表渲染只是選配，核心撰寫流程也沒有強制依賴的支援腳本。

我可以用 writing-skills 來編修既有技能嗎？

可以，而且這其實是它很好的使用場景之一。如果技能已經存在，但 agent 還是忽略它或用錯它，writing-skills 能幫你找出真正的失敗模式，刪掉沒用的內容，重寫那些最關鍵的指令。

如何改進 writing-skills 技能

從觀察到的失敗出發，不要從理想化文件出發

想讓 writing-skills 的結果更好，最快的方法就是提供失敗證據。如果你只描述理想流程，輸出通常會變得很泛。如果你提供 agent 實際走過的捷徑，最後產出的技能會更銳利、也更短。

提供更有力的高壓情境

好的情境，會真的讓人想跳過技能。建議納入：

• 時間壓力
• 來自過往經驗的自信
• 沉沒成本
• 來自人類的權威壓力
• 「這個修正很明顯」的敘事框架

這些條件最能暴露你的指令到底是太軟，還是太模糊。

記錄 agent 的原話式合理化說詞

不要只把失敗總結成「忽略了技能」。請記下 agent 實際說了什麼或暗示了什麼：

• 「這只是小改動」
• 「CI 會抓到」
• 「這種模式我早就知道」
• 「現在去讀技能太花時間」

這些合理化說詞，會直接告訴你修改後的 writing-skills usage prompt 和最終技能文案，必須正面回應哪些點。

在遵循最重要的地方收緊措辭

如果技能的目的是強制執行不可省略的行為，模糊語氣只會有害。把柔性的建議改成明確的觸發條件與必要動作。這裡 persuasion 指南確實有幫助，但真正關鍵的改善通常來自具體性：

• 何時要載入技能
• 第一步要做什麼
• 哪些不能跳過
• 怎樣才算成功

刪掉那些不會改變行為的內容

writing-skills skill 輸出常見的失敗模式之一，就是解釋過多。如果某一段沒有幫助被發現、被遵循，或提升測試品質，就刪掉它。repository 裡的最佳實務檔案之所以把這件事列為核心規則，是有原因的。

不要在第一次通過就停下來

如果技能只在容易的情境下有效，那第一個「GREEN」結果還不夠。請用更嚴苛的 prompt 和不同說法重新測試。要問的是：當 agent 很趕、很有把握，或想保住已經完成的工作時，這個技能還有沒有用。

把 writing-skills 和 repository 專屬範例搭配使用

如果你的團隊有反覆出現的工作流程，請在目標技能所屬領域中放入一個已完成的簡短範例。很多時候，這比再增加更多抽象規則更能提升採用率。重點是範例要短，而且經過高壓測試，而不是寫成百科全書。

改進 prompt 時，要求結構，不要要求潤飾

在呼叫 writing-skills 時，優先要求：

• 情境列表
• 失敗分析
• 精簡的技能大綱
• 用來封住漏洞的修改建議

不要一開始就說「幫我寫得更 polished」或「幫我寫得更完整」。這通常只會讓內容變長，卻不會提升遵循度。

先確認這個技能是否真的有必要存在

writing-skills guide 類材料的一個很有用的結果，是幫你發現某些主題其實根本不需要技能。如果流程本身很直覺、風險低，或很少重複發生，那建立技能可能只會增加維護成本，卻換不到足夠的行為收益。這樣的結論完全合理，而且有助於提升 repository 的整體品質。

把 writing-skills 用在重構，不只用在建立

writing-skills 最有價值的用法，往往是在看過既有技能失敗後，用它來做重構。這樣一來，這套方法就不再只是文件起草工具，而是變成行為工程的方法；而這也正是這個 repository 最實用的地方。