SNNN-011/skill-authoring

Skill Authoring

建立能真正改變 Agent 行為的技能指南，而非一份從未被讀過的文件。

核心原則：技能是操作說明，不是文章。 如果 Agent 載入此技能後行為沒有任何不同，那它就是一個失敗的技能。

如何使用此技能

此技能透過對話使用，而非一次性執行。流程如下：

1. 使用者觸發技能（例如：「使用 skill-authoring 技能，我想為我的 Agent 建立一個技能」）。
2. Agent 停止撰寫，開始進行步驟 1 的訪談：每次只問一個問題，等待回覆。
3. 五個問題都回答完後，Agent 執行步驟 2 到 5，並向使用者展示草稿。
4. 使用者同意後，Agent 寫入檔案（步驟 6），接著執行觸發測試（步驟 7）與檢查清單（步驟 8）。

給 Agent 的規則：

• 在步驟 1 的五個問題都回答完之前，不要寫入 SKILL.md。過早草擬會中斷訪談。
• 不要一次問完五個問題。每次一個，並在每個問題中提供簡短範例。
• 如果使用者只想要「快速範例」，至少問完問題 1 和 4，再繼續後續步驟。
• 一開始就告知使用者：最終產出是一個可立即使用的 SKILL.md 檔案。

何時觸發此技能

• 使用者說「建立技能」、「創建技能」、「如何建立技能」、「為我的 Agent 建立技能」。
• 使用者有 Agent 功能的想法，但不確定如何具體描述。
• 現有技能從未被觸發或未被 Agent 遵循。
• 需要決定：這應該做成技能（Skill）、代理（Agent）、命令（Command）還是鉤子（Hook）？

要尋找現有技能，請先使用 skill-scout。要審核已累積過多的技能，請使用 skill-stocktake。

步驟 0 - 撰寫前的基本規則

一個好的技能具備四個特性：

特性	意義
特定	解決單一類型的工作，而非「所有與後端相關的事情」
可操作	包含步驟、指令、真實範例，而非理論
可觸發	description 包含使用者實際會說的詞語
有限制	少於 500 行；理想為 100-250 行

如果技能想法不符合這四點，請先修正想法，不要急著寫檔案。

步驟 1 - 捕捉真實問題，而非功能

不要從「用於測試的技能」開始。要從具體的失敗情況開始。

向使用者提出這五個問題（一次一個，不要同時問）：

1. Agent 現在做錯了什麼或行為不一致？請提供一個具體的實際例子。
2. 這種情況發生在什麼時候？（寫程式碼、審查 PR、部署、回答使用者問題、分析資料）
3. 你期望的正確結果是什麼樣的？請展示一個你認為好的輸出範例。
4. 為了完成任務，Agent 有哪些不知道、必須透過這個技能告知的資訊？（團隊慣例、執行順序、常見陷阱）
5. 執行此技能時，Agent 不應該做什麼？

問題 4 和 5 的答案才是技能的真正內容。問題 1 和 2 的答案是 description 的內容。

如果使用者無法回答問題 1，請停止流程。目前並不需要建立技能——那只是一個願望。請直接告知使用者。

步驟 2 - 選擇正確的形式

不要把所有事情都做成技能。選擇最能以最低成本解決問題的形式。

需求	形式	原因
撰寫程式碼時反覆使用的知識/慣例	技能	自動載入，無需手動呼叫
獨立的多步驟任務，需隔離上下文	代理	可並行執行，擁有自己的上下文
使用者有意識地觸發的動作，帶有參數	命令	/{名稱} 明確，非自動
針對事件自動運作的行為（提交前、編輯後）	鉤子	無需模型決策即可運行
適用於所有工作的簡短規則	規則	永遠啟用，無需觸發
供人類閱讀的長篇說明	文件	Agent 不需要載入

實用原則：

• 需要觸發條件？用技能。
• 需要隔離上下文或限制工具？用代理。
• 需要手動呼叫並帶參數？用命令。
• 需要無需要求即自動執行？用鉤子。
• 需要永遠正確、絕不違反？用規則。
• 需要給人看而不是給 Agent 看？用文件。

如果在技能和規則之間猶豫：如果內容少於 10 行且適用於所有情境，那就是規則。

步驟 3 - 先搜尋重複項

