AgentSkillsCN

skills development

協助設計和開發 Claude Code Skills，提供 skill 設計的思考邏輯和最佳實踐

中文原作
SKILL.md
--- frontmatter
name: skills development
description: 協助設計和開發 Claude Code Skills，提供 skill 設計的思考邏輯和最佳實踐

Skills 設計指南

本指南遵循 Claude Code Skills 官方規範 並整合此 marketplace 專案的最佳實踐。

協助你設計和開發 Claude Code Skills，提供清晰的判斷標準、設計原則和實際案例，確保 skill 的設計符合「可重複使用的工作流程」的核心定位。

📚 文件導覽

本 skill 包含以下文件：

  1. •SKILL.md（本文件）：核心判斷標準和設計原則
  2. •official-reference.md：官方定義、特性和參考資源
  3. •examples.md：實際案例分析和專案範例
  4. •implementation.md：實施指南、檔案結構和命名規範
  5. •best-practices.md：最佳實踐和常見錯誤

建議閱讀順序：

  1. •先閱讀本文件了解核心概念和判斷標準
  2. •查看 official-reference.md 了解官方定義
  3. •閱讀 examples.md 學習實際案例
  4. •使用 implementation.md 進行實作
  5. •參考 best-practices.md 避免常見錯誤

核心概念

什麼是 Skill？

Skill 是 可重複使用的工作流程，定義在 SKILL.md 檔案中，可以在多個 commands、agents 或其他 skills 中被引用和重複使用。

關鍵特性

  • •模組化設計：每個 skill 是獨立的資料夾，包含指令、說明和相關資源
  • •跨平台通用：可在 Claude.ai、API 和 Claude Code 之間共用
  • •動態載入：Claude 會在相關時自動發現和載入 skills
  • •單一定義：設計一次，可在多個地方重複使用

詳細的官方定義請參閱：official-reference.md

判斷標準

何時「需要」獨立成 Skill？

使用以下檢查清單來判斷：

✅ 強烈建議獨立

  1. •

    多處重複使用

    • •有 2 個以上 的 commands/agents 需要使用相同的邏輯
    • •預期未來會有更多地方需要這個功能
  2. •

    邏輯複雜度高

    • •工作流程包含 5 個以上 的步驟
    • •需要複雜的條件判斷或分支邏輯
    • •維護和測試時需要獨立處理
  3. •

    使用者可能單獨呼叫

    • •這個功能本身具有獨立的使用價值
    • •使用者可能只想執行這個特定的工作流程
  4. •

    需要獨立維護和版本控制

    • •這個邏輯的更新頻率較高
    • •需要獨立測試和驗證
    • •多個開發者協作時需要獨立的職責劃分

❌ 不建議獨立

  1. •

    單一使用場景

    • •只在 1 個 command/agent 中使用
    • •未來也不太可能在其他地方重複使用
  2. •

    邏輯簡單

    • •只有 3 個以下 的簡單步驟
    • •沒有複雜的條件判斷
  3. •

    與特定 command 緊密耦合

    • •邏輯與 command 的其他部分緊密相關
    • •獨立出來反而降低可讀性
  4. •

    過度工程化

    • •為了「可能的」未來需求而設計
    • •增加不必要的抽象層次

詳細的案例分析請參閱：examples.md

設計原則

1. YAGNI 原則（You Aren't Gonna Need It）

不要過度設計

❌ 錯誤思維：

「雖然現在只有一個地方用到，但未來可能會用到，所以我先獨立成 skill 好了。」

✅ 正確做法：

「目前只有一個地方使用，先保持簡單。等到第二個地方需要時，再考慮重構成 skill。」

2. DRY 原則（Don't Repeat Yourself）

避免重複邏輯

時機點：

  • •1st 使用 → 直接寫在 command/agent 中
  • •2nd 使用 → 考慮抽取成 skill
  • •3rd 使用 → 必須抽取成 skill

3. 單一職責原則

一個 Skill 只做一件事

✅ 好的設計：

  • •analyze-atomicity: 只負責分析提交的原子性
  • •generate-commit-message: 只負責產生提交訊息
  • •resolve-conflict: 只負責解決 Git 衝突

❌ 不好的設計：

  • •commit-helper: 包含原子性分析、訊息產生、推送等多個功能（職責不清晰，難以重複使用）

4. 清晰的介面設計

明確的輸入和輸出

每個 skill 應該清楚定義：

markdown
## 輸入條件
- 需要哪些前置資訊？
- 依賴哪些工具或環境？

## 執行步驟
1. 步驟 1
2. 步驟 2
3. 步驟 3

## 輸出結果
- 返回什麼資訊？
- 如何被其他 commands/skills 使用？

詳細的實施指南請參閱：implementation.md

