writing-skills

撰寫技能

概述

撰寫技能就是將測試驅動開發應用於流程文件。

個人技能存放在執行環境的技能目錄中 — 請參閱 claude-code-tools.md、codex-tools.md、copilot-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。

何時建立技能

建立時機：

技巧對你來說並非直觀明顯
你會跨專案再次參考此技巧
模式廣泛適用（非專案特定）
其他人會受益

不要為以下情況建立：

一次性解決方案
其他地方已有完善文件的一般實務
專案特定的慣例（放在你的指令檔案中）
機械性限制（如果可以透過正則表達式/驗證強制執行，就自動化它—將文件留給需要判斷的情況）

技能類型

技巧

具有可遵循步驟的具體方法（condition-based-waiting、root-cause-tracing）

模式

解決問題的思考方式（flatten-with-flags、test-invariants）

參考

API 文件、語法指南、工具文件（office docs）

目錄結構

skills/
  skill-name/
    SKILL.md              # 主要參考（必要）
    supporting-file.*     # 僅在需要時

扁平命名空間 - 所有技能都在一個可搜尋的命名空間中

獨立檔案用於：

大量參考（100 行以上）- API 文件、完整語法
可重複使用的工具 - 腳本、工具、範本

保持內嵌：

原則與概念
程式碼模式（少於 50 行）
其他所有內容

SKILL.md 結構

Frontmatter (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]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

技能發現最佳化 (SDO)

對發現至關重要： 未來的代理需要找到你的技能

1. 豐富的描述欄位

目的： 你的代理會讀取描述來決定針對給定任務要載入哪些技能。讓它回答：「我現在應該閱讀這個技能嗎？」

格式： 以「Use when...」開頭，聚焦於觸發條件

關鍵：描述 = 何時使用，而非技能做什麼

描述應該只描述觸發條件。不要在描述中總結技能的流程或工作流程。

為什麼這很重要： 測試顯示，當描述總結了技能的工作流程時，代理可能會遵循描述而不是閱讀完整的技能內容。一個描述為「在任務之間進行程式碼審查」的技能導致代理只做了一次審查，即使技能的流程圖清楚顯示了兩次審查（規格遵循性然後程式碼品質）。

當描述改為「在執行包含獨立任務的實作計畫時使用」（沒有工作流程摘要），代理正確地閱讀了流程圖並遵循了兩階段審查流程。

陷阱： 總結工作流程的描述會創造一個代理會走捷徑。技能本體變成代理跳過的文件。

# ❌ 不好：總結工作流程 - 代理可能遵循此描述而非閱讀技能
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. Token 效率（關鍵）

問題： getting-started 和經常被參考的技能會載入到每個對話中。每個 token 都很重要。

目標字數：

getting-started 工作流程：每個少於 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...
[20 lines of repeated instructions]

# ✅ 好：參考其他技能
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
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

根據你做的事或核心見解命名：

✅ 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. 交叉參考其他技能

在撰寫參考其他技能的文件時：

僅使用技能名稱，並加上明確的必要標記：

✅ 好：**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
✅ 好：**REQUIRED BACKGROUND:** 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：

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

程式碼範例

一個優秀的範例勝過許多平庸的範例

選擇最相關的語言：

測試技巧 → TypeScript/JavaScript
系統除錯 → Shell/Python
資料處理 → Python

好的範例：

完整且可執行
有良好的註解說明 WHY
來自真實情境
清楚展示模式
可直接改編（非通用範本）

不要：

用 5 種以上語言實作
建立填空範本
編寫牽強的範例

你很擅長移植 — 一個好的範例就夠了。

檔案組織

自包含技能

defense-in-depth/
  SKILL.md    # Everything inline

時機：所有內容都適合，不需要大量參考

包含可重複使用工具的技能

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

時機：工具是可重複使用的程式碼，而非僅敘述

包含大量參考的技能

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

時機：參考資料太大無法內嵌

鐵律（與 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

這適用於新技能和對現有技能的編輯。

先寫技能再測試？刪掉它。重新開始。
編輯技能而不測試？同樣的違規。

沒有例外：

不是「簡單的補充」
不是「只是加一個章節」
不是「文件更新」
不要保留未測試的變更作為「參考」
不要在執行測試時「改編」
刪除就是刪除

必要背景： superpowers:test-driven-development 技能解釋了為什麼這很重要。同樣的原則適用於文件。

測試所有技能類型

不同技能類型需要不同的測試方法：

紀律強制技能（規則/要求）

