writing-skills

概觀

writing-skills 技能的用途

writing-skills 是一個 meta-skill，專給為 Claude 等代理撰寫、精煉與測試其他技能的人使用。它把經典的 Test-Driven Development (TDD) 套用到流程說明上，讓你的技能具備：

• 以真實壓力情境為基礎
• 針對實際代理失誤進行驗證
• 經過精煉以封堵漏洞，降低代理合理化逃避的空間

你可以用 writing-skills 設計出讓代理在時間壓力、沉沒成本偏誤或誘因衝突下，仍能「找到、遵循並持續遵循」的技能。

適合使用 writing-skills 的對象

若你是下列角色，可以使用 writing-skills：

• 為 Claude 或類似代理建立技能的開發者
• 在 ~/.claude/skills 或 ~/.agents/skills/ 中標準化工作流程的團隊主管
• 需負責「一定要被代理遵守，而不只是被閱讀」的技能文件的文件負責人
• 在上線前驗證技能是否真的改變代理行為的測試人員

它不著重一般寫作風格，而是專注在撰寫有效且可測試的代理技能。

這個技能幫你解決的問題

writing-skills 是為以下情境設計：

• 代理在壓力下忽略或只部分遵守你的技能
• 你不確定新技能是否真的帶來行為上的改變
• 你需要一套可重複運用的方法，在部署前用 subagents 測試技能
• 你想遵循 Anthropic 的技能撰寫最佳實務，而不是靠猜
• 你需要用 Graphviz 視覺化並溝通複雜的技能流程

如果你現在的技能比較像一次性的故事或備忘，writing-skills 能幫你把它們重塑成可重複使用、可測試的參考指南。

writing-skills 適用與不適用的情境

適用情境：

• 需要強化紀律的技能（TDD、驗證流程、審查清單）
• 具備實際合規成本的技能（時間、返工、延後出貨）
• 代理可能會想「就這一次」繞過的技能
• 你希望能量化提升「遵循率」的技能

不適用情境：

• 純參考資訊型技能（例如 API 語法、基本語言小抄）
• 刻意不設「可違反規則」的技能
• 只需要簡單備忘、且不需要 TDD 式測試或壓力情境的輕量筆記

如果你只需要為單一對話寫一個暫時、非正式的備忘，通常不需要 writing-skills；若你希望技能能撐過實際上線時的壓力，就需要它。

使用方式

安裝與基本設定

要在支援技能的環境安裝 writing-skills：

npx skills add https://github.com/obra/superpowers --skill writing-skills

這會從 obra/superpowers repository 抓取 writing-skills 技能，並與你現有的技能一起註冊。

個人技能通常放在與代理相關的目錄，例如：

• ~/.claude/skills/：Claude Code
• ~/.agents/skills/：Codex 或類似代理

請將 writing-skills 資料夾放在對應的技能根目錄底下，讓代理在需要時可以載入 SKILL.md 與相關檔案。

writing-skills 中的重要檔案與資料夾

安裝完成後，先打開這些檔案，以了解並套用整體流程：

