# Skills 設計實際案例分析

本文件提供實際的 skill 設計案例分析，幫助你理解如何判斷是否需要將功能獨立成 skill。

每個案例都包含：
- 背景說明
- 詳細的分析過程
- 決策結論和理由
- 未來的重新評估條件（如果適用）

## 案例 1：Git 提交原子性判斷

### 背景

在設計 Git 相關的 commands 時，遇到一個問題：

- `git:commit-push` 需要判斷變更是否符合原子性（atomic commits）
- `git:commit-push-all` **明確設計為不考慮**原子性，直接提交所有變更

**問題**：是否應該將「原子性判斷」邏輯獨立成一個 skill？

### 分析過程

#### 使用檢查清單

```markdown
檢查清單：
- [ ] 多處使用？→ ❌ 只有一處使用（commit-push）
- [x] 邏輯複雜？→ ✅ 包含分類、分析等邏輯（7+ 步驟）
- [ ] 可獨立呼叫？→ ❓ 可能有價值，但不確定使用者是否會單獨呼叫
- [ ] 需要獨立維護？→ ❌ 目前沒有這個需求
```

#### 權重評估

| 評估項目 | 現況 | 符合度 |
|---------|------|--------|
| 使用次數 | 1 處 | ❌ 不符合 |
| 複雜度 | 中高（7+ 步驟） | ✅ 符合 |
| 獨立價值 | 不確定 | ❓ 不明確 |
| 未來擴展 | 可能但不確定 | ❓ 不明確 |

**評分**：2 個明確條件中只符合 1 個

### 決策結論

**❌ 目前不需要獨立成 skill**

#### 理由

1. **使用次數不足**
   - 只有 `git:commit-push` 使用
   - `git:commit-push-all` 明確採用不同設計理念（不檢查原子性）
   - 未來是否有其他使用場景不確定

2. **遵循 YAGNI 原則**
   - 不要為「可能的」未來需求過度設計
   - 等到第二個使用場景出現再重構

3. **與 command 緊密耦合**
   - 原子性判斷的邏輯與 commit-push 的流程緊密結合
   - 獨立出來可能降低可讀性

### 未來觸發條件

**何時應該重新評估？**

如果出現以下任一情況，應該考慮將其獨立成 `git:analyze-atomicity` skill：

✅ **觸發重構的條件**：

1. **新增其他 commands 需要這個邏輯**
   - 例如：`git:commit-review` 也需要檢查原子性
   - 例如：`git:pre-commit-check` 需要在提交前驗證

2. **使用者主動要求獨立功能**
   - 使用者想要「只檢查原子性，不提交」的功能
   - 需要將原子性檢查作為獨立的驗證步驟

3. **邏輯變得更複雜**
   - 原子性判斷需要更多步驟和條件
   - 需要獨立測試和驗證

4. **跨 plugin 重複使用**
   - 其他 plugins 也需要類似的原子性判斷邏輯

**那時候再抽取成獨立的 skill 是更好的時機。**

---

## 案例 2：產生 Commit 訊息

### 背景

多個 Git commands 都需要產生符合規範的提交訊息：

- `git:commit-push` 需要產生符合 Conventional Commits 的訊息
- `git:commit-push-all` 也需要產生提交訊息（可能格式略有不同）
- 未來可能有 `git:commit-amend`、`git:commit-fixup` 等 commands

**問題**：是否應該將「產生提交訊息」獨立成一個 skill？

### 分析過程

#### 使用檢查清單

```markdown
檢查清單：
- [x] 多處使用？→ ✅ 2 處以上，未來可能更多
- [x] 邏輯複雜？→ ✅ 需要分析變更、套用格式規範（5+ 步驟）
- [x] 可獨立呼叫？→ ✅ 使用者可能想「預覽提交訊息」而不實際提交
- [x] 需要獨立維護？→ ✅ 格式規範（如 Conventional Commits）可能會調整
```

#### 權重評估

| 評估項目 | 現況 | 符合度 |
|---------|------|--------|
| 使用次數 | 2+ 處，未來更多 | ✅ 符合 |
| 複雜度 | 中（5+ 步驟） | ✅ 符合 |
| 獨立價值 | 高（預覽訊息） | ✅ 符合 |
| 未來擴展 | 確定會擴展 | ✅ 符合 |

**評分**：4 個條件全部符合 ✅

### 決策結論

**✅ 應該獨立成 skill**

#### 理由