在開始撰寫前，先進行搜尋。不同平台的技能資料夾路徑不同——請根據使用者的平台進行調整：

平台	技能資料夾
Claude Code	~/.claude/skills/ 或專案中的 .claude/skills/
OpenCode	~/.config/opencode/skills/ 或 .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# 已安裝的技能（將 <技能資料夾> 替換為上表對應的路徑）
grep -ril "關鍵詞" <技能資料夾> --include=SKILL.md

# 如果當前正在一個包含 skills/ 資料夾的儲存庫中
grep -ril "關鍵詞" skills --include=SKILL.md

如果使用者不知道自己的技能資料夾在哪，請解釋上表並請他們選擇使用的平台。不要猜測。

如果已有非常相似的功能，請決定：直接使用、擴展現有的，還是建立新的。重複的技能會讓 Agent 難以選擇，並浪費上下文空間。

步驟 4 - 撰寫 description（最重要的部分）

description 是 Agent 用來決定是否載入此技能的唯一依據。這裡錯了，技能就廢了。

公式：

[要完成的活動] + [觸發的上下文] + [使用者會用的關鍵詞] + [何時不使用]

錯誤範例：

description: 協助進行測試

正確範例：

description: 使用 Vitest 和 Testing Library 進行 React 測試的模式 - 渲染、使用者事件、模擬網路請求以及可及性斷言。在撰寫或修復 React 元件測試時使用。不適用於 E2E 測試（請使用 e2e-testing）。

規則：

• 使用使用者實際會輸入的詞語，而非內部術語。
• 說明範圍限制，以免此技能搶走其他技能的工作。
• 保持為一行，字串內不要有換行。
• 避免使用單一的通用詞，如「程式碼」、「協助」、「各種」。

快速測試：關閉檔案，只讀 description。如果你作為 Agent 都不確定何時該載入它，請重寫。

步驟 5 - 組織內容

經實證有效的章節順序：

---
name: 技能名稱
description: <步驟 4 的公式>
metadata:
  origin: ECC
---

# 標題

一段話：這個技能改變了 Agent 的哪些行為。

## 何時觸發
具體的觸發條件列表。

## 核心內容
工作步驟、決策表格或規則。這佔了技能內容的 70%。

## 範例
一個錯誤範例，一個正確範例。要真實，不要用佔位符。

## 反模式
應避免的錯誤，並附上簡短原因。

## 檢查清單
可以被驗證的核取方塊。

## 相關技能
二到四個技能名稱。

內容撰寫規則：

• 使用命令句（「執行 X」），而非被動描述（「X 可以被執行」）。
• 決策用表格，順序用編號列表，指令用程式碼區塊。
• 每條規則都必須可以被驗證——「寫出乾淨的程式碼」不行，「函式最多 50 行」可以。
• 在 Agent 會執行的部分中，不要使用 [在此填入]、TODO 或 ... 這類佔位符。
• 不要直接複製貼上外部產品的內容——吸收其概念，用自己的上下文重新撰寫。
• 不要包含機密資訊：API 金鑰、令牌、絕對路徑的個人資料夾、公司內部名稱。

長度限制：500 行（嚴格上限為 800）。如果超過，請拆分成兩個技能，或將細節移至同技能資料夾下的 references/ 目錄。

步驟 6 - 寫入檔案

在寫入前，先確認最後兩件事：

1. 技能語言 - 使用使用者日常使用的語言，還是為了可攜性使用英文？依據使用者的回答執行，不要擅自決定。
2. 資料夾名稱 - 提出一個描述性的 kebab-case 名稱（例如：react-component-testing），並取得使用者同意。

然後寫入 <技能資料夾>/<名稱>/SKILL.md。不可違反的規則：

• 前端訊息中的 name: 必須與資料夾名稱完全相同。若不符，某些平台會拒絕載入技能。
• 先向使用者展示完整的草稿，然後再儲存。不要默默地儲存。
• 在 Agent 會執行的部分中，不要留下佔位符（TODO、[在此填入]、...）。
• 儲存後，回報完整路徑，並用一句話說明如何觸發：「從現在起，當 <觸發條件> 時，請要求 Agent 使用 <名稱> 技能。」

步驟 7 - 使用前先測試

至少執行三項測試。一項都不能省略。

