gh-mileschou-claude-marketplace-plugins-plugin-dev/skills/skills-development/examples.md

Skills 設計實際案例分析

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

每個案例都包含：

• 背景說明
• 詳細的分析過程
• 決策結論和理由
• 未來的重新評估條件（如果適用）

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

背景

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

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

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

分析過程

使用檢查清單

檢查清單：
- [ ] 多處使用？→ ❌ 只有一處使用（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？

分析過程

使用檢查清單

檢查清單：
- [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：

---
name: Generate-Commit-Message
description: 根據變更內容和專案規範產生提交訊息
---

核心功能：

# 產生提交訊息

## 輸入條件
- 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？

分析過程

使用檢查清單

檢查清單：
- [ ] 多處使用？→ ❌ 只有 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

設計亮點：

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

為何獨立成 skill？

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

學習要點：

• 如何設計清晰的步驟流程
• 如何處理多種情況和分支邏輯
• 如何與使用者互動（AskUserQuestion）

2. Plugin 快速修正

檔案：plugins/plugin-dev/skills/quick-fix/SKILL.md

設計亮點：

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

為何獨立成 skill？

• 特定的使用場景（測試流程中的快速修正）
• 可能在多個測試 commands 中重複使用
• 包含標準化的修正流程

學習要點：

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

3. Skills 設計指南

檔案：plugins/plugin-dev/skills/skills-development/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：核心判斷標準和設計原則
• official-reference.md：官方定義和參考
• implementation.md：如何實作這些案例中決定獨立的 skills
• best-practices.md：避免案例中出現的常見錯誤

---

最後更新：2025-10-19