範例： TDD、verification-before-completion、designing-before-coding

測試方式：

學術問題：他們是否理解規則？
壓力情境：他們在壓力下是否遵循？
多重壓力組合：時間 + 沉沒成本 + 疲勞
識別合理化藉口並加入明確的反制

成功標準： 代理在最大壓力下遵循規則

技巧技能（操作指南）

範例： condition-based-waiting、root-cause-tracing、defensive-programming

測試方式：

應用情境：他們能否正確應用技巧？
變化情境：他們是否處理邊界情況？
資訊缺失測試：指令是否有缺口？

成功標準： 代理成功將技巧應用於新情境

模式技能（心智模型）

範例： reducing-complexity、information-hiding concepts

測試方式：

識別情境：他們是否識別出模式適用的時機？
應用情境：他們能否使用心智模型？
反例：他們是否知道何時不該應用？

成功標準： 代理正確識別何時/如何應用模式

參考技能（文件/API）

範例： API documentation、command references、library guides

測試方式：

檢索情境：他們能否找到正確資訊？
應用情境：他們能否正確使用找到的資訊？
缺口測試：常見使用案例是否涵蓋？

成功標準： 代理找到並正確應用參考資訊

跳過測試的常見合理化藉口

藉口	現實
「技能顯然很清楚」	你清楚 ≠ 其他代理清楚。測試它。
「這只是參考」	參考可能有缺口、不清楚的章節。測試檢索。
「測試小題大作」	未測試的技能總有問題。15 分鐘測試省下數小時。
「等問題出現再測試」	問題 = 代理無法使用技能。在部署前測試。
「測試太繁瑣」	測試比在生產環境中除錯壞掉的技能不那麼繁瑣。
「我有信心它很好」	過度自信保證有問題。無論如何都要測試。
「學術審查就夠了」	閱讀 ≠ 使用。測試應用情境。
「沒時間測試」	部署未測試的技能會浪費更多時間來修復。

所有這些都意味著：在部署前測試。沒有例外。

將形式與失敗匹配

在撰寫指導之前，先分類基準失敗。一種形式能防禦一種失敗類型，但可能對另一種造成反效果。

基準失敗	正確形式	錯誤形式
在壓力下跳過/違反規則（知道更好，但還是做了）	禁止 + 合理化藉口表 + 紅旗（見下方防禦）	軟性指導（「prefer...」、「consider...」）
遵循規範，但輸出形狀錯誤（提示過於冗長、結論被埋沒、重複規格）	正面配方或契約：說明輸出的內容 — 其組成部分，按順序	禁止列表（「don't restate」、「never narrate」）
從他們已經產生的東西中遺漏了必要元素	結構性：在他們填寫的範本中的 REQUIRED 欄位或插槽	範本附近的散文提醒
行為應取決於條件	條件式，鍵入可觀察的謂詞（「如果簡報存在，請參考它」）	無條件規則 + 豁免條款

為什麼禁止在形狀問題上會反效果： 在競爭性誘因下（「讓提示自包含」），代理會與「不要 X」協商。在針對 dispatch-prompt 指導的逐字測試中，禁止組產生了明顯更多的不需要的內容，比配方組更多（完全分離的分佈），甚至比無指導控制組更差 — 請微測試你自己的案例，而不是假設，但永遠不要預設使用禁止。配方沒有什麼好協商的：輸出符合所述形狀，否則就不符合。

無論你選擇哪種形式的規則：

沒有細微差別條款。 「除非重要，否則不要 X」重新開啟協商 — 在一個成功的配方上附加一個細微差別條款，在相同的逐字測試中使其從一致變為嘈雜。將真正的例外表達為基於可觀察謂詞的自己的條件。
豁免條款不會限定範圍。 「此限制不適用於程式碼區塊」仍然抑制程式碼區塊。如果輸出的某些部分必須豁免，請重構結構，使規則無法觸及它。

防禦技能對抗合理化

強制紀律的技能（如 TDD）需要抵抗合理化。代理很聰明，在壓力下會找到漏洞。

範圍： 這個工具包適用於紀律失敗 — 代理知道規則但在壓力下跳過它。對於形狀錯誤的輸出或遺漏的元素，基於禁止的防禦會反效果；請改用「將形式與失敗匹配」中的形式。

心理學備註： 了解說服技巧為何有效，有助於你系統性地應用它們。請參閱 persuasion-principles.md 以了解關於權威、承諾、稀缺、社會證明和團結原則的研究基礎（Cialdini, 2021; Meincke et al., 2025）。