1. **多處重複使用**
   - 至少 2 個 commands 需要
   - 未來明確會有更多使用場景

2. **邏輯複雜且需要獨立維護**
   - 需要分析 git diff
   - 套用 Conventional Commits 格式
   - 可能需要支援不同的訊息格式

3. **具有獨立使用價值**
   - 使用者可能想「預覽提交訊息」
   - 可以作為提交前的檢查步驟

4. **便於測試和維護**
   - 提交訊息格式可能會調整
   - 獨立 skill 便於集中管理和測試

### 建議的 Skill 設計

**Skill 名稱**：`git:generate-commit-message`

**位置**：`plugins/git/skills/generate-commit-message/SKILL.md`

**YAML Front Matter**：
```yaml
---
name: Generate-Commit-Message
description: 根據變更內容和專案規範產生提交訊息
---
```

**核心功能**：

```markdown
# 產生提交訊息

## 輸入條件
- Git 變更的詳細資訊（通過 git diff 獲取）
- 專案的提交訊息格式偏好（預設 Conventional Commits）
- 可選：現有的 commit history 來學習風格

## 執行步驟
1. 分析變更內容和類型（新增、修改、修正等）
2. 識別影響範圍（scope）
3. 產生簡短描述（subject line）
4. 產生詳細說明（body）
5. 套用格式規範（Conventional Commits 或自訂格式）
6. 加入 co-author 資訊（如果是 AI 協助）

## 輸出結果
- 格式化的提交訊息文字
- 可以直接用於 `git commit -m`
```

**預期使用者**：
- `git:commit-push`
- `git:commit-push-all`
- 未來的 `git:commit-amend`
- 未來的 `git:commit-review`

---

## 案例 3：檔案變更分類

### 背景

在 `git:commit-push` 的實作中，需要將變更的檔案按類型分類：

- 依照 Conventional Commits 的類型（feat, fix, docs, style 等）
- 分析檔案路徑和變更內容
- 決定這些變更屬於哪個類別

**問題**：是否應該將「檔案變更分類」獨立成一個 skill？

### 分析過程

#### 使用檢查清單

```markdown
檢查清單：
- [ ] 多處使用？→ ❌ 只有 commit-push 使用
- [x] 邏輯複雜？→ ✅ 需要分析檔案路徑、內容變更（中等複雜度）
- [ ] 可獨立呼叫？→ ❓ 單獨分類檔案的使用場景不明確
- [ ] 需要獨立維護？→ ❌ 目前沒有獨立維護的需求
```

#### 權重評估

| 評估項目 | 現況 | 符合度 |
|---------|------|--------|
| 使用次數 | 1 處 | ❌ 不符合 |
| 複雜度 | 中 | ✅ 符合 |
| 獨立價值 | 低 | ❌ 不符合 |
| 未來擴展 | 不確定 | ❓ 不明確 |

**評分**：4 個條件中只符合 1 個

### 決策結論

**❌ 目前不需要獨立成 skill**

#### 理由

1. **遵循 YAGNI 原則**
   - 只有一個使用場景
   - 沒有明確的第二個使用需求

2. **與 command 緊密耦合**
   - 檔案分類邏輯與 commit-push 的提交流程緊密結合
   - 分類的結果直接用於產生提交訊息
   - 獨立出來反而降低程式碼的連貫性

3. **獨立價值不明確**
   - 使用者很少會只想「分類檔案」而不做其他操作
   - 沒有明確的獨立使用場景

### 建議做法

**保持在 `git:commit-push` 的 command 檔案中**

- 作為 command 的內部邏輯步驟
- 保持程式碼的可讀性和連貫性
- 如果未來出現第二個使用場景，再考慮重構

---

## 專案中的實際 Skills 範例

本專案已經有幾個設計良好的 skills，可以作為參考：

### 1. Git 衝突解決

**檔案**：[`plugins/git/skills/resolving-conflict/SKILL.md`](../../../git/skills/resolving-conflict/SKILL.md)

**設計亮點**：
- ✅ **明確的使用場景**：rebase 和 merge 衝突解決
- ✅ **清晰的執行步驟**：偵測狀態 → 列出衝突 → 解決 → 完成流程
- ✅ **詳細的工作流程範例**：包含使用者互動的完整流程
- ✅ **特殊情況處理**：二進位檔案、檔案刪除衝突等

