# Skills 設計最佳實踐

本文件整理 skills 設計和開發中的最佳實踐和常見錯誤，幫助你避免陷阱，寫出高品質的 skills。

## 常見錯誤

### 1. 過早抽象（Premature Abstraction）

#### 錯誤示範

```markdown
場景：正在開發第一個使用某個邏輯的 command

開發者：「這個檔案分析邏輯未來可能會在其他地方用到，
        我先把它抽成一個 skill 好了。」

結果：
- 創建了一個只有一個使用者的 skill
- 增加了不必要的複雜度
- 後來發現其他地方根本不需要這個邏輯
```

#### 為什麼會發生

- **過度優化**：想要提前做好「未來的準備」
- **誤解 DRY 原則**：認為「可能重複」就要抽象
- **缺乏判斷標準**：沒有明確的判斷流程

#### 正確做法

```markdown
✅ 第一次使用：直接寫在 command 中，保持簡單

✅ 第二次使用：這時候才考慮是否要抽取成 skill
   - 檢查兩個使用場景的相似度
   - 評估未來的擴展可能性
   - 如果高度相似且可能繼續擴展，才抽取

✅ 第三次使用：必須抽取成 skill
   - 此時已經有明確的重複使用模式
   - DRY 原則明確適用
```

#### 記住

> **YAGNI（You Aren't Gonna Need It）**：不要為「可能的」未來需求設計，等需求真正出現再重構。

---

### 2. 過度細分（Over-Fragmentation）

#### 錯誤示範

```markdown
場景：將 3 行簡單的邏輯抽成一個 skill

# skills/format-string/SKILL.md
---
name: Format-String
description: 格式化字串，移除首尾空白
---

## 執行步驟
1. 使用 trim() 移除首尾空白
2. 轉換為小寫
3. 返回結果

結果：
- 檔案過多，難以維護
- 增加理解成本
- 這種簡單邏輯應該直接內嵌在 command 中
```

#### 為什麼會發生

- **誤解模組化**：認為「什麼都要獨立」
- **忽略複雜度**：簡單邏輯也獨立成 skill
- **缺乏成本意識**：沒有考慮維護成本

#### 正確做法

```markdown
❌ 不獨立：3 行以下的簡單邏輯
   - 直接寫在 command 中
   - 保持程式碼的連貫性

✅ 考慮獨立：5+ 行且有重複使用的可能
   - 邏輯稍微複雜
   - 有明確的第二個使用場景

✅ 必須獨立：10+ 行或有複雜分支邏輯
   - 即使只有一個使用場景
   - 也值得為了可讀性獨立出來
```

#### 判斷原則

**詢問自己**：
- 這個邏輯獨立出來後，是否更容易理解？
- 維護兩個地方（skill 定義 + command 引用）是否比直接寫在 command 中更簡單？
- 未來真的會在其他地方使用嗎？

如果答案都是「否」，那就不要獨立。

---

### 3. 職責不清（Unclear Responsibility）

#### 錯誤示範

```markdown
# skills/commit-helper/SKILL.md
---
name: Commit-Helper
description: 協助提交相關的各種操作
---

## 核心功能
- 分析檔案變更
- 判斷原子性
- 產生提交訊息
- 執行 git add
- 執行 git commit
- 推送到遠端

問題：
- 一個 skill 包含太多不相關的功能
- 難以重複使用（因為太「大包」了）
- 難以維護（修改一個功能可能影響其他功能）
```

#### 為什麼會發生

- **缺乏單一職責意識**：想把相關的東西都放在一起
- **過度整合**：認為「都是提交相關的，放一起比較方便」
- **沒有考慮重複使用性**：只想到自己目前的需求

#### 正確做法

```markdown
✅ 拆分成多個職責清晰的 skills：

1. `analyze-changes` skill
   - 只負責分析檔案變更
   - 輸入：檔案列表
   - 輸出：變更分類結果

2. `generate-commit-message` skill
   - 只負責產生提交訊息
   - 輸入：變更分類結果
   - 輸出：格式化的提交訊息

3. `validate-atomicity` skill
   - 只負責判斷原子性
   - 輸入：變更分類結果
   - 輸出：原子性判斷結果

然後在 command 中組合這些 skills：
commands/commit-push.md 可以選擇性地使用需要的 skills
```

#### 單一職責原則

> 每個 skill 應該只有**一個明確的職責**，只因為**一個理由**而需要修改。

---

### 4. 缺乏文件（Lack of Documentation）

#### 錯誤示範