• SKILL.md – writing-skills 的核心技能定義與總覽，包含技能對應的 TDD 映射。
• anthropic-best-practices.md – 類似官方風格的指引，說明如何為 Claude 撰寫精簡、易發現且有效的技能。
• testing-skills-with-subagents.md – 實作指南，說明如何建立與執行壓力情境與測試 campaign。
• persuasion-principles.md – 以實證為基礎的說服模式，協助提升代理遵守技能的程度。
• graphviz-conventions.dot – 將技能流程與程序以 Graphviz 圖表呈現的慣例。
• render-graphs.js – 協助腳本，會從 SKILL.md 中擷取 ```dot 區塊並渲染為 SVG 圖檔。
• examples/CLAUDE_MD_TESTING.md – 完整範例，示範如何為不同版本的 CLAUDE.md 文件設計測試 campaign。

這些檔案組合起來，提供一套完整的技能 撰寫 + 測試 + 視覺化 工作流程。

核心流程：將 TDD 套用到技能

writing-skills 直接把 TDD 概念用在技能撰寫上。高階循環如下：

1. 撰寫測試案例（壓力情境）

   • 設計真實情況，模擬代理可能如何合理化跳過或扭曲你設計的流程。
   • 使用 subagents 執行這些情境，並記錄其行為。

2. 先跑基準測試並看它失敗

   • 在還沒載入新技能或更新後技能的情況下執行情境。
   • 收集代理失敗的地方：略過了什麼、怎麼合理化、誤解了什麼。

3. 撰寫或調整技能

   • 撰寫或更新 SKILL.md 與支援檔案，針對你觀察到的具體失敗點做修正。
   • 使用精簡、具指令性的語言，並注意 context window 限制。

4. 載入技能後再次執行測試

   • 以同樣的情境重新測試，這次載入你的技能。
   • 確認代理現在會主動發現、宣告並遵循該技能。

5. 重構以封堵漏洞

   • 找出剩餘的合理化空間或只部分遵守的情況。
   • 套用說服原則（權威、承諾等）來強化遵從度。
   • 精簡不必要的 token，保持技能內容俐落。

這個循環就是經典 TDD 裡的 RED → GREEN → REFACTOR，只是從程式碼改成用在文件與流程遵循上。

使用 anthropic-best-practices.md 強化技能品質

anthropic-best-practices.md 提供針對 Claude 生態系的指引，內容包含：

• 為何精簡的技能能提升 context 使用效率與模型效能
• Claude 何時、如何把 SKILL.md 與其他檔案載入 context window
• 如何撰寫值得其 token 成本的技能章節

你可以把這份檔案當成檢查清單來審視自己的技能：

• 移除 Claude 已知的說明
• 聚焦在可執行的模式、規則與流程
• 讓最重要的指示在技能中一開始就清楚出現

把這些實務與 writing-skills 的 TDD 循環整合，可以同時確保你的技能容易被發現且資源使用有效率。

使用 subagents 測試技能

testing-skills-with-subagents.md 把 TDD 方法延伸成具體的測試流程：

• 設計模擬實際上線壓力的情境（時間壓力、沉沒成本、速度 vs 品質）。
• 用 subagents 執行這些情境，模擬主代理的行為。
• 用結構化方式記錄失敗與合理化過程。

這對於以下類型的技能特別有用：

• 強制執行耗時的最佳實務（例如先寫測試）
• 與短期目標競爭的技能（例如「快點出貨」 vs 「確實驗證」）
• 需要在使用者明示「想走捷徑」時仍能堅守的技能

依照檔案中的測試模式，你可以在技能到達最終使用者之前，先確認它能在壓力下維持效果。

在技能設計中運用說服原則

persuasion-principles.md 摘要了也會影響 LLM 行為的心理學原則，例如：

• Authority（權威） – 對安全關鍵規則使用明確、不可協商的語句
• Commitment（承諾） – 要求代理在使用技能時先明確宣告，並遵守選定的流程
• Scarcity（稀缺） 等其他原則 – 謹慎使用，以凸顯關鍵實務的重要性

實務上你可以這樣做：

• 對「非選擇性」步驟使用更具命令性的措辭
• 要求代理在技能啟用時明講：「I am using [Skill Name] now」
• 設計強迫完成的勾選式清單，而不是只讓代理「讀過就算」

目的不是操控，而是確保關鍵實務能被穩定遵守。

使用 Graphviz 視覺化技能流程

複雜技能往往適合用圖像來表達。writing-skills 提供：

• graphviz-conventions.dot – 圖表建議結構與風格
• render-graphs.js – Node.js 腳本，會從 SKILL.md 中擷取 ```dot 區塊並轉成 SVG 檔

renderer 的基本用法：

./render-graphs.js path/to/your/skill
# or
./render-graphs.js path/to/your/skill --combine

這能幫助你：