明確堵住每個漏洞

不要只陳述規則 — 禁止特定的變通方法：

<Bad>

Write code before test? Delete it.

</Bad>

<Good>

Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete

</Good>

處理「精神與文字」的論點

在早期加入基本原則：

**Violating the letter of the rules is violating the spirit of the rules.**

這切斷了整類「我遵循精神」的合理化。

建立合理化藉口表

從基準測試中捕捉合理化藉口（見下方測試章節）。代理使用的每個藉口都放入表中：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

建立紅旗列表

讓代理在合理化時容易自我檢查：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

更新 SDO 以包含違規症狀

在描述中加入：你即將違反規則時的症狀：

description: use when implementing any feature or bugfix, before writing implementation code

技能的 RED-GREEN-REFACTOR

遵循 TDD 循環：

RED：撰寫失敗測試（基準）

在沒有技能的情況下，使用子代理執行壓力情境。記錄確切行為：

他們做了什麼選擇？
他們使用了什麼合理化藉口（逐字）？
哪些壓力觸發了違規？

這就是「觀察測試失敗」— 你必須在撰寫技能之前看到代理自然會做什麼。

GREEN：撰寫最小技能

撰寫技能來處理那些特定的合理化藉口。不要為假設情況添加額外內容。

在有技能的情況下執行相同情境。代理現在應該遵循規範。

REFACTOR：堵住漏洞

代理發現了新的合理化藉口？加入明確的反制。重新測試直到防禦完善。

在完整情境之前微測試措辭

完整的壓力情境執行是最終關卡，但每次迭代緩慢且昂貴。先用微測試驗證措辭本身：

每次呼叫一個全新的上下文樣本 — 原始 API 呼叫，或如果你沒有 API 存取權限，則為單次子代理。系統提示 = 指導將存在的現實上下文（完整的技能或提示範本，而非孤立的指導）；使用者訊息 = 一個會誘發失敗的任務。
始終包含無指導控制組。 如果控制組沒有表現出失敗，就沒有什麼需要修復 — 停止，不要撰寫指導。
每個變體 5 次以上重複。 單一樣本會說謊。
手動閱讀每個標記的匹配。 如果你喜歡，可以用程式計分，但範本回聲和引用的反例會偽裝成命中；僅自動計數會高估失敗和成功。
變異數是一個指標。 當指導生效時，重複會收斂到相同的形狀。五次重複中有五種不同的解釋意味著措辭沒有約束力 — 在增加文字之前先緊縮形式。

微測試驗證措辭；它們不能取代紀律技能的壓力情境。

測試方法： 請參閱 testing-skills-with-subagents.md 以了解完整的測試方法：

如何撰寫壓力情境
壓力類型（時間、沉沒成本、權威、疲勞）
系統性地堵住漏洞
元測試技巧

反模式

❌ 敘述範例

"In session 2025-10-03, we found empty projectDir caused..."
為什麼不好： 太具體，不可重複使用

❌ 多語言稀釋

example-js.js、example-py.py、example-go.go
為什麼不好： 品質平庸，維護負擔

❌ 流程圖中的程式碼

step1 [label="import fs"];
step2 [label="read file"];

為什麼不好： 無法複製貼上，難以閱讀

❌ 通用標籤

helper1、helper2、step3、pattern4
為什麼不好： 標籤應具有語義意義

停止：在進入下一個技能之前

在撰寫任何技能之後，你必須停止並完成部署流程。

不要：

批次建立多個技能而不測試每個
在當前技能驗證之前就進入下一個技能
因為「批次更有效率」而跳過測試

下面的部署檢查清單對每個技能都是強制性的。

部署未測試的技能 = 部署未測試的程式碼。這是違反品質標準的行為。

技能建立檢查清單（TDD 改編）

重要：為下方每個檢查清單項目建立一個待辦事項。

RED 階段 - 撰寫失敗測試：

[ ] 建立壓力情境（紀律技能需要 3 種以上壓力組合）
[ ] 在沒有技能的情況下執行情境 - 逐字記錄基準行為
[ ] 識別合理化/失敗的模式

GREEN 階段 - 撰寫最小技能：