```markdown
---
name: Process-Data
description: 處理資料
---

# 處理資料

執行資料處理。

問題：
- 沒有說明輸入是什麼
- 沒有說明輸出是什麼
- 沒有執行步驟
- 其他人（或未來的自己）不知道如何使用
```

#### 為什麼會發生

- **趕時間**：想快速完成功能
- **覺得簡單**：「程式碼就是最好的文件」
- **缺乏同理心**：沒有考慮其他人使用的情況

#### 正確做法

```markdown
---
name: Process-Data
description: 處理和轉換輸入資料，將 JSON 格式轉換為標準化的物件結構
---

# 處理資料

將輸入的 JSON 資料轉換為標準化的物件結構，並進行驗證和清理。

## 核心功能
- 解析 JSON 資料
- 驗證資料格式
- 清理無效欄位
- 標準化欄位名稱
- 返回處理後的物件

## 輸入條件
- JSON 格式的資料字串或檔案路徑
- 必須包含 `id` 和 `name` 欄位
- 可選：`metadata` 欄位

## 執行步驟
1. 讀取輸入資料（字串或檔案）
2. 解析 JSON
3. 驗證必要欄位
4. 清理和標準化
5. 返回處理後的物件

## 輸出結果
- 標準化的物件，包含：
  - `id`: string
  - `name`: string
  - `metadata`: object（可選）

## 使用範例
\`\`\`
輸入：{"id": "123", "Name": "Test", "extra": "data"}
輸出：{"id": "123", "name": "Test"}  （欄位名稱標準化，移除 extra）
\`\`\`
```

#### 文件最低要求

- ✅ 清楚的 description（50-100 字）
- ✅ 核心功能列表
- ✅ 詳細的執行步驟
- ✅ 使用範例（如果邏輯不是顯而易見）

---

## 最佳實踐

### 1. 等待第二次使用（Rule of Three）

#### 原則

```markdown
第 1 次使用 → 直接寫在 command/agent 中
第 2 次使用 → 認真考慮是否要抽取成 skill
第 3 次使用 → 必須抽取成 skill（如果還沒抽的話）
```

#### 為什麼這樣做

**避免過早抽象**：
- 第 1 次：還不知道是否真的需要重複使用
- 第 2 次：開始看到重複模式，可以評估
- 第 3 次：明確的重複，DRY 原則適用

**實際重構時機更明確**：
- 有真實的使用案例可以參考
- 知道不同使用場景的差異
- 可以設計更通用的介面

#### 範例

```markdown
場景：檔案變更分析邏輯

第 1 次：在 git:commit-push 中直接實作
決策：保持簡單，觀察是否有其他需求

第 2 次：git:commit-review 也需要類似邏輯
決策：評估兩個使用場景的相似度
      - 如果 80% 以上相似 → 考慮抽取
      - 如果差異很大 → 各自保持獨立

第 3 次：git:pre-commit-check 也需要
決策：明確的重複模式，必須抽取成 analyze-changes skill
```

---

### 2. 明確的命名（Clear Naming）

#### 好的命名特徵

✅ **描述性**：一看就知道 skill 做什麼

```markdown
✅ analyze-atomicity      # 清楚：分析原子性
✅ generate-commit-message # 清楚：產生提交訊息
✅ resolve-conflict       # 清楚：解決衝突
✅ validate-config        # 清楚：驗證配置
```

✅ **動詞開頭**：強調 skill 的動作

```markdown
✅ analyze-*    # 分析
✅ generate-*   # 產生
✅ validate-*   # 驗證
✅ resolve-*    # 解決
✅ transform-*  # 轉換
```

✅ **簡潔但不失清晰**：

```markdown
✅ parse-json              # 簡潔清楚
❌ parse-json-data-format  # 太冗長
❌ parse                   # 太簡短，不知道解析什麼
```

#### 壞的命名範例

❌ **太抽象**：

```markdown
❌ helper       # 幫什麼忙？
❌ utils        # 什麼工具？
❌ processor    # 處理什麼？
❌ manager      # 管理什麼？
```

❌ **太具體**：

```markdown
❌ analyze-git-commit-atomicity-for-conventional-commits
   # 太長，應該簡化為 analyze-atomicity

❌ validate-json-config-file-format-version-2
   # 太長，應該簡化為 validate-config
```

❌ **不清楚的縮寫**：

```markdown
❌ val-cfg      # 應該寫完整：validate-config
❌ gen-msg      # 應該寫完整：generate-message
❌ proc-data    # 應該寫完整：process-data
```

#### 命名檢查清單

