writing-skillslisted

# 撰寫技能 ## 總覽 **撰寫技能，就是將測試驅動開發應用於流程文件。** **個人技能存放於你執行環境的 skills 目錄**（Claude Code 是 `~/.claude/skills/`）——其他執行環境的路徑請見 [codex-tools.md](../using-superpowers/references/codex-tools.md) 或 [gemini-tools.md](../using-superpowers/references/gemini-tools.md)。Codex、Copilot CLI 與 Gemini CLI 也都能辨識 `~/.agents/skills/` 作為跨執行環境的別名。 你撰寫測試案例（搭配子代理的壓力情境）、觀察其失敗（基線行為）、撰寫技能（文件）、觀察測試通過（代理遵從），然後重構（關閉漏洞）。 **核心原則：**如果你沒有看過代理在沒有技能時失敗，你就不會知道該技能是否教對了事情。 **必備背景：**使用本技能前，你必須先理解 superpowers:test-driven-development。該技能定義了根本的紅 → 綠 → 重構循環。本技能將 TDD 應用於文件撰寫。 **官方指引：**關於 Anthropic 官方的技能撰寫最佳實務，請見 anthropic-best-practices.md。該文件提供與本技能 TDD 導向方法互補的額外模式與準則。 ## 什麼是技能？ **技能**是針對經過驗證的技術、模式或工具的參考指南。技能幫助未來的代理找到並套用有效的方法。 **技能是：**可重用的技術、模式、工具、參考指南 **技能不是：**關於你曾如何解決某個問題的敘事 ## 技能的 TDD 對應 | TDD 概念 | 技能建立 | |-------------|----------------| | **測試案例** | 搭配子代理的壓力情境 | | **實作程式碼** | 技能文件（SKILL.md） | | **測試失敗（紅）** | 代理在沒有技能時違反規則（基線） | | **測試通過（綠）** | 代理在有技能時遵從 | | **重構** | 關閉漏洞同時維持遵從 | | **先寫測試** | 在撰寫技能前���執行基線情境 | | **觀察其失敗** | 逐字記錄代理使用的合理化藉口 | | **最小化程式碼** | 撰寫能針對那些特定違規的技能 | | **觀察其通過** | 驗證代理現在確實遵從 | | **重構循環** | 找出新的合理化藉口 → 堵住 → 重新驗證 | 整個技能建立流程都遵循紅 → 綠 → 重構。 ## 何時建立技能 **以下情況建立：** - 技術對你而言並非直覺上顯而易見 - 你會想在跨專案時再次參考它 - 模式適用範圍廣（非專案特定） - 其他人也會受益 **以下情況不要建立：** - 一次性解決方案 - 其他地方已有良��文件記載的標準做法 - 專案特定的慣例（放進你的 instructions 檔案） - 機械性限制（若能用 regex／驗證強制執行，就自動化它——把文件留給需要判斷的情境） ## 技能類型 ### 技術 有步驟可循的具體方法（condition-based-waiting、root-cause-tracing） ### 模式 思考問題的方式（flatten-with-flags、test-invariants） ### 參考文件 API 文件、語法指南、工具文件（of