測試 1 - 正向觸發（啟動） 給 Agent 一個應該會觸發此技能的任務，但不要提及技能名稱。

"請幫我為 LoginButton 元件撰寫測試。"

通過條件：技能被載入。失敗表示 description 缺少關鍵詞。

測試 2 - 負向觸發（不啟動） 給予一個相似但不屬於此技能範疇的任務。

"請幫我撰寫登入流程的 E2E 測試。"

通過條件：技能沒有被載入（或 Agent 選擇了其他更合適的技能）。失敗表示 description 範圍太廣。

測試 3 - 執行測試 要求 Agent 執行一個會真正觸發此技能的任務，然後比較有載入和沒有載入此技能時的輸出。

無技能時：Agent 以樣式 X 撰寫測試
有技能時：Agent 以樣式 Y 撰寫測試（符合團隊慣例）

通過條件：可以展示出行為上的差異。如果輸出完全相同，則此技能無用——請刪除或合併。

步驟 8 - 準備完成的檢查清單

• 檔案位於 <技能資料夾>/{名稱}/SKILL.md，且 name: 與資料夾名稱完全相同
• description 為一行，包含使用者的關鍵詞與範圍限制
• description 不使用字面區塊（|），僅使用單行字串
• 有明確的「何時觸發」章節
• 每條規則都可被驗證，沒有「寫出好的程式碼」這種模糊描述
• 至少包含一個錯誤範例和一個正確範例
• 包含反模式
• 少於 500 行
• 沒有機密、令牌或絕對路徑的個人資訊
• 已執行測試 1、2 和 3，並記錄結果
• 已執行步驟 3，沒有發現重複項
• 在結尾處提及 2-4 個相關技能

僅在使用者的儲存庫中確實有驗證工具時，才進行自動驗證：

# ECC / 包含技能驗證工具的儲存庫
node scripts/ci/validate-skills.js

如果沒有驗證工具，請手動檢查四個最常失敗的項目：name: 是否與資料夾相符、description 是否為一行、行數是否少於 500、以及沒有佔位符。告知使用者目前使用的是這種手動檢查方式。

即用型模板

---
name: 技能名稱
description: <活動> - <範圍>. 在 <具體觸發條件> 時使用。不適用於 <超出範圍的情況>。
metadata:
  origin: ECC
---

# 技能名稱

載入此技能後，Agent 的行為會有哪些改變。

## 何時觸發
- <觸發條件 1>
- <觸發條件 2>

## 步驟
1. <可立即執行的第一步>
2. <第二步>
3. <驗證>

## 範例
錯誤：<常見的錯誤程式碼或回應>
正確：<期望的版本，附上簡短原因>

## 反模式
- <錯誤的做法> - <為何不好>

## 檢查清單
- [ ] <可透過肉眼或機器檢查的事項>

## 相關技能
- `<技能-a>`, `<技能-b>`

技能創作的反模式

• 沒有觸發條件的技能。 description 含糊不清，技能從未被載入。這是最常見的失敗原因。
• 文字牆技能。 900 行的理論，卻沒有一條實際指令。Agent 載入後完全忽略它。
• 「要變得有幫助」的技能。 沒有提供具體知識，結果與沒有技能完全相同。
• 重複的技能。 兩個技能聲稱擁有相同領域；Agent 隨機選擇。
• 完全複製他人的技能。 包含你不自覺的隱藏指令和依賴項。
• 包含機密或個人路徑的技能。 分享技能時會一併外洩。
• 為單一事件編寫技能。 如果只用一次，那就不是技能——那是文件或命令。
• 在搜尋之前就建立技能。 務必先執行步驟 3。

何時不需要建立技能

如果符合以下任一情況，請直接告訴使用者：

• 問題是程式碼中的錯誤，而不是 Agent 知識不足。
• 只需要執行一次——直接給出指令即可。
• 內容少於 10 行的通用規則——那是規則。
• 只需加入專案的 AGENTS.md 或 CLAUDE.md 即可。
• 已有技能涵蓋了 80% 的需求——擴展現有的即可。

相關技能

• skill-scout - 在建立新技能前搜尋現有技能
• skill-stocktake - 審核已累積過多技能的品質
• skill-comply - 衡量技能是否確實被 Agent 遵循
• agent-harness-construction - 設計 Agent 的工具與行為邊界