詢問自己：
- [ ] 其他人看到名稱，是否能猜到 70% 的功能？
- [ ] 名稱是否使用了動詞開頭？
- [ ] 名稱是否簡潔（2-4 個單字）？
- [ ] 名稱是否避免了不清楚的縮寫？
- [ ] 名稱是否符合專案的命名規範（kebab-case）？

---

### 3. 完整的文件（Complete Documentation）

#### 必須包含的元素

1. **YAML Front Matter**
   ```yaml
   ---
   name: Skill-Name
   description: 清楚的一句話說明（50-100 字）
   ---
   ```

2. **核心功能**
   ```markdown
   ## 核心功能
   - 列出 3-5 個主要功能
   - 使用簡潔的條列式
   ```

3. **執行步驟**
   ```markdown
   ## 執行步驟

   ### 1. 準備階段
   詳細說明...

   ### 2. 執行階段
   詳細說明...

   ### 3. 完成階段
   詳細說明...
   ```

4. **使用範例**
   ```markdown
   ## 工作流程範例

   提供實際的使用案例，包含：
   - 使用者的輸入
   - Skill 的執行過程
   - 預期的輸出
   ```

#### 建議包含的元素

1. **輸入條件**（如果有特定要求）
   ```markdown
   ## 輸入條件
   - 需要的工具或環境
   - 前置條件
   - 必要的參數
   ```

2. **輸出結果**（如果有明確產出）
   ```markdown
   ## 輸出結果
   - 返回什麼資訊
   - 如何被其他 commands/skills 使用
   ```

3. **注意事項**
   ```markdown
   ## 注意事項

   ### 安全檢查
   - 需要注意的安全問題

   ### 常見錯誤
   - 避免什麼
   - 推薦什麼
   ```

4. **整合其他工具**（如果相關）
   ```markdown
   ## 整合其他工具
   - 可以配合使用的 commands
   - 相關的 skills
   - 建議的工作流程
   ```

#### 文件品質檢查

- [ ] 其他人閱讀文件後，能否獨立使用這個 skill？
- [ ] 文件是否說明了「為什麼」而不只是「怎麼做」？
- [ ] 是否提供了實際的使用範例？
- [ ] 是否說明了邊界情況和錯誤處理？

---

### 4. 測試和驗證（Testing and Validation）

#### 基本測試

在發布 skill 前，至少要測試：

1. **獨立執行**
   ```markdown
   測試：skill 可以被單獨呼叫並正常運作
   方法：創建一個簡單的 command 來測試這個 skill
   ```

2. **整合測試**
   ```markdown
   測試：所有引用這個 skill 的 commands/agents 都能正常運作
   方法：逐一測試每個引用者
   ```

3. **邊界情況**
   ```markdown
   測試：極端輸入、錯誤輸入的處理
   方法：故意提供不正常的輸入，確認錯誤處理
   ```

#### 驗證清單

- [ ] 在至少 2 個使用場景中測試過
- [ ] 測試過正常輸入
- [ ] 測試過異常輸入
- [ ] 確認錯誤訊息清楚易懂
- [ ] 確認文件與實際行為一致

#### 回歸測試

當修改 skill 時：
- [ ] 測試所有引用這個 skill 的地方
- [ ] 確認向後相容性
- [ ] 更新 CHANGELOG 記錄變更
- [ ] 如果有 breaking changes，考慮增加 MAJOR 版本號

---

## 特殊處理

### 1. YAML Front Matter 修改

修改 YAML Front Matter 時要特別小心：

```yaml
---
name: Skill-Name           # 修改這個會影響引用
description: 描述          # 修改這個是安全的
---
```

#### 修改 name 的影響

如果修改 `name` 欄位：
- 所有引用這個 skill 的地方都需要更新
- 考慮使用「搜尋並替換」確保不遺漏
- 在 CHANGELOG 中明確記錄這個變更

#### 正確的修改流程

1. 搜尋所有引用舊名稱的地方
2. 逐一更新引用
3. 更新 skill 的 `name` 欄位
4. 測試所有引用者
5. 更新 CHANGELOG

---

### 2. 大幅度重構

當 skill 需要大幅度重構時：

#### 評估影響範圍

1. **列出所有引用者**
   - Commands
   - Agents
   - 其他 Skills

2. **評估變更影響**
   - 是否會破壞現有功能？
   - 是否需要更新介面？
   - 是否需要遷移指南？

#### 重構策略

**選項 1：原地重構**（適用於小影響）