決策樹

使用這個決策樹快速判斷：

mermaid
flowchart TD
    Start([開始]) --> Q1{是否有 2+ 個<br/>地方使用？}

    Q1 -->|是| Q2{邏輯是否複雜<br/>5+ 步驟？}
    Q1 -->|否| Q3{邏輯是否非常複雜<br/>10+ 步驟？}

    Q2 -->|是| A1[✅ 強烈建議獨立成 Skill]
    Q2 -->|否| A2[✅ 建議獨立成 Skill<br/>便於維護]

    Q3 -->|是| Q4{使用者是否<br/>可能單獨呼叫？}
    Q3 -->|否| A3[❌ 不需要獨立<br/>遵循 YAGNI 原則]

    Q4 -->|是| A4[✅ 建議獨立<br/>便於測試和使用]
    Q4 -->|否| A5[❌ 暫不獨立<br/>保留重構空間]

    style A1 fill:#90EE90
    style A2 fill:#90EE90
    style A4 fill:#90EE90
    style A3 fill:#FFB6C1
    style A5 fill:#FFB6C1
    style Start fill:#87CEEB

執行步驟

當使用者詢問「是否需要將某個功能獨立成 skill」時，按照以下步驟進行分析：

步驟 1：收集資訊

收集以下資訊（使用 AskUserQuestion 或直接分析）：

  1. •

    目前使用情況

    • •這個功能目前在哪些地方使用？
    • •使用次數是 1 次、2 次還是更多？
  2. •

    未來使用預期

    • •是否已經規劃其他會使用這個功能的 command/agent？
    • •使用者是否明確表達未來的擴展需求？
  3. •

    邏輯複雜度

    • •包含幾個步驟？
    • •是否有複雜的條件判斷或分支邏輯？
  4. •

    獨立使用價值

    • •使用者是否可能單獨執行這個功能？
    • •這個功能是否具有獨立的使用場景？

步驟 2：套用判斷標準

根據「判斷標準」章節的檢查清單進行評估：

markdown
檢查清單：
- [ ] 多處使用？
- [ ] 邏輯複雜？
- [ ] 可獨立呼叫？
- [ ] 需要獨立維護？

評分：勾選 3+ 項 → ✅ 建議獨立
     勾選 1-2 項 → ❓ 視情況決定
     勾選 0 項 → ❌ 不建議獨立

步驟 3：提供建議

根據評估結果，提供清晰的建議：

如果建議獨立

markdown
✅ 建議獨立成 Skill

理由：
1. [列出符合的條件]
2. [說明獨立後的好處]
3. [未來的擴展可能性]

建議的 Skill 設計：
- 名稱：{plugin-name}:{skill-name}
- 位置：plugins/{plugin-name}/skills/{skill-name}/SKILL.md
- 核心功能：[簡述]
- 預期使用者：[列出會使用這個 skill 的 commands/agents]

如果不建議獨立

markdown
❌ 目前不建議獨立成 Skill

理由：
1. [列出不符合的條件]
2. [說明保持現狀的好處]
3. [遵循的設計原則]

建議：
- 保持在 {current-location} 中
- 等到出現第二個使用場景時再考慮重構

未來觸發條件：
[列出什麼情況下應該重新評估]

步驟 4：提供實施計畫（如果建議獨立）

如果決定要獨立成 skill，引導使用者查看詳細的實施計畫：

詳細的實施步驟請參閱：implementation.md

主要步驟：

  1. •創建 Skill 檔案結構
  2. •設計 SKILL.md（YAML Front Matter、內容結構）
  3. •重構現有 Command/Agent（移除重複邏輯、引用新 skill）
  4. •更新文件（README.md、CHANGELOG.md、版本號）

快速參考

常見問題快速解答

問題答案參考文件
第一次使用這個邏輯，要獨立嗎？❌ 不要，遵循 YAGNI 原則best-practices.md
第二次使用，要獨立嗎？✅ 強烈建議獨立examples.md
邏輯很複雜但只用一次？視情況，看是否有獨立價值SKILL.md
如何命名 skill？使用 kebab-case，動詞開頭implementation.md
SKILL.md 必須包含什麼？YAML Front Matter、核心功能、執行步驟implementation.md
可以在 skill 中引用其他 skills 嗎？可以，但要避免循環依賴best-practices.md

設計檢查清單

創建 skill 前快速檢查：

  • • 有 2+ 個使用場景（或邏輯極其複雜）
  • • 職責單一且清晰
  • • 名稱具有描述性
  • • 規劃了完整的文件結構
  • • 考慮了與現有 commands/skills 的整合

總結

設計 Skill 的核心原則：

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

記住：保持簡單永遠是最好的設計。

延伸閱讀

專案相關：