**為何獨立成 skill？**
- 可能在多個 commands 中使用（`git:resolve-conflict`、`git:rebase`、`git:merge` 等）
- 邏輯複雜，包含多種衝突類型的處理
- 具有獨立使用價值（使用者可能單獨執行衝突解決）

**學習要點**：
- 如何設計清晰的步驟流程
- 如何處理多種情況和分支邏輯
- 如何與使用者互動（AskUserQuestion）

### 2. Plugin 快速修正

**檔案**：[`plugins/plugin-dev/skills/quick-fix/SKILL.md`](../test/plugin-dev/quick-fix/SKILL.md)

**設計亮點**：
- ✅ **單一職責**：專注於快速修正測試中的問題
- ✅ **明確的輸入條件**：測試中的 plugin 和使用者回饋
- ✅ **詳細的注意事項**：YAML Front Matter 處理、格式檢查等
- ✅ **整合其他工具**：說明如何與其他檔案配合

**為何獨立成 skill？**
- 特定的使用場景（測試流程中的快速修正）
- 可能在多個測試 commands 中重複使用
- 包含標準化的修正流程

**學習要點**：
- 如何設計針對特定場景的 skill
- 如何處理檔案讀取、修改、驗證的流程
- 如何保持與專案規範的一致性

### 3. Skills 設計指南

**檔案**：[`plugins/plugin-dev/skills/skills-development/SKILL.md`](SKILL.md)

**設計亮點**：
- ✅ **元 skill**：幫助設計其他 skills 的 skill
- ✅ **完整的決策框架**：判斷標準、設計原則、決策樹
- ✅ **豐富的案例**：包含本文件的所有案例分析
- ✅ **模組化文件**：拆分成多個文件便於維護

**為何獨立成 skill？**
- 在開發多個 plugins 時會重複使用
- 提供標準化的設計流程
- 需要獨立維護和更新

**學習要點**：
- 如何設計指導性的 skill
- 如何提供決策支援
- 如何組織複雜的文件結構

---

## 案例對照表

快速對照這三個案例的決策：

| 案例 | 使用次數 | 複雜度 | 獨立價值 | 決策 | 主要理由 |
|------|---------|--------|----------|------|---------|
| **Git 原子性判斷** | 1 處 | 高 | 不確定 | ❌ 不獨立 | YAGNI 原則，等第二個使用場景 |
| **產生 Commit 訊息** | 2+ 處 | 中 | 高 | ✅ 獨立 | 多處使用 + 獨立價值 + 需要維護 |
| **檔案變更分類** | 1 處 | 中 | 低 | ❌ 不獨立 | 與 command 緊密耦合，獨立價值低 |

---

## 案例分析的關鍵思考

### 1. 不要被複雜度迷惑

❌ **錯誤思維**：
> 「這個邏輯很複雜（5+ 步驟），應該獨立成 skill。」

✅ **正確思維**：
> 「雖然複雜，但只有一個使用場景，而且與現有 command 緊密耦合，應該保持在一起。複雜度只是判斷因素之一，不是唯一條件。」

### 2. 重視「使用次數」的權重

使用次數是**最重要的判斷標準**：
- 1 次使用 → 幾乎不需要獨立（除非極特殊情況）
- 2 次使用 → 強烈建議獨立
- 3+ 次使用 → 必須獨立

### 3. 「獨立價值」的判斷

**有獨立價值**：
- 使用者可能單獨呼叫這個功能
- 可以作為其他工作流程的一部分
- 本身就是一個完整的任務

**沒有獨立價值**：
- 只作為更大流程的中間步驟
- 離開原本的 context 就沒有意義
- 使用者不會單獨執行

### 4. 未來導向 vs. 當前需求

✅ **好的未來導向**：
- 「已經有 2 個使用場景，未來可能有第 3、4 個」→ 獨立
- 「有明確的擴展計畫，第 2 個使用場景正在開發中」→ 可以考慮獨立

❌ **過度的未來導向**：
- 「雖然現在只有 1 個使用場景，但未來可能會有」→ 不獨立（YAGNI）
- 「為了靈活性和可擴展性先獨立」→ 過度工程化

---

## 與其他文件的關聯

- **[SKILL.md](SKILL.md)**：核心判斷標準和設計原則
- **[official-reference.md](official-reference.md)**：官方定義和參考
- **[implementation.md](implementation.md)**：如何實作這些案例中決定獨立的 skills
- **[best-practices.md](best-practices.md)**：避免案例中出現的常見錯誤

---

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