387 lines
12 KiB
Markdown
387 lines
12 KiB
Markdown
# 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
|