• 向人類合作夥伴溝通技能流程
• 找出流程設計中的缺口或不必要的迴圈
• 透過在 SKILL.md 中嵌入 ```dot 程式碼區塊，讓文件與圖像保持同步

將 writing-skills 調整成符合你環境的版本

此 repository 提供的是可供調整的模式，而非要你照抄。在把 writing-skills 納入你的工作流程時可以：

• 保留 TDD 循環，但依你的工具調整情境與資料格式
• 視需要採用不同目錄結構，只要維持技能邊界清晰即可
• 把測試 campaign 串進現有的 CI、審查或發版流程

目標是打造一套可重複、以測試驅動的技能撰寫工作流程，並且能貼合你的團隊與基礎設施。

常見問題（FAQ）

什麼時候應該載入 writing-skills？

建議在以下情況使用 writing-skills：

• 建立將放在 ~/.claude/skills 或類似目錄的新技能
• 編修已經開始「走樣」或常被忽略的既有技能
• 準備把技能交給團隊成員或用於正式上線
• 設計或執行使用 subagents 的技能測試 campaign

若你只是短暫地在單一 session 中做小實驗，可能不需要完整的 writing-skills 流程。

使用 writing-skills 前一定要懂 TDD 嗎？

是的。此技能明確要求你熟悉 superpowers:test-driven-development。writing-skills 假設你已了解 RED → GREEN → REFACTOR 循環，並將其套用到文件上：

• RED：在沒有技能的情況下執行情境並記錄失敗
• GREEN：新增或調整技能，讓這些情境通過
• REFACTOR：提升清晰度、封堵漏洞並降低 token 成本

若你對 TDD 還不熟，請先載入並研讀與 TDD 相關的技能。

writing-skills 如何幫助處理 Claude 特有的行為？

writing-skills 是為 Claude 這類環境設計的，repository 中包含與 Anthropic 文檔對齊的 anthropic-best-practices.md，兩者結合可協助你：

• 撰寫 Claude 能穩定發現的技能
• 尊重 context window 與 token 預算
• 以有利於 Claude 載入與使用的方式結構化 SKILL 檔

如果你正在打造一整套 Claude 技能庫，writing-skills 會特別實用。

可以拿 writing-skills 來寫非技術或非程式類的技能嗎？

可以，只要該技能描述的是能透過情境測試的可重複流程。例如：

• 事故處理（incident response）清單
• Code review 工作流程
• 文件審查或核准流程

關鍵在於該流程必須具備：

• 明確規則，代理可以遵守或違反
• 略過步驟時會產生真實後果
• 可以透過情境測試「遵循程度」

純敘事或說故事型內容就不太適合。

examples/CLAUDE_MD_TESTING.md 是做什麼用的？

examples/CLAUDE_MD_TESTING.md 是一個完整實作範例，示範如何：

• 設計真實感情境（時間壓力、沉沒成本、權威 vs 速度）
• 對不同版本的 CLAUDE.md 文件執行這些情境
• 比較各版本在技能發現與實際使用上的效果

你可以把它當作範本，來設計自己的技能測試 campaign。

技能與故事或案例研究有什麼不同？

在 writing-skills 的模型中：

• 技能（skill） 是可重複使用的參考指南，用於編碼已驗證的模式、工具或工作流程。
• 故事或案例研究 只是描述你在某次特定情況下如何解決某個問題。

writing-skills 幫助你從一次性的故事，轉化成未來代理在新情境中也能找到並套用的通用、可測試技能。

如果我的技能很長，會有影響嗎？

會。長度會直接受限於 context window。anthropic-best-practices.md 說明了為何精簡的技能表現較好：

• 一開始只會載入 metadata，但一旦讀取 SKILL.md，每個 token 都要和對話歷史搶空間。
• 你應該持續檢查每個章節是否「值得存在」。

writing-skills 會鼓勵你：

• 刪除冗長、重複的說明
• 必要時把範例移到支援檔案
• 讓 SKILL.md 聚焦在讓測試能通過的核心流程與規則

我要怎麼判斷 writing-skills 是否真的有效？

你會在以下情況看出成效：

• 過去在壓力下常被忽略的技能，現在能被實際遵守
• 新技能不再只有文字，而是同時伴隨明確的情境與測試
• 你可以指出代理在特定情境中，套用技能前後的行為差異

如果你無法看出「有無技能」時行為的差別，就表示需要重新檢視 TDD 循環，以及 writing-skills 中提供的說服與測試指南。