撰寫技能
概述
撰寫技能是將測試驅動開發應用於流程文件。
個人技能存放在執行環境的技能目錄中（Claude Code 上為 ~/.claude/skills/）——請參閱 codex-tools.md 或 gemini-tools.md 以了解其他執行環境的路徑。Codex、Copilot CLI 和 Gemini CLI 也都能辨識 ~/.agents/skills/ 作為跨執行環境的別名。
你撰寫測試案例（包含子代理的壓力情境），觀察它們失敗（基準行為），撰寫技能（文件），觀察測試通過（代理遵守），然後重構（堵住漏洞）。
核心原則： 如果你沒有看過代理因缺乏技能而失敗，你就無法確定該技能是否教導了正確的行為。
必要背景： 在使用此技能之前，你必須理解 superpowers:test-driven-development。該技能定義了基本的 RED-GREEN-REFACTOR 循環。此技能則是將 TDD 應用於文件撰寫。
官方指南： 關於 Anthropic 官方技能撰寫的最佳實踐，請參閱 anthropic-best-practices.md。本文檔提供了補充的模式與指引，與此技能中著重 TDD 的方法相輔相成。
什麼是技能？
技能是針對已驗證的技術、模式或工具的參考指南。技能幫助未來的代理找到並應用有效的方法。
技能是： 可重複使用的技術、模式、工具、參考指南
技能不是： 關於你如何解決某個問題的敘述性故事
技能的 TDD 對應
| TDD 概念 | 技能建立 |
|---|---|
| 測試案例 | 包含子代理的壓力情境 |
| 生產程式碼 | 技能文件 (SKILL.md) |
| 測試失敗 (RED) | 代理在沒有技能時違反規則（基準線） |
| 測試通過 (GREEN) | 代理在有技能時遵守規則 |
| 重構 | 在維持遵守性的同時堵住漏洞 |
| 先寫測試 | 在撰寫技能之前執行基準線情境 |
| 觀察失敗 | 記錄代理所使用的確切合理化藉口 |
| 最小程式碼 | 撰寫專門解決這些特定違規行為的技能 |
| 觀察通過 | 驗證代理現在遵守規則 |
| 重構循環 | 尋找新的合理化藉口 → 堵住漏洞 → 重新驗證 |
整個技能建立過程遵循 RED-GREEN-REFACTOR。
何時建立技能
建立時機：
- 某個技術對你而言並非直觀明顯時
- 你會跨專案再次參考這個方法時
- 該模式具有廣泛適用性（非專案特定）時
- 其他人也能受益時
不建立的情況：
- 一次性解決方案
- 其他地方已有完善文件的標準做法
- 專案特定慣例（請放入你的指令檔中）
- 機械性限制（如果可以用正則表達式/驗證來強制執行，就將其自動化——把文件留給需要判斷的場景）
技能類型
技術
具有可遵循步驟的具體方法（基於條件的等待、根本原因追蹤）
模式
解決問題的思考方式（使用旗標展平、測試不變量）
參考
API 文件、語法指南、工具文件（辦公室文件）
目錄結構
skills/
skill-name/
SKILL.md # 主要參考文件 (必要)
supporting-file.* # 僅在需要時使用
平坦命名空間 - 所有技能位於一個可搜尋的命名空間中
獨立的檔案用於：
- 大型參考（100 行以上） - API 文件、全面的語法
- 可重複使用的工具 - 腳本、工具程式、範本
內嵌保留：
- 原則與概念
- 程式碼模式（少於 50 行）
- 其他所有內容
SKILL.md 結構
前置中繼資料 (YAML)：
- 兩個必要欄位：
name和description（所有支援的欄位請參閱 agentskills.io/specification） - 總字數最多 1024 個字元
name：僅使用字母、數字和連字號（無括號、特殊字元）description：使用第三人稱，僅描述何時使用（而非做什麼）- 以「Use when...」開頭，專注於觸發條件
- 包含具體的症狀、情境和上下文
- 絕對不要總結技能的程序或工作流程（見 SDO 部分說明原因）
- 如果可能，保持在 500 字元以下
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# 技能名稱
## 概述
這是什麼？用 1-2 句話說明核心原則。
## 何時使用
[如果決策不明顯，使用小型內嵌流程圖]
包含**症狀**和使用案例的條列清單
何時不使用
## 核心模式（針對技術/模式）
修改前/修改後的程式碼比較
## 快速參考
用於快速查閱常見操作的表格或條列
## 實作
簡單模式使用內嵌程式碼
大型參考或可重複使用的工具則連結到檔案
## 常見錯誤
哪裡出錯 + 修正方法
## 真實世界影響（選擇性）
具體成果
技能發現優化 (SDO)
對於被發現至關重要： 未來的代理需要找到你的技能
1. 豐富的描述欄位
目的： 你的代理會讀取描述，以決定針對特定任務要載入哪些技能。讓它能回答：「我現在應該閱讀這個技能嗎？」
格式： 以「Use when...」開頭，專注於觸發條件
關鍵：描述 = 何時使用，而非技能做什麼
描述應該僅描述觸發條件。不要在描述中總結技能的程序或工作流程。
為何重要： 測試發現，當描述總結了技能的工作流程時，代理可能會遵循描述，而不去閱讀完整的技能內容。一個描述為「在任務之間進行程式碼審查」的技能，導致代理只進行了一次審查，即使技能的流程圖清楚地顯示了兩階段審查程序（先檢查規範符合性，再檢查程式碼品質）。
當描述改為僅說明「Use when executing implementation plans with independent tasks」（無工作流程摘要）時，代理正確地讀取了流程圖，並遵循了兩階段的審查流程。
陷阱： 總結工作流程的描述會創造一個捷徑，代理會抄捷徑。技能本體變成了代理跳過閱讀的文件。
# ❌ 錯誤：總結了工作流程 - 代理可能遵循此描述而非閱讀技能
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ❌ 錯誤：過程細節太多
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# ✅ 正確：僅觸發條件，無工作流程摘要
description: Use when executing implementation plans with independent tasks in the current session
# ✅ 正確：僅觸發條件
description: Use when implementing any feature or bugfix, before writing implementation code
內容：
- 使用具體的觸發條件、症狀和情境，表明此技能適用
- 描述問題（競爭條件、不一致行為），而非語言特定的症狀（setTimeout、sleep）
- 保持觸發條件與技術無關，除非技能本身是特定於某項技術
- 如果技能是特定於某項技術，請在觸發條件中明確說明
- 使用第三人稱撰寫（會被注入到系統提示詞中）
- 絕對不要總結技能的程序或工作流程
# ❌ 錯誤：過於抽象、模糊，未包含何時使用
description: For async testing
# ❌ 錯誤：第一人稱
description: I can help you with async tests when they're flaky
# ❌ 錯誤：提及技術但技能並非特定於該技術
description: Use when tests use setTimeout/sleep and are flaky
# ✅ 正確：以「Use when」開頭，描述問題，無工作流程
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# ✅ 正確：特定於技術的技能，帶有明確觸發條件
description: Use when using React Router and handling authentication redirects
2. 關鍵字覆蓋
使用代理可能會搜尋的詞彙：
- 錯誤訊息：「Hook timed out」、「ENOTEMPTY」、「race condition」
- 症狀：「flaky」、「hanging」、「zombie」、「pollution」
- 同義詞：「timeout/hang/freeze」、「cleanup/teardown/afterEach」
- 工具：實際的指令、函式庫名稱、檔案類型
3. 描述性命名
使用主動語態，動詞優先：
- ✅
creating-skills而非skill-creation - ✅
condition-based-waiting而非async-test-helpers
4. 權杖效率（關鍵）
問題： 入門指南和經常被引用的技能會載入到每一次對話中。每一個權杖都很重要。
目標字數：
- 入門工作流程：每個 <150 字
- 頻繁載入的技能：總計 <200 字
- 其他技能：<500 字（仍要簡潔）
技巧：
將細節移至工具說明：
# ❌ 錯誤：在 SKILL.md 中記錄所有旗標
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# ✅ 正確：參考 --help
search-conversations supports multiple modes and filters. Run --help for details.
使用交叉引用：
# ❌ 錯誤：重複工作流程細節
When searching, dispatch subagent with template...
[二十行重複的說明]
# ✅ 正確：參考其他技能
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
壓縮範例：
# ❌ 錯誤：冗長的範例（42 字）
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]
# ✅ 正確：最小範例（20 字）
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
消除冗餘：
- 不要重複交叉引用的技能中已有的內容
- 不要解釋從指令中顯而易見的內容
- 不要包含相同模式的多個範例
驗證：
wc -w skills/path/SKILL.md
# 入門工作流程：目標每個 <150
# 其他頻繁載入：目標總計 <200
根據你做的事或核心見解來命名：
- ✅
condition-based-waiting>async-test-helpers - ✅
using-skills而非skill-usage - ✅
flatten-with-flags>data-structure-refactoring - ✅
root-cause-tracing>debugging-techniques
動名詞 (-ing) 對流程來說效果很好：
creating-skills、testing-skills、debugging-with-logs- 主動，描述你正在採取的動作
5. 交叉引用其他技能
在撰寫引用其他技能的文件時：
僅使用技能名稱，並加上明確的必要標記：
- ✅ 正確：
**必要子技能：** Use superpowers:test-driven-development - ✅ 正確：
**必要背景：** You MUST understand superpowers:systematic-debugging - ❌ 錯誤：
See skills/testing/test-driven-development（不清楚是否必要） - ❌ 錯誤：
@skills/testing/test-driven-development/SKILL.md（強制載入，浪費上下文）
為什麼不用 @ 連結： @ 語法會立即強制載入檔案，在你需要它們之前就消耗掉 200k+ 的上下文。
流程圖用法
digraph when_flowchart {
"Need to show information?" [shape=diamond];
"Decision where I might go wrong?" [shape=diamond];
"Use markdown" [shape=box];
"Small inline flowchart" [shape=box];
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
}
僅在以下情況使用流程圖：
- 非顯而易見的決策點
- 可能會過早停止的流程循環
- 「何時使用 A 與 B」的決策
絕對不要將流程圖用於：
- 參考資料 → 表格、清單
- 程式碼範例 → Markdown 區塊
- 線性說明 → 編號清單
- 沒有語義意義的標籤（step1、helper2）
請參閱此目錄中的 graphviz-conventions.dot 以了解 graphviz 樣式規則。
為你的合作夥伴視覺化： 使用此目錄中的 render-graphs.js 將技能的流程圖渲染為 SVG：
node ./render-graphs.js ../some-skill # 每個圖表單獨渲染
node ./render-graphs.js ../some-skill --combine # 所有圖表合併為一個 SVG
程式碼範例
一個優秀的範例勝過許多平庸的範例
選擇最相關的語言：
- 測試技術 → TypeScript/JavaScript
- 系統除錯 → Shell/Python
- 資料處理 → Python
好的範例：
- 完整且可執行
- 註解完善，解釋為什麼
- 來自真實場景
- 清晰地展示模式
- 準備好進行改編（而非泛型範本）
不要：
- 用 5 種以上語言實作
- 建立填空範本
- 撰寫人為編造的範例
你擅長移植——一個出色的範例就足夠了。
檔案組織
自包含技能
defense-in-depth/
SKILL.md # 所有內容內嵌
適用時機：所有內容都能容納，無需大型參考
附帶可重複使用工具的技能
condition-based-waiting/
SKILL.md # 概述 + 模式
example.ts # 可供改編的工作用輔助程式
適用時機：工具是可重複使用的程式碼，而非僅敘述
附帶大型參考的技能
pptx/
SKILL.md # 概述 + 工作流程
pptxgenjs.md # 600 行 API 參考
ooxml.md # 500 行 XML 結構
scripts/ # 可執行的工具
適用時機：參考資料太大，無法內嵌
透過它們的直譯器在 prose 中調用捆綁的腳本（bash scripts/tool.sh、node scripts/tool.js），絕對不要使用裸路徑：某些 harness 套件打包器會剝奪可執行位元，裸調用 scripts/tool.sh 會在那裡失敗並顯示 Permission denied。
鐵律（與 TDD 相同）
沒有先有失敗的測試，就沒有技能
這適用於新技能以及對現有技能的編輯。
在測試之前就撰寫了技能？刪掉它。重新開始。 未經測試編輯技能？同樣的違規。
沒有例外：
- 不是為了「簡單的補充」
- 不是為了「只是新增一個段落」
- 不是為了「文件更新」
- 不要保留未經測試的更改作為「參考」
- 不要
…
[已截斷以供翻譯]