```markdown
1. 備份當前版本
2. 修改 skill
3. 測試所有引用者
4. 更新 CHANGELOG
```

**選項 2：創建新版本**（適用於大變更）

```markdown
1. 創建新的 skill（如 skill-v2）
2. 保留舊版本一段時間
3. 逐步遷移引用者
4. 在 CHANGELOG 中標記舊版本為 deprecated
5. 一段時間後移除舊版本
```

#### 溝通變更

- 在 CHANGELOG 中詳細說明變更
- 如果是 breaking change，增加 MAJOR 版本號
- 提供遷移指南（如果需要）

---

### 3. 同時修改多個檔案

當修改涉及多個檔案時：

#### 使用 TodoWrite 規劃

```markdown
✅ 使用 TodoWrite 追蹤任務：

Todos:
1. 修改 skill: analyze-changes
2. 更新 command: git:commit-push
3. 更新 command: git:commit-review
4. 更新 README.md
5. 更新 CHANGELOG.md
6. 測試所有變更
```

#### 修改順序

建議的修改順序：

1. **核心檔案**（skills、agents）
2. **引用檔案**（commands）
3. **文件檔案**（README、CHANGELOG）
4. **測試**
5. **提交**

#### 整體確認

修改完成後：
- [ ] 所有檔案的變更是一致的
- [ ] 文件反映了實際行為
- [ ] 測試通過
- [ ] CHANGELOG 記錄完整

---

## 避免這些反模式（Anti-Patterns）

### ❌ 「未來可能用到」症候群

```markdown
錯誤思維：
「這個功能現在只有一個地方用到，但未來可能會有其他地方需要，
 所以我先抽成 skill 好了。」

正確做法：
等到真的有第二個使用場景時再抽取。
```

### ❌ 「什麼都要獨立」症候群

```markdown
錯誤做法：
把每個小功能都抽成獨立的 skill，
結果檔案數量爆炸，反而更難維護。

正確做法：
只有真正需要重複使用或邏輯複雜時才獨立。
```

### ❌ 「複製貼上」症候群

```markdown
錯誤做法：
發現兩個地方有相同的邏輯，
直接複製貼上程式碼。

正確做法：
第二次使用時就應該考慮抽取成 skill。
```

### ❌ 「文件晚點再寫」症候群

```markdown
錯誤想法：
「先把功能寫完，文件晚點有時間再補。」

結果：
文件永遠不會補，因為過一段時間就忘記細節了。

正確做法：
邊寫程式碼邊寫文件，趁記憶猶新時記錄下來。
```

---

## 成功的 Skills 設計模式

### 模式 1：轉換器（Transformer）

**特徵**：
- 輸入一種格式
- 輸出另一種格式
- 職責清晰

**範例**：
```markdown
skills/generate-commit-message/
- 輸入：git diff 結果
- 處理：分析變更、套用格式
- 輸出：Conventional Commits 格式的訊息
```

### 模式 2：驗證器（Validator）

**特徵**：
- 檢查輸入是否符合規範
- 返回驗證結果
- 提供清楚的錯誤訊息

**範例**：
```markdown
skills/validate-atomicity/
- 輸入：變更列表
- 處理：檢查是否符合原子性
- 輸出：通過/不通過 + 原因
```

### 模式 3：工作流程（Workflow）

**特徵**：
- 完整的多步驟流程
- 包含決策點
- 可能與使用者互動

**範例**：
```markdown
skills/resolving-conflict/
- 偵測狀態
- 列出衝突
- 詢問使用者
- 解決衝突
- 完成流程
```

---

## 與其他文件的關聯

- **[SKILL.md](SKILL.md)**：核心判斷標準和設計原則
- **[official-reference.md](official-reference.md)**：官方定義和規範
- **[examples.md](examples.md)**：實際案例中的錯誤和正確做法
- **[implementation.md](implementation.md)**：如何正確實作這些最佳實踐

---

## 總結

### 核心原則

1. **YAGNI**：不要過度設計，等需求明確時再抽取
2. **DRY**：出現重複時才抽取，而不是提前
3. **單一職責**：一個 skill 只做一件事
4. **清晰文件**：完整的說明和範例

### 記住

- ✅ 等待第二次使用再抽取
- ✅ 使用清楚的命名
- ✅ 撰寫完整的文件
- ✅ 充分測試和驗證
- ❌ 不要過早抽象
- ❌ 不要過度細分
- ❌ 不要職責不清
- ❌ 不要缺乏文件

**保持簡單永遠是最好的設計。**

---

**最後更新**：2025-10-19