[ ] 名稱僅使用字母、數字、連字號（無括號/特殊字元）
[ ] YAML frontmatter 包含必要的 name 和 description 欄位（最多 1024 字元；請參閱 spec）
[ ] 描述以「Use when...」開頭，並包含具體觸發條件/症狀
[ ] 描述以第三人稱撰寫
[ ] 全文包含關鍵字以便搜尋（錯誤、症狀、工具）
[ ] 清晰的概述，包含核心原則
[ ] 處理 RED 階段識別的具體基準失敗
[ ] 指導形式與失敗類型匹配（見「將形式與失敗匹配」）
[ ] 對於行為塑造指導：措辭已針對無指導控制組進行微測試（5 次以上重複，每個標記的匹配手動閱讀）— 純參考技能不適用
[ ] 程式碼內嵌或連結到獨立檔案
[ ] 一個優秀的範例（非多語言）
[ ] 在有技能的情況下執行情境 - 驗證代理現在遵循規範

REFACTOR 階段 - 堵住漏洞：

[ ] 從測試中識別新的合理化藉口
[ ] 加入明確的反制（如果是紀律技能）
[ ] 從所有測試迭代建立合理化藉口表
[ ] 建立紅旗列表
[ ] 重新測試直到防禦完善

品質檢查：

[ ] 僅在決策非顯而易見時使用小型流程圖
[ ] 快速參考表
[ ] 常見錯誤章節
[ ] 沒有敘述故事
[ ] 支援檔案僅用於工具或大量參考

部署：

[ ] 將技能提交到 git 並推送到你的分支（如果已設定）
[ ] 考慮透過 PR 回饋（如果廣泛有用）

發現工作流程

未來代理如何找到你的技能：

遇到問題（「測試不穩定」）
搜尋技能（grep 描述，瀏覽類別）
找到技能（描述匹配）
掃描概述（這相關嗎？）
閱讀模式（快速參考表）
載入範例（僅在實作時）

針對此流程最佳化 - 將可搜尋的術語放在早期且頻繁出現。

結論

建立技能就是將 TDD 應用於流程文件。

相同的鐵律：沒有技能可以在沒有先失敗測試的情況下存在。
相同的循環：RED（基準）→ GREEN（撰寫技能）→ REFACTOR（堵住漏洞）。
相同的好處：更好的品質、更少的意外、防禦完善的結果。

如果你對程式碼遵循 TDD，就對技能遵循它。這是應用於文件的相同紀律。

您可能也喜歡

learn

6.4Kresearch-knowledge

執行六階段研究流程，將不熟悉的領域、來源素材或收集到的資料轉換為可發布的輸出。當使用者以任何語言要求研究、學習、深入探討、彙整來源、綜合不熟悉的素材，或將來源素材轉換為連貫的參考資料時使用。不適用於快速查詢或單一檔案閱讀。

tw93

獲取

summarize

380Kresearch-knowledge

總結或轉錄網址、YouTube/影片、播客、文章、逐字稿、PDF 和本地檔案。

steipete

獲取

planning-and-task-breakdown

77Kresearch-knowledge

將工作分解為有序的任務。當你有規格或明確的需求，需要將工作分解為可實作的任務時使用。當任務感覺太大而無法開始、需要估算範圍或可以平行工作時使用。

addyosmani

獲取

繼續探索

瀏覽 research-knowledge 熱門 Skills 最近更新

writing-skills

相關技能

撰寫技能

概述

什麼是技能？

技能的 TDD 對應

何時建立技能

技能類型

技巧

模式

參考

目錄結構

SKILL.md 結構

技能發現最佳化 (SDO)

1. 豐富的描述欄位

2. 關鍵字覆蓋

3. 描述性命名

4. Token 效率（關鍵）

5. 交叉參考其他技能

流程圖使用

程式碼範例

檔案組織

自包含技能

包含可重複使用工具的技能

包含大量參考的技能

鐵律（與 TDD 相同）

測試所有技能類型

紀律強制技能（規則/要求）

技巧技能（操作指南）

模式技能（心智模型）

參考技能（文件/API）

跳過測試的常見合理化藉口

將形式與失敗匹配

防禦技能對抗合理化

明確堵住每個漏洞

處理「精神與文字」的論點

建立合理化藉口表

建立紅旗列表

更新 SDO 以包含違規症狀

技能的 RED-GREEN-REFACTOR

RED：撰寫失敗測試（基準）

GREEN：撰寫最小技能

REFACTOR：堵住漏洞

在完整情境之前微測試措辭

反模式

❌ 敘述範例

❌ 多語言稀釋

❌ 流程圖中的程式碼

❌ 通用標籤

停止：在進入下一個技能之前

技能建立檢查清單（TDD 改編）

發現工作流程

結論

您可能也喜歡

learn

summarize

planning-and-task-breakdown

繼續探索