commit 7c88e7d08d6c706a3627debce4c305e6503f184c Author: Zhongwei Li Date: Sun Nov 30 08:40:34 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..6dc5f5c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "plugin-dev", + "description": "Plugin development tools", + "version": "0.1.0", + "author": { + "name": "Miles Chou" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..ac24ffd --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# plugin-dev + +Plugin development tools diff --git a/commands/create-skill.md b/commands/create-skill.md new file mode 100644 index 0000000..78dc69d --- /dev/null +++ b/commands/create-skill.md @@ -0,0 +1,461 @@ +--- +description: Create Skill +argument-hint: [技能描述] +allowed-tools: Read,Write,Edit,Bash(mkdir:*),AskUserQuestion +--- + +# 建立新的 Skill + +協助你從構思到實作，建立一個符合最佳實踐的 Claude Code Skill。 + +## 參數說明 + +接收一個可選的技能描述參數： + +``` +/plugin-dev:create-skill [技能描述] +``` + +- 如果有提供描述，直接進入設計流程 +- 如果沒有提供，先詢問使用者想要建立什麼 skill + +## 執行流程 + +### 步驟 1：收集需求 + +#### 1-1. 取得技能描述 + +如果使用者沒有提供描述，使用 AskUserQuestion 詢問： + +**問題**：你想建立什麼樣的 Skill？ +- 請描述這個 skill 的主要功能 +- 它會在什麼場景下使用？ + +#### 1-2. 收集基本資訊 + +詢問以下資訊（使用一次 AskUserQuestion 同時詢問）： + +1. **所屬 Plugin**：這個 skill 屬於哪個 plugin？ + - 提供當前可用的 plugins 清單作為選項 + - 允許使用者輸入新的 plugin 名稱 + +2. **使用場景**： + - 目前有哪些地方會使用這個 skill？ + - 預期未來會在哪些地方使用？ + +3. **邏輯複雜度**： + - 大概需要幾個步驟？（簡單 3-5、中等 5-10、複雜 10+） + +### 步驟 2：套用設計原則 + +**引用 `plugin-dev:skills-development` 的判斷標準** + +根據收集到的資訊，評估是否符合 skill 的定位： + +#### 檢查清單 + +```markdown +- [ ] 多處使用？（2+ 個地方） +- [ ] 邏輯複雜？（5+ 個步驟） +- [ ] 可獨立呼叫？（使用者可能單獨執行） +- [ ] 需要獨立維護？（邏輯會經常更新） +``` + +#### 評估結果 + +**符合 3+ 項**：✅ 適合建立 Skill，繼續流程 + +**符合 1-2 項**：❓ 提供建議 +```markdown +根據 YAGNI 原則，這個功能可能更適合： +- Command：如果使用者需要直接呼叫 +- 直接寫在現有的 Command/Agent 中：如果只在一個地方使用 + +是否仍要繼續建立 Skill？ +``` + +**符合 0 項**：❌ 不建議建立 Skill +```markdown +這個功能不符合 Skill 的定位，建議： +1. 如果使用者需要直接呼叫 → 建立 Command +2. 如果需要複雜互動 → 建立 Agent +3. 如果邏輯簡單 → 直接寫在現有檔案中 + +提供替代方案建議。 +``` + +### 步驟 3：設計 Skill 結構 + +如果確定要建立 skill，開始設計細節： + +#### 3-1. 確認命名 + +**Skill 名稱**（使用 kebab-case）： +- 清楚描述功能 +- 遵循 `{功能動詞}-{對象}` 格式 +- 範例：`analyze-atomicity`、`generate-commit-message` + +**YAML Front Matter 名稱**（使用 PascalCase 或自然語言）： +- 範例：`Analyze Atomicity`、`Generate Commit Message` + +**Description**（一句話說明）： +- 簡潔明瞭，50 字以內 +- 說明核心功能和使用場景 + +#### 3-2. 設計輸入輸出 + +**輸入條件**： +- 需要哪些前置資訊？ +- 依賴哪些工具或環境？ +- 有什麼前提條件？ + +**輸出結果**： +- 返回什麼資訊？ +- 如何被其他 commands/skills 使用？ +- 會產生哪些副作用（如建立檔案、修改狀態）？ + +#### 3-3. 規劃執行步驟 + +將工作流程分解成清晰的步驟： + +```markdown +## 執行步驟 + +### 步驟 1：[第一個階段] +- 子步驟 1-1 +- 子步驟 1-2 + +### 步驟 2：[第二個階段] +- 子步驟 2-1 +- 子步驟 2-2 + +### 步驟 N：[最後階段] +- 完成並輸出結果 +``` + +**注意事項**： +- 每個步驟應該有明確的目標 +- 步驟之間的依賴關係要清楚 +- 包含錯誤處理的說明 + +#### 3-4. 提供使用範例 + +設計實際的使用場景和範例： + +```markdown +## 使用範例 + +### 場景 1：[典型使用情況] +[描述場景和範例程式碼] + +### 場景 2：[特殊情況] +[描述場景和範例程式碼] +``` + +### 步驟 4：確認設計 + +在產生檔案前，向使用者確認完整的設計： + +```markdown +## Skill 設計摘要 + +**Plugin**：{plugin-name} +**Skill 名稱**：{skill-name} +**描述**：{description} + +**輸入條件**： +- [列出輸入項目] + +**執行步驟**： +1. [步驟 1] +2. [步驟 2] +... + +**輸出結果**： +- [列出輸出項目] + +**使用場景**： +- [場景 1] +- [場景 2] + +確認以上設計無誤？ +``` + +使用 AskUserQuestion 確認，如果使用者提出修改意見，調整設計後再次確認。 + +### 步驟 5：產生檔案 + +#### 5-1. 建立目錄結構 + +```bash +mkdir -p plugins/{plugin-name}/skills/{skill-name} +``` + +#### 5-2. 產生 SKILL.md + +使用 Write tool 建立 `plugins/{plugin-name}/skills/{skill-name}/SKILL.md`： + +```yaml +--- +name: {Skill Name} +description: {簡短描述} +--- + +# {Skill 標題} + +{詳細說明這個 skill 的功能和目的} + +## 核心功能 + +- {功能點 1} +- {功能點 2} +- {功能點 3} + +## 輸入條件 + +- {前置條件 1} +- {前置條件 2} + +## 執行步驟 + +### 步驟 1：{步驟名稱} + +{詳細說明} + +### 步驟 2：{步驟名稱} + +{詳細說明} + +## 輸出結果 + +- {輸出項目 1} +- {輸出項目 2} + +## 使用範例 + +### 場景 1：{場景名稱} + +{範例說明} + +## 注意事項 + +- {注意事項 1} +- {注意事項 2} +``` + +**重要**： +- 檔案結尾要留一個空行 +- YAML Front Matter 格式要正確 +- Markdown 格式要規範 + +#### 5-3. 確認檔案已建立 + +使用 Read tool 讀取剛建立的 SKILL.md，確認內容正確。 + +### 步驟 6：更新文件 + +#### 6-1. 更新 README.md + +讀取 `plugins/{plugin-name}/README.md`，在 Skills 清單中加入新的 skill： + +```markdown +### `{plugin-name}:{skill-name}` + +{description} + +**功能特點：** + +- {特點 1} +- {特點 2} + +**適用場景：** + +- {場景 1} +- {場景 2} + +**使用方式：** + +{簡要的使用說明} +``` + +#### 6-2. 更新 CHANGELOG.md + +讀取 `plugins/{plugin-name}/CHANGELOG.md`，在 `[Unreleased]` 區段的 `### Added` 下加入： + +```markdown +- 新增 `{plugin-name}:{skill-name}` Skill + - {功能說明 1} + - {功能說明 2} + - {功能說明 3} +``` + +如果 `[Unreleased]` 區段不存在，創建它。 +如果 `### Added` 區段不存在，創建它。 + +### 步驟 7：總結並提供後續建議 + +完成後向使用者報告： + +```markdown +✅ Skill 建立完成！ + +**檔案位置**： +- SKILL.md: plugins/{plugin-name}/skills/{skill-name}/SKILL.md +- README.md: 已更新 +- CHANGELOG.md: 已更新 + +**後續步驟建議**： + +1. 測試 Skill + - 在實際場景中使用這個 skill + - 確認執行步驟是否清晰 + - 驗證輸入輸出是否符合預期 + +2. 更新引用 + - 在需要使用這個 skill 的 commands/agents 中加入引用 + - 移除重複的邏輯程式碼 + +3. 版本管理 + - 如果這是重要更新，考慮更新 plugin 版本號 + - 在 CHANGELOG.md 中補充更詳細的說明 + +4. 文件完善 + - 根據實際使用情況補充更多範例 + - 加入常見問題和注意事項 +``` + +## 設計原則提醒 + +在整個流程中，持續提醒並應用以下原則： + +### YAGNI（You Aren't Gonna Need It） +- 不要為「可能的」未來需求過度設計 +- 保持簡單，專注於當前的實際需求 + +### DRY（Don't Repeat Yourself） +- 確保這個 skill 真的能避免重複 +- 如果只有一個使用場景，考慮延後創建 + +### 單一職責原則 +- 一個 skill 只做一件事 +- 職責要清晰明確 + +### 清晰介面 +- 輸入輸出要明確 +- 文件要完整清楚 + +## 特殊情況處理 + +### 情況 1：Plugin 不存在 + +如果使用者指定的 plugin 不存在，詢問： + +```markdown +Plugin `{plugin-name}` 不存在。 + +你想要： +1. 建立新的 plugin `{plugin-name}`？ +2. 選擇其他現有的 plugin？ +``` + +如果選擇建立新 plugin，提示： +```markdown +建立新 plugin 需要： +- .claude-plugin/plugin.json +- README.md +- CHANGELOG.md + +建議先使用其他工具建立 plugin，再回來建立 skill。 +或者我可以協助你建立基本的 plugin 結構？ +``` + +### 情況 2：Skill 已存在 + +如果 skill 已經存在，詢問： + +```markdown +Skill `{plugin-name}:{skill-name}` 已存在。 + +你想要： +1. 覆蓋現有的 skill（會備份舊版本） +2. 使用不同的名稱 +3. 取消操作 +``` + +### 情況 3：使用者提出的功能不適合 Skill + +根據評估結果，提供替代建議： + +**建議建立 Command：** +```markdown +這個功能更適合建立 Command，因為： +- [列出理由] + +Command 的優點： +- 使用者可以直接呼叫（/plugin-name:command-name） +- 輕量快速 +- 適合工具型功能 + +要改為建立 Command 嗎？ +``` + +**建議建立 Agent：** +```markdown +這個功能更適合建立 Agent，因為： +- [列出理由] + +Agent 的優點： +- 可以深入分析和思考 +- 支援複雜的多輪互動 +- 適合需要專業判斷的場景 + +要改為建立 Agent 嗎？ +``` + +## 錯誤處理 + +### 檔案操作錯誤 + +如果建立檔案失敗： +```markdown +❌ 建立檔案時發生錯誤：{錯誤訊息} + +可能的原因： +- 權限不足 +- 路徑不存在 +- 檔案名稱不合法 + +請檢查並重試。 +``` + +### 格式錯誤 + +如果 YAML Front Matter 格式錯誤： +```markdown +⚠️ 檢測到格式問題： + +- YAML Front Matter 缺少 `---` 分隔線 +- name 或 description 欄位缺失 + +已自動修正格式。 +``` + +## 品質檢查清單 + +在完成前確認： + +- [ ] SKILL.md 的 YAML Front Matter 格式正確 +- [ ] 檔案結尾有空行 +- [ ] Markdown 格式規範（標題、列表、程式碼區塊） +- [ ] 輸入輸出說明清楚 +- [ ] 執行步驟完整且有邏輯順序 +- [ ] 至少有一個使用範例 +- [ ] README.md 已更新 +- [ ] CHANGELOG.md 已更新 +- [ ] 檔案路徑和命名符合規範 + +## 參考資源 + +- 設計原則：參考 `plugin-dev:skills-development` skill +- 檔案結構：參考專案 CLAUDE.md 中的目錄結構說明 +- 版本管理：參考 CLAUDE.md 中的版本管理規範 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..9bb422d --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:MilesChou/claude-marketplace:plugins/plugin-dev", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "c3a0ca93959360fd75032bf2306259447010d297", + "treeHash": "5c87399d4fd780f490dbe970c1f0e6776520908d9f79f61e8639c4cc965ffd94", + "generatedAt": "2025-11-28T10:12:08.027242Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "plugin-dev", + "description": "Plugin development tools", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "93c9c804f1f44bc0fb71d818030e862e4d57fb9481a2030ddcd1e70fcf81de93" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "12d546603fe5afacc4fd49056523d3be44d320341438ac449fc637ceac762b88" + }, + { + "path": "commands/create-skill.md", + "sha256": "87f0b3cebdd3fac721824fe3aaf13e869943e14fd2c576a46791c686cc8a9c4a" + }, + { + "path": "skills/skills-development/implementation.md", + "sha256": "07d1701a3b395b74ea1ef9c49fbe8da63e8c6435f1037a0ca7b8d049bd5e7e7e" + }, + { + "path": "skills/skills-development/examples.md", + "sha256": "5b4c3104ed44ac977ff9e6fdd4d7a84efee20fa0e82b11ea52a3e6204633cc59" + }, + { + "path": "skills/skills-development/best-practices.md", + "sha256": "9726760e988775476841bf347724bfff0168adfb9a7c5b8bd9742fe3002455b5" + }, + { + "path": "skills/skills-development/official-reference.md", + "sha256": "9bce06e793cd77ee7718624326ce0d7190a1a67d3d311082be9b93bd99cb86fc" + }, + { + "path": "skills/skills-development/SKILL.md", + "sha256": "2c27a2dccb0bcb7fa21a652496d6ff529d417f37d19480ae7e413a92f770d193" + }, + { + "path": "skills/quick-fix/SKILL.md", + "sha256": "2b627ca9a2bf10523cad699165d7125d8d6115574583c1869483bce8314c3003" + } + ], + "dirSha256": "5c87399d4fd780f490dbe970c1f0e6776520908d9f79f61e8639c4cc965ffd94" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/quick-fix/SKILL.md b/skills/quick-fix/SKILL.md new file mode 100644 index 0000000..81479c4 --- /dev/null +++ b/skills/quick-fix/SKILL.md @@ -0,0 +1,220 @@ +--- +name: quick-fix +description: 當使用 test 開頭的 command、skill、agent 時，在執行過程中使用者提出改善建議，立即調整 .claude 目錄中對應的 md 檔案 +--- + +# Plugin 快速修正 + +當使用 test 開頭的 command、skill、agent 進行測試時，若使用者提出改善建議，立即定位並調整 `.claude` 目錄中對應的 md 檔案。 + +## 核心功能 + +- 快速識別當前測試的 plugin 和相關檔案 +- 根據使用者回饋定位需要修改的 md 檔案 +- 立即進行修正並驗證 +- 提供修改前後的對比說明 + +## 執行步驟 + +### 1. 確認測試中的 Plugin + +當使用者在測試過程中提出改善觀點時： + +1. **識別目標 Plugin** + - 從對話脈絡中確認正在測試的 plugin 名稱 + - 如果不明確，使用 AskUserQuestion 詢問： + - 正在測試哪個 plugin？ + - 是測試 agent、command 還是 skill？ + - 具體是哪個檔案？ + +2. **定位目標檔案** + - Agent: `plugins/{plugin-name}/agents/{agent-name}.md` + - Command: `plugins/{plugin-name}/commands/{command-name}.md` + - Skill: `plugins/{plugin-name}/skills/{skill-name}/SKILL.md` + +### 2. 讀取並分析當前內容 + +1. **使用 Read tool 讀取目標檔案** + ``` + Read: plugins/{plugin-name}/{type}/{name}/檔案.md + ``` + +2. **分析使用者的改善觀點** + - 理解使用者反映的問題點 + - 確認需要修改的具體區塊 + - 思考最佳的修改方式 + +3. **確認修改範圍** + - 如果使用者的意見很明確，直接進行修改 + - 如果需要澄清，使用 AskUserQuestion 確認： + - 具體要修改哪個章節？ + - 要新增內容還是修改現有內容？ + - 修改的幅度如何？ + +### 3. 執行修改 + +1. **使用 Edit tool 進行修改** + - 精確定位需要修改的區塊 + - 使用 old_string 和 new_string 進行替換 + - 保持檔案格式的一致性（YAML Front Matter、Markdown 格式） + +2. **注意事項** + - 保持 YAML Front Matter 的完整性 + - 維持原有的文件結構 + - 確保修改後的內容符合 Markdown 格式 + - 檔案結尾保留一個空行 + +3. **多處修改** + - 如果需要修改多處，一次性處理 + - 保持修改的邏輯一致性 + +### 4. 驗證與確認 + +1. **重新讀取檔案** + - 使用 Read tool 確認修改結果 + - 檢查是否有格式錯誤 + +2. **向使用者說明修改內容** + - 清楚說明修改了哪些部分 + - 解釋修改的理由和預期效果 + - 提供修改前後的對比（如果必要） + +3. **詢問是否需要繼續測試** + - 確認使用者是否滿意修改 + - 是否需要再次測試功能 + - 是否還有其他需要調整的地方 + +## 使用場景 + +### 適用情境 + +1. **測試 Agent 時** + - Agent 的提示詞不夠明確 + - Agent 的執行步驟需要調整 + - Agent 的範例需要更新 + +2. **測試 Command 時** + - Command 的說明不清楚 + - Command 的參數說明需要補充 + - Command 的執行邏輯需要修正 + +3. **測試 Skill 時** + - Skill 的工作流程需要優化 + - Skill 的注意事項需要補充 + - Skill 的範例需要修正 + +### 典型工作流程 + +``` +[使用者正在測試某個 skill] + +User: 我發現這個 skill 的步驟 3 說明不夠清楚， + 應該要先執行 git status 再決定要用哪個策略。 + +Agent: 我會立即修正這個 skill 的 SKILL.md 檔案。 + +[使用 Read tool 讀取當前的 SKILL.md] +[使用 Edit tool 修改步驟 3 的內容] + +Agent: 已修改 plugins/git/skills/resolving-conflict/SKILL.md:42 + - 在步驟 3 開頭新增「先執行 git status 確認狀態」的說明 + - 補充不同狀態下的處理策略 + + 修改內容： + 原本：「對於每個衝突的檔案...」 + 修改後：「先執行 git status 確認衝突狀態，再對於每個衝突的檔案...」 + + 你要繼續測試看看嗎？ + +User: 好的，再測試一次。 + +[繼續測試流程...] +``` + +## 特殊處理 + +### YAML Front Matter 修改 + +如果需要修改 YAML Front Matter（name 或 description）： + +```yaml +--- +name: 原始名稱 +description: 原始描述 +--- +``` + +修改時要特別注意： +- 保持 `---` 分隔線的完整性 +- name 使用 PascalCase 或 kebab-case +- description 簡潔明瞭，說明核心功能 + +### 大幅度重構 + +如果使用者的改善意見需要大幅度重構： + +1. **使用 AskUserQuestion 確認範圍** + - 列出需要調整的主要區塊 + - 確認是否需要重新組織結構 + - 是否影響其他相關檔案 + +2. **分步驟進行** + - 先調整結構性的內容 + - 再補充細節說明 + - 最後更新範例 + +3. **保持溝通** + - 每個大區塊修改後向使用者確認 + - 確保修改方向符合使用者期望 + +### 同時修改多個檔案 + +如果改善意見涉及多個檔案（例如 SKILL.md 和 README.md）： + +1. **使用 TodoWrite 規劃任務** + - 列出所有需要修改的檔案 + - 標示修改的優先順序 + +2. **按順序執行** + - 先修改核心檔案（agent 的 .md、command 的 .md、SKILL.md 等） + - 再更新文件檔案（README.md） + +3. **整體確認** + - 所有修改完成後，整體說明變更 + - 確保檔案間的一致性 + +## 注意事項 + +### 修改原則 + +- **快速響應**：立即處理使用者的改善意見，不要拖延 +- **精確定位**：準確找到需要修改的區塊，避免影響其他內容 +- **保持格式**：維持原有的檔案格式和結構 +- **清楚溝通**：說明修改的內容和理由 + +### 常見錯誤 + +**避免：** +- 在不確定的情況下猜測使用者的意圖 +- 修改過度，超出使用者的要求 +- 破壞檔案的原有結構 +- 修改後沒有向使用者確認 + +**推薦：** +- 不確定時使用 AskUserQuestion 確認 +- 只修改使用者明確提出的部分 +- 保持檔案結構的完整性 +- 修改後清楚說明變更內容 + +### 品質檢查 + +修改完成後檢查： +- [ ] YAML Front Matter 格式正確 +- [ ] Markdown 格式正確 +- [ ] 檔案結尾有空行 +- [ ] 內容邏輯清晰 +- [ ] 符合使用者的改善意見 + +## 整合其他工具 + +- 如果修改涉及 README.md，確保與 plugin 的實際功能一致 diff --git a/skills/skills-development/SKILL.md b/skills/skills-development/SKILL.md new file mode 100644 index 0000000..da473c7 --- /dev/null +++ b/skills/skills-development/SKILL.md @@ -0,0 +1,327 @@ +--- +name: skills development +description: 協助設計和開發 Claude Code Skills，提供 skill 設計的思考邏輯和最佳實踐 +--- + +# Skills 設計指南 + +> 本指南遵循 [Claude Code Skills 官方規範](https://docs.claude.com/en/docs/claude-code/skills) +> 並整合此 marketplace 專案的最佳實踐。 + +協助你設計和開發 Claude Code Skills，提供清晰的判斷標準、設計原則和實際案例，確保 skill 的設計符合「可重複使用的工作流程」的核心定位。 + +## 📚 文件導覽 + +本 skill 包含以下文件： + +1. **[SKILL.md](SKILL.md)**（本文件）：核心判斷標準和設計原則 +2. **[official-reference.md](official-reference.md)**：官方定義、特性和參考資源 +3. **[examples.md](examples.md)**：實際案例分析和專案範例 +4. **[implementation.md](implementation.md)**：實施指南、檔案結構和命名規範 +5. **[best-practices.md](best-practices.md)**：最佳實踐和常見錯誤 + +**建議閱讀順序**： +1. 先閱讀本文件了解核心概念和判斷標準 +2. 查看 [official-reference.md](official-reference.md) 了解官方定義 +3. 閱讀 [examples.md](examples.md) 學習實際案例 +4. 使用 [implementation.md](implementation.md) 進行實作 +5. 參考 [best-practices.md](best-practices.md) 避免常見錯誤 + +--- + +## 核心概念 + +### 什麼是 Skill？ + +Skill 是 **可重複使用的工作流程**，定義在 `SKILL.md` 檔案中，可以在多個 commands、agents 或其他 skills 中被引用和重複使用。 + +#### 關鍵特性 + +- **模組化設計**：每個 skill 是獨立的資料夾，包含指令、說明和相關資源 +- **跨平台通用**：可在 Claude.ai、API 和 Claude Code 之間共用 +- **動態載入**：Claude 會在相關時自動發現和載入 skills +- **單一定義**：設計一次，可在多個地方重複使用 + +> 詳細的官方定義請參閱：[official-reference.md](official-reference.md) + +--- + +## 判斷標準 + +### 何時「需要」獨立成 Skill？ + +使用以下檢查清單來判斷： + +#### ✅ 強烈建議獨立 + +1. **多處重複使用** + - 有 **2 個以上** 的 commands/agents 需要使用相同的邏輯 + - 預期未來會有更多地方需要這個功能 + +2. **邏輯複雜度高** + - 工作流程包含 **5 個以上** 的步驟 + - 需要複雜的條件判斷或分支邏輯 + - 維護和測試時需要獨立處理 + +3. **使用者可能單獨呼叫** + - 這個功能本身具有獨立的使用價值 + - 使用者可能只想執行這個特定的工作流程 + +4. **需要獨立維護和版本控制** + - 這個邏輯的更新頻率較高 + - 需要獨立測試和驗證 + - 多個開發者協作時需要獨立的職責劃分 + +#### ❌ 不建議獨立 + +1. **單一使用場景** + - 只在 **1 個** command/agent 中使用 + - 未來也不太可能在其他地方重複使用 + +2. **邏輯簡單** + - 只有 **3 個以下** 的簡單步驟 + - 沒有複雜的條件判斷 + +3. **與特定 command 緊密耦合** + - 邏輯與 command 的其他部分緊密相關 + - 獨立出來反而降低可讀性 + +4. **過度工程化** + - 為了「可能的」未來需求而設計 + - 增加不必要的抽象層次 + +> 詳細的案例分析請參閱：[examples.md](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](implementation.md) + +--- + +## 決策樹 + +使用這個決策樹快速判斷： + +```mermaid +flowchart TD + Start([開始]) --> Q1{是否有 2+ 個
地方使用？} + + Q1 -->|是| Q2{邏輯是否複雜
5+ 步驟？} + Q1 -->|否| Q3{邏輯是否非常複雜
10+ 步驟？} + + Q2 -->|是| A1[✅ 強烈建議獨立成 Skill] + Q2 -->|否| A2[✅ 建議獨立成 Skill
便於維護] + + Q3 -->|是| Q4{使用者是否
可能單獨呼叫？} + Q3 -->|否| A3[❌ 不需要獨立
遵循 YAGNI 原則] + + Q4 -->|是| A4[✅ 建議獨立
便於測試和使用] + Q4 -->|否| A5[❌ 暫不獨立
保留重構空間] + + 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](implementation.md) + +主要步驟： +1. 創建 Skill 檔案結構 +2. 設計 SKILL.md（YAML Front Matter、內容結構） +3. 重構現有 Command/Agent（移除重複邏輯、引用新 skill） +4. 更新文件（README.md、CHANGELOG.md、版本號） + +--- + +## 快速參考 + +### 常見問題快速解答 + +| 問題 | 答案 | 參考文件 | +|------|------|---------| +| 第一次使用這個邏輯，要獨立嗎？ | ❌ 不要，遵循 YAGNI 原則 | [best-practices.md](best-practices.md) | +| 第二次使用，要獨立嗎？ | ✅ 強烈建議獨立 | [examples.md](examples.md) | +| 邏輯很複雜但只用一次？ | 視情況，看是否有獨立價值 | [SKILL.md](SKILL.md#判斷標準) | +| 如何命名 skill？ | 使用 kebab-case，動詞開頭 | [implementation.md](implementation.md#命名規範) | +| SKILL.md 必須包含什麼？ | YAML Front Matter、核心功能、執行步驟 | [implementation.md](implementation.md#skillmd-格式規範) | +| 可以在 skill 中引用其他 skills 嗎？ | 可以，但要避免循環依賴 | [best-practices.md](best-practices.md) | + +### 設計檢查清單 + +創建 skill 前快速檢查： + +- [ ] 有 2+ 個使用場景（或邏輯極其複雜） +- [ ] 職責單一且清晰 +- [ ] 名稱具有描述性 +- [ ] 規劃了完整的文件結構 +- [ ] 考慮了與現有 commands/skills 的整合 + +--- + +## 總結 + +設計 Skill 的核心原則： + +1. **YAGNI**：不要過度設計，等需求明確時再抽取 +2. **DRY**：出現重複時才抽取，而不是提前 +3. **單一職責**：一個 skill 只做一件事 +4. **清晰介面**：明確的輸入輸出，完整的文件 + +**記住：保持簡單永遠是最好的設計。** + +--- + +## 延伸閱讀 + +- **官方資訊**：[official-reference.md](official-reference.md) - Claude Code Skills 官方定義和特性 +- **實際案例**：[examples.md](examples.md) - 包含成功和失敗的設計案例 +- **實作指南**：[implementation.md](implementation.md) - 詳細的檔案結構和命名規範 +- **避免錯誤**：[best-practices.md](best-practices.md) - 常見錯誤和最佳實踐 + +**專案相關**： +- 專案結構說明：[`CLAUDE.md`](../../../../CLAUDE.md) +- 其他 skills 範例： + - [`plugins/git/skills/resolving-conflict/SKILL.md`](../../../git/skills/resolving-conflict/SKILL.md) + - [`plugins/plugin-dev/skills/quick-fix/SKILL.md`](../test/plugin-dev/quick-fix/SKILL.md) diff --git a/skills/skills-development/best-practices.md b/skills/skills-development/best-practices.md new file mode 100644 index 0000000..984daea --- /dev/null +++ b/skills/skills-development/best-practices.md @@ -0,0 +1,740 @@ +# 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 diff --git a/skills/skills-development/examples.md b/skills/skills-development/examples.md new file mode 100644 index 0000000..f8c67e2 --- /dev/null +++ b/skills/skills-development/examples.md @@ -0,0 +1,386 @@ +# 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 diff --git a/skills/skills-development/implementation.md b/skills/skills-development/implementation.md new file mode 100644 index 0000000..1d9d600 --- /dev/null +++ b/skills/skills-development/implementation.md @@ -0,0 +1,815 @@ +# Skills 實施指南 + +本文件提供詳細的 skill 實施指南，包含檔案結構、格式規範、命名規範和實施步驟。 + +## Skill 檔案結構 + +### 基本結構 + +每個 skill 都是一個獨立的資料夾，裡面的結構如下： + +``` +/ +├── SKILL.md # 必須：Skill 定義檔 +├── scripts/ # 可選：可執行腳本 +│ ├── setup.sh +│ └── helper.py +├── templates/ # 可選：範本檔案 +│ ├── config.yaml +│ └── example.md +└── resources/ # 可選：其他資源 + ├── diagrams/ + └── references/ +``` + +### 目錄命名規範 + +**官方標準 vs 本專案擴充** + +根據 [Claude Code Skills 官方規範](https://docs.claude.com/en/docs/claude-code/skills)，以下是目錄命名的規範： + +| 目錄名稱 | 性質 | 說明 | 建議 | +|--------------|-------|---------------------------|-------------------------| +| `SKILL.md` | 官方必須 | Skill 定義檔，也可以是其他 `.md` 檔案 | 強烈建議使用 `SKILL.md` 保持一致性 | +| `scripts/` | 官方建議 | 存放可執行腳本的標準目錄 | **建議使用**官方名稱以保持跨平台相容性 | +| `resources/` | 官方建議 | 存放輔助資源的標準目錄 | **建議使用**官方名稱以保持跨平台相容性 | +| `templates/` | 本專案擴充 | 本專案新增的範本檔案目錄 | 可選使用，不影響官方相容性 | + +**自訂目錄名稱** + +雖然官方沒有強制規定目錄名稱，但為了保持一致性和跨平台相容性： + +- ✅ **建議**：使用官方推薦的 `scripts/` 和 `resources/` 名稱 +- ✅ **可以**：新增本專案的 `templates/` 或其他自訂目錄 +- ⚠️ **不建議**：修改官方推薦的目錄名稱（如將 `scripts/` 改為 `bin/`） +- ❌ **避免**：使用可能與官方未來擴充衝突的名稱 + +**重要提醒**： + +- 使用官方名稱可確保 skill 在不同平台（Claude.ai、Claude Code、Claude API）間正常運作 +- 自訂目錄只能在支援的平台上使用，可能影響可移植性 + +### 必須的檔案 + +#### SKILL.md + +**用途**：定義 skill 的核心工作流程和行為 + +**必須包含**： + +- YAML Front Matter（name, description） +- 核心功能說明 +- 執行步驟 + +**範例**： + +```markdown +--- +name: example-skill +description: 簡短描述這個 skill 的核心功能 +--- + +# Skill 標題 + +## 核心功能 + +- 功能 1 +- 功能 2 + +## 執行步驟 + +1. 步驟 1 +2. 步驟 2 +3. 步驟 3 +``` + +### 可選的資源類型 + +#### 腳本檔案 (scripts/) + +**用途**：存放可執行的腳本 + +**適用情境**： + +- Skill 需要執行系統命令 +- 包含可重複使用的腳本邏輯 +- 需要與外部工具整合 + +**範例**： + +``` +scripts/ +├── analyze.py # Python 分析腳本 +├── format.sh # Bash 格式化腳本 +└── validate.js # JavaScript 驗證腳本 +``` + +**注意事項**： + +- 腳本應該有可執行權限（`chmod +x`） +- 在 SKILL.md 中說明如何使用這些腳本 +- 腳本應該有清晰的錯誤處理 + +#### 範本檔案 (templates/) + +**用途**：存放範本檔案 + +**適用情境**： + +- Skill 需要產生標準格式的檔案 +- 提供可自訂的配置範本 +- 包含文件範本 + +**範例**： + +``` +templates/ +├── README.template.md # README 範本 +├── config.template.yaml # 配置檔範本 +└── test.template.js # 測試檔案範本 +``` + +**注意事項**： + +- 範本中使用清晰的佔位符（如 `{{PLACEHOLDER}}`） +- 在 SKILL.md 中說明如何使用範本 +- 提供範本的填寫說明 + +#### 輔助資源檔案 (resources/) + +**用途**：存放其他輔助資源 + +**適用情境**： + +- 需要參考的圖表或文件 +- 靜態資料檔案 +- 額外的說明文件 + +**範例**： + +``` +resources/ +├── diagrams/ +│ └── workflow.mermaid # Mermaid 流程圖 +├── references/ +│ └── api-spec.json # API 規格 +└── data/ + └── examples.json # 範例資料 +``` + +--- + +## SKILL.md 格式規範 + +### YAML Front Matter + +位於檔案開頭，使用 `---` 包圍： + +```yaml +--- +name: Skill-Name # 必須：skill 的名稱 +description: 簡短描述 # 必須：一句話說明核心功能 +--- +``` + +#### name 欄位 + +**必須欄位** + +**格式**： + +- 使用 kebab-case（如 `skills-development`） +- 與資料夾名稱完全一致 + +**範例**： + +``` +# ✅ 正確 +name: resolving-conflict +name: skills-development +name: quick-fix + +# ❌ 錯誤 +name: Resolving-Conflict # 首字母大寫 +name: resolvingConflict # camelCase +name: resolving_conflict # snake_case +name: RESOLVING-CONFLICT # SCREAMING-KEBAB-CASE +``` + +#### description 欄位 + +**必須欄位** + +**用途與重要性** + +description 是 **AI 發現和選擇 skill 的關鍵**： + +1. **啟動時預載入**：Claude 在啟動時會預載入所有 skills 的 name 和 description 到 system prompt +2. **動態發現**：工作時 Claude 會掃描 descriptions 來找到相關的 skills +3. **漸進式揭露**：只有在需要時才載入完整的 SKILL.md 內容 +4. **Token 效率**：每個 skill 只佔用幾十個 tokens，保持 Claude 快速運作 + +**內容要求** + +description 必須包含兩個關鍵資訊： + +1. ✅ **What（做什麼）**：這個 skill 的核心功能 +2. ✅ **When（何時使用）**：Claude 應該在什麼情況下使用它 + +**格式規範** + +- **官方限制**：最大 1024 字元 +- **建議長度**：50-150 字（一到兩句話） +- **語言**：繁體中文（本專案規範） +- **語態**：使用主動語態，直接說明功能 + +**範例** + +```yaml +# ✅ 優秀範例（包含 What 和 When） +description: 協助解決 Git Rebase 或 Merge 過程中的衝突，提供系統化的衝突解決流程。 +# What: 解決 Git 衝突 +# When: Git Rebase 或 Merge 過程中 + +description: 協助設計和開發 Claude Code Skills，提供 skill 設計的思考邏輯和最佳實踐 +# What: 協助設計和開發 Skills +# When: 設計 Skills 時需要思考邏輯和最佳實踐 + +# ⚠️ 需要改進 +description: 解決衝突 +# 問題：太簡短，缺少 When（何時使用） + +description: 這個 skill 是用來幫助使用者解決 Git 衝突的工具 +# 問題：不要用「這個 skill」開頭，語句冗長 + +description: 處理資料 +# 問題：太模糊，沒有說明做什麼資料處理、何時使用 + +# ❌ 錯誤範例 +description: Helps resolve git conflicts +# 問題：應使用繁體中文（本專案規範） + +description: 解決 Git 衝突的工具，可以幫助使用者在遇到衝突時進行處理，包含自動分析、手動編輯、衝突標記移除等多種功能，並且支援 rebase 和 merge 兩種模式 +# 問題：太冗長，應該簡潔明瞭 +``` + +**撰寫技巧** + +1. **直接說明功能** + - ✅ 協助解決 Git Rebase 或 Merge 過程中的衝突 + - ❌ 這是一個用來解決 Git 衝突的 skill + +2. **包含使用時機** + - ✅ 在 Git Rebase 或 Merge 過程中遇到衝突時 + - ❌ 解決衝突（沒說明什麼時候） + +3. **保持簡潔但完整** + - ✅ 一到兩句話，涵蓋 What 和 When + - ❌ 過度詳細的功能列表（這些應該放在 SKILL.md 內容中） + +4. **使用具體的情境** + - ✅ Git Rebase 或 Merge 過程中 + - ❌ 當你需要處理版本控制問題時 + +### 內容結構 + +**建議的章節順序**： + +```markdown +--- +name: skill-name +description: 簡短描述 +--- + +# Skill 標題 + +簡短的介紹（1-2 段） + +## 核心功能 + +- 列出主要功能 + +## 輸入條件（可選） + +- 列出前置條件 +- 需要的資訊或工具 + +## 執行步驟 + +1. 步驟 1 +2. 步驟 2 +3. 步驟 3 + +## 輸出結果（可選） + +- 說明產出內容 +- 如何被其他 commands/skills 使用 + +## 使用場景 + +- 適用情境 +- 工作流程範例 + +## 注意事項 + +- 安全檢查 +- 常見錯誤 + +## 整合其他工具（可選） + +- 相關的 commands、skills、agents +``` + +### 章節說明 + +#### 核心功能（必須） + +列出 skill 的主要功能，使用條列式： + +```markdown +## 核心功能 + +- 偵測當前的衝突狀態（rebase 或 merge） +- 列出所有衝突的檔案 +- 逐個檢視並解決衝突 +- 完成 rebase 或 merge 流程 +``` + +#### 執行步驟（必須） + +詳細說明工作流程，使用編號列表： + +```markdown +## 執行步驟 + +### 1. 準備階段 + +檢查前置條件： + +- 確認工具已安裝 +- 驗證環境設定 + +### 2. 執行階段 + +1. **第一步** + - 詳細說明 + - 可能的指令 + +2. **第二步** + - 詳細說明 + - 注意事項 + +### 3. 完成階段 + +清理和驗證： + +- 檢查結果 +- 產生報告 +``` + +#### 使用場景（建議） + +提供實際的使用範例： + +```markdown +## 使用場景 + +### 適用情境 + +- 情境 1 +- 情境 2 + +### 工作流程範例 + +\`\`\` +[使用者的操作] + +User: 描述使用者的請求 + +Agent: Claude 的回應和操作 + +[執行 skill 的過程] + +User: 使用者的後續互動 + +Agent: 完成的回應 +\`\`\` +``` + +--- + +## 命名規範 + +### 資料夾命名 + +**格式**：kebab-case（全小寫，單字用 `-` 分隔） + +**規則**： + +- ✅ 使用小寫字母和數字 +- ✅ 使用 `-` 分隔單字 +- ❌ 不使用 `_`（底線） +- ❌ 不使用大寫字母 +- ❌ 不使用特殊字元 + +**範例**： + +| ✅ 正確 | ❌ 錯誤 | 原因 | +|---------------------------|---------------------------|---------------| +| `resolving-conflict` | `ResolvingConflict` | 不使用大寫 | +| `skills-development` | `skills_development` | 使用 `-` 而非 `_` | +| `quick-fix` | `quickFix` | 不使用 camelCase | +| `generate-commit-message` | `generate.commit.message` | 不使用 `.` | +| `api-v2-client` | `api_v2_client` | 使用 `-` 而非 `_` | + +### YAML name 欄位命名 + +**格式**：kebab-case（全小寫，與資料夾名稱完全一致） + +**規則**： + +- ✅ 使用 kebab-case 與資料夾名稱完全一致 +- ❌ 不使用首字母大寫 +- ❌ 不使用 camelCase +- ❌ 不使用 snake_case +- ❌ 不使用 PascalCase + +**範例**： + +| 資料夾名稱 | ✅ 正確的 name | ❌ 錯誤的 name | +|----------------------|----------------------|-------------------------------------------------------------| +| `resolving-conflict` | `resolving-conflict` | `Resolving-Conflict`
`resolvingConflict`
`resolving_conflict` | +| `skills-development` | `skills-development` | `Skills-Development`
`skillsDevelopment`
`SKILLS-DEVELOPMENT` | +| `quick-fix` | `quick-fix` | `Quick-Fix`
`quickFix`
`QuickFix` | + +**推薦做法**： + +```yaml +# 推薦：與資料夾名稱完全一致 +資料夾：skills-development/ +name: skills-development +``` + +### 描述性命名 + +Skill 名稱應該清楚描述功能： + +**✅ 好的命名**： + +| 名稱 | 說明 | +|---------------------------|--------------| +| `analyze-atomicity` | 明確說明「分析原子性」 | +| `generate-commit-message` | 明確說明「產生提交訊息」 | +| `resolving-conflict` | 明確說明「解決衝突」 | +| `validate-config` | 明確說明「驗證配置」 | + +**❌ 壞的命名**： + +| 名稱 | 問題 | +|-------------|------------| +| `helper` | 太抽象，不知道幫什麼 | +| `utils` | 太通用，應該明確功能 | +| `processor` | 不知道處理什麼 | +| `manager` | 不知道管理什麼 | +| `do-stuff` | 完全不清楚功能 | + +### 命名最佳實踐 + +#### 1. 使用動詞開頭 + +描述 skill 的動作： + +``` +✅ analyze-atomicity （分析原子性） +✅ generate-message （產生訊息） +✅ validate-input （驗證輸入） +✅ resolve-conflict （解決衝突） + +❌ atomicity-analyzer （應該用動詞開頭） +❌ message-generator （應該用動詞開頭） +``` + +#### 2. 保持簡潔但清楚 + +``` +✅ validate-config （簡潔清楚） +✅ parse-json （簡潔清楚） + +❌ validate-all-configuration-files （太長） +❌ val-cfg （縮寫不清楚） +``` + +#### 3. 避免重複 + +``` +✅ git/skills/resolve-conflict/ （git 已在 plugin 名稱中） +❌ git/skills/git-resolve-conflict/ （重複 git） + +✅ jira/skills/analyze-ticket/ +❌ jira/skills/jira-analyze-ticket/ +``` + +--- + +## 實施計畫 + +當你決定要創建一個新的 skill 時，按照以下步驟進行： + +### 步驟 1：創建檔案結構 + +```bash +# 進入 plugin 目錄 +cd plugins/{plugin-name} + +# 創建 skill 資料夾 +mkdir -p skills/{skill-name} + +# 創建核心定義檔 +touch skills/{skill-name}/SKILL.md + +# 如果需要，創建可選的資源資料夾 +mkdir -p skills/{skill-name}/scripts +mkdir -p skills/{skill-name}/templates +mkdir -p skills/{skill-name}/resources +``` + +### 步驟 2：設計 SKILL.md + +**2.1 撰寫 YAML Front Matter** + +```yaml +--- +name: your-skill-name +description: 一句話說明這個 skill 的核心功能（50-100 字） +--- +``` + +**2.2 撰寫核心內容** + +按照以下順序組織內容： + +1. **主標題和簡介** + ```markdown + # Skill 標題 + + 簡短介紹這個 skill 的用途和價值（1-2 段） + ``` + +2. **核心功能** + ```markdown + ## 核心功能 + + - 功能 1 + - 功能 2 + - 功能 3 + ``` + +3. **執行步驟** + ```markdown + ## 執行步驟 + + ### 1. 步驟標題 + + 詳細說明... + + ### 2. 步驟標題 + + 詳細說明... + ``` + +4. **其他章節**（視需要加入） + - 輸入條件 + - 輸出結果 + - 使用場景 + - 注意事項 + - 整合其他工具 + +**2.3 撰寫範例** + +提供實際的使用範例，幫助使用者理解： + +```markdown +## 工作流程範例 + +\`\`\` +User: [使用者的請求] + +Agent: [Claude 的回應] +[執行 skill 的步驟] + +User: [使用者的後續互動] + +Agent: [完成的回應] +\`\`\` +``` + +### 步驟 3：重構現有程式碼（如果適用） + +如果是從現有的 command/agent 中抽取 skill： + +**3.1 識別要抽取的邏輯** + +找出重複使用或可以獨立的部分 + +**3.2 更新原始檔案** + +移除重複的邏輯，改為引用新的 skill： + +```markdown +## 執行步驟 + +1. 準備工作 +2. **使用 `{plugin-name}:{skill-name}` skill** 執行主要邏輯 +3. 後續處理 +``` + +**3.3 測試功能** + +確保重構後功能正常： + +- 測試所有引用這個 skill 的 commands +- 確認 skill 可以獨立執行 +- 檢查錯誤處理 + +### 步驟 4：更新文件 + +**4.1 更新 Plugin README.md** + +在 plugin 的 README 中加入新的 skill： + +```markdown +## Skills + +### {skill-name} + +簡短說明這個 skill 的功能。 + +**位置**：`skills/{skill-name}/SKILL.md` + +**主要功能**： + +- 功能 1 +- 功能 2 + +**使用方式**： +在 commands 或 agents 中引用這個 skill +``` + +**4.2 更新 CHANGELOG.md** + +記錄到 plugin 的 CHANGELOG： + +```markdown +## [Unreleased] + +### Added + +- 新增 `{skill-name}` skill：{簡短說明} +``` + +**4.3 更新版本號**（如果需要發布） + +在 `.claude-plugin/plugin.json` 中更新版本號： + +```json +{ + "name": "plugin-name", + "version": "1.1.0", + ... +} +``` + +--- + +## 品質檢查清單 + +創建或修改 skill 後，使用這個檢查清單確保品質： + +### 檔案結構 + +- [ ] `SKILL.md` 檔案存在且位於正確位置 +- [ ] 資料夾名稱使用 kebab-case +- [ ] 檔案結尾有空行 +- [ ] 可選的資料夾（scripts, templates, resources）有適當的組織 + +### YAML Front Matter + +- [ ] 包含 `name` 欄位 +- [ ] 包含 `description` 欄位 +- [ ] `name` 使用 PascalCase 或 kebab-case +- [ ] `description` 清楚簡潔（50-100 字） +- [ ] 使用繁體中文 +- [ ] YAML 格式正確（使用 `---` 包圍） + +### 內容品質 + +- [ ] 包含「核心功能」章節 +- [ ] 包含「執行步驟」章節 +- [ ] 執行步驟清晰且可操作 +- [ ] 提供使用範例或場景 +- [ ] 包含注意事項（如果適用） +- [ ] Markdown 格式正確 +- [ ] 沒有錯字和語法錯誤 + +### 命名規範 + +- [ ] 資料夾名稱使用 kebab-case +- [ ] YAML name 與資料夾名稱一致（推薦） +- [ ] 名稱具有描述性，清楚說明功能 +- [ ] 使用動詞開頭（建議） +- [ ] 避免重複 plugin 名稱 + +### 功能驗證 + +- [ ] Skill 可以獨立執行 +- [ ] 所有引用這個 skill 的 commands/agents 都能正常運作 +- [ ] 測試過主要使用場景 +- [ ] 錯誤處理完善 + +### 文件更新 + +- [ ] 更新 Plugin README.md +- [ ] 更新 CHANGELOG.md +- [ ] 更新版本號（如果需要發布） +- [ ] 所有文件間的連結正確 + +### 整合檢查 + +- [ ] 與其他 skills 的介面清楚 +- [ ] 與 commands 的整合正確 +- [ ] 與 agents 的整合正確 +- [ ] 沒有與其他 skills 重複的功能 + +--- + +## 常見問題 + +### Q1：應該創建多少個可選資料夾？ + +**A**：只創建你實際需要的資料夾。 + +- 如果沒有腳本，不要創建空的 `scripts/` 資料夾 +- 如果沒有範本，不要創建空的 `templates/` 資料夾 +- 保持結構簡單，遵循 YAGNI 原則 + +### Q2：YAML name 必須使用 kebab-case 嗎？ + +**A**：**是的，統一使用全小寫的 kebab-case** 與資料夾名稱完全一致。 + +範例： + +``` +資料夾：skills-development/ +YAML： name: skills-development （全小寫的 kebab-case） +``` + +這樣可以保持命名的一致性，便於維護和識別。 + +### Q3：description 應該寫多長？要包含什麼內容？ + +**A**：**建議 50-150 字**，一到兩句話，必須包含 **What（做什麼）** 和 **When（何時使用）**。 + +**原因**： +- description 是 AI 發現 skill 的關鍵，會被預載入到 system prompt +- Claude 透過掃描 descriptions 來決定使用哪個 skill +- 官方限制最大 1024 字元 + +**範例**： +- ✅ 優秀：「協助解決 Git Rebase 或 Merge 過程中的衝突，提供系統化的衝突解決流程。」 + - What: 解決 Git 衝突 + - When: Git Rebase 或 Merge 過程中 +- ❌ 太簡短：「解決衝突」（缺少 When 和具體情境） +- ❌ 太冗長：列出所有功能細節（應該放在 SKILL.md 內容中） + +### Q4：可以在 skill 中引用其他 skills 嗎？ + +**A**：可以，但要注意避免循環依賴。 + +```markdown +## 執行步驟 + +1. 使用 `analyze-changes` skill 分析變更 +2. 根據分析結果決定策略 +3. 執行對應的操作 +``` + +### Q5：如何處理 skill 的版本控制？ + +**A**：Skills 的版本跟隨 plugin 的版本。 + +- 修改 skill 時更新 plugin 的 CHANGELOG +- 如果是重大變更，考慮增加 plugin 的 MAJOR 版本號 +- 在 CHANGELOG 中明確記錄 skill 的變更 + +--- + +## 與其他文件的關聯 + +- **[SKILL.md](SKILL.md)**：核心判斷標準，決定是否需要創建 skill +- **[official-reference.md](official-reference.md)**：官方格式規範的詳細說明 +- **[examples.md](examples.md)**：實際案例，看其他 skills 如何實作 +- **[best-practices.md](best-practices.md)**：避免實施中的常見錯誤 + +--- + +**最後更新**：2025-10-19 diff --git a/skills/skills-development/official-reference.md b/skills/skills-development/official-reference.md new file mode 100644 index 0000000..08daf32 --- /dev/null +++ b/skills/skills-development/official-reference.md @@ -0,0 +1,231 @@ +# Claude Code Skills 官方定義與參考 + +本文件整理 Claude Code Skills 的官方定義、特性和最佳實踐，並說明與本 marketplace 專案的對應關係。 + +## 官方定義 + +### 什麼是 Skills？ + +根據 Anthropic 官方文件，**Skills** 是： + +> **模組化的能力擴展**，透過組織化的資料夾結構來擴展 Claude 的功能。每個 skill 是一個包含指令、腳本和資源的獨立單元。 + +Skills 在 2025 年 10 月正式發布，適用於： +- Claude.ai（Pro、Max、Team、Enterprise 方案） +- Claude Code（Beta） +- Claude API（使用 code execution tool） + +## 核心特性 + +### 1. 模組化設計 + +每個 skill 是一個獨立的資料夾，包含： +- **指令檔案**（如 SKILL.md）：定義工作流程和行為 +- **腳本**（可選）：可執行的程式碼 +- **範本**（可選）：可重複使用的檔案範本 +- **資源**（可選）：其他輔助檔案 + +**優勢**： +- 邏輯集中管理 +- 易於測試和維護 +- 可以獨立版本控制 + +### 2. 跨平台通用 + +Skills 使用統一的格式，**設計一次，到處使用**： + +``` +同一個 skill 可以在以下環境中使用： +┌─────────────────────────────────────┐ +│ Claude.ai (網頁版) │ +│ Claude Code (開發工具) │ +│ Claude API (程式整合) │ +└─────────────────────────────────────┘ + ▲ + │ + 同一套 skill 定義 +``` + +**本專案的實作**： +- Plugins 遵循官方格式 +- 可以輕鬆在不同環境間移植 +- 統一的 YAML Front Matter 格式 + +### 3. 動態載入 + +Claude 會在相關時**自動發現和載入** skills： +- 根據任務需求自動選擇合適的 skill +- 使用者不需要手動指定 +- 也支援明確呼叫特定 skill + +**載入方式**： +- **自動**：Claude 偵測到相關任務時自動載入 +- **手動**：使用 `/skill-name` 明確呼叫 +- **引用**：在 commands、agents 中引用其他 skills + +### 4. 統一的安裝方式 + +**Claude Code 中的安裝**： + +```bash +# 方式 1：透過 plugin 安裝（推薦） +# 從 marketplace 安裝，自動載入 + +# 方式 2：手動安裝 +# 將 skill 資料夾複製到 ~/.claude/skills/ +``` + +**本專案的做法**： +- Skills 包含在 plugins 中 +- 使用者安裝 plugin 時自動獲得相關 skills +- 遵循官方的資料夾結構 + +## 官方最佳實踐 + +### 1. Planning First Approach + +**官方建議**： +> 要求 Claude 在編碼前先制定計畫，並明確告知在確認計畫前不要開始編碼。 + +**應用到 Skills 設計**： +- Skills 應該包含明確的執行步驟 +- 複雜的 skills 應該先規劃再執行 +- 使用 TodoWrite 追蹤任務進度 + +### 2. Extended Thinking Mode + +**官方建議**： +> 使用「think」、「think hard」、「think harder」、「ultrathink」觸發更深入的思考。 + +**應用到 Skills 設計**： +- 複雜決策的 skills 應該引導 Claude 深入思考 +- 在 skill 中可以加入「仔細思考」的提示 + +### 3. Custom Commands Integration + +**官方建議**： +> 將重複的工作流程儲存為 Markdown 檔案在 `.claude/commands` 資料夾。 + +**本專案的整合**： +- Commands 可以引用 Skills +- Skills 提供可重複使用的邏輯 +- Commands 提供使用者友善的入口點 + +### 4. Skills as Reusable Workflows + +**官方強調**： +> Skills 是可重複使用的工作流程，應該在多處使用相同邏輯時才抽取。 + +**本專案的實踐**： +- 遵循 YAGNI 原則（詳見 `SKILL.md`） +- 使用判斷標準決定是否獨立成 skill +- 提供決策樹輔助判斷 + +## 與本專案的對應 + +### 目錄結構對應 + +**官方標準結構**： +``` +{skill-name}/ +├── SKILL.md # 或其他 .md 檔案 +├── scripts/ # 可選 +└── resources/ # 可選 +``` + +**本專案的結構**： +``` +plugins/{plugin-name}/skills/{skill-name}/ +├── SKILL.md # 必須 +├── scripts/ # 可選 +├── templates/ # 可選（擴充） +└── resources/ # 可選 +``` + +**差異說明**： +- 本專案將 skills 組織在 plugins 下 +- 新增 `templates/` 資料夾用於存放範本 +- 其他遵循官方標準 + +### YAML Front Matter 對應 + +**官方格式**： +```yaml +--- +name: Skill Name +description: Brief description +--- +``` + +**本專案格式**（完全相同）： +```yaml +--- +name: Skill-Name # PascalCase 或 kebab-case +description: 簡短描述 # 一句話說明核心功能 +--- +``` + +### 命名規範對應 + +**官方建議**： +- 使用描述性名稱 +- 反映 skill 的功能 + +**本專案規範**： +- 資料夾名稱：`kebab-case`（如 `skills-development`） +- YAML name 欄位：`PascalCase` 或 `kebab-case`（如 `Skills-Development`） +- 描述性、動詞開頭（如 `analyze-atomicity`） + +詳細命名規範請參閱 [`implementation.md`](implementation.md)。 + +## 官方資源連結 + +### 文件 + +- **Claude Code Skills 文件**：https://docs.claude.com/en/docs/claude-code/skills +- **Skills 公告**：https://www.anthropic.com/news/skills +- **Agent Skills 工程部落格**：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills +- **Claude Code 最佳實踐**：https://www.anthropic.com/engineering/claude-code-best-practices + +### 官方 Skills Repository + +- **GitHub**：https://github.com/anthropics/skills +- 官方維護的 skills 範例 +- 可以參考學習和貢獻 + +### 支援文件 + +- **什麼是 Skills？**：https://support.claude.com/en/articles/12512176-what-are-skills +- **在 Claude 中使用 Skills**：https://support.claude.com/en/articles/12512180-using-skills-in-claude + +## 與其他文件的關聯 + +本專案的 Skills Development 文件系列： + +1. **[SKILL.md](SKILL.md)**：主文件，包含核心判斷標準和設計原則 +2. **[official-reference.md](official-reference.md)**（本文件）：官方定義和參考 +3. **[examples.md](examples.md)**：實際案例分析 +4. **[implementation.md](implementation.md)**：實施指南和命名規範 +5. **[best-practices.md](best-practices.md)**：最佳實踐和常見錯誤 + +建議閱讀順序： +1. 先閱讀 `SKILL.md` 了解核心概念 +2. 參考本文件了解官方定義 +3. 查看 `examples.md` 學習實際案例 +4. 使用 `implementation.md` 進行實作 +5. 遵循 `best-practices.md` 避免常見錯誤 + +## 總結 + +Claude Code Skills 是 Anthropic 官方提供的強大功能，讓開發者能夠： +- **擴展 Claude 的能力**：透過模組化的方式 +- **重複使用工作流程**：在多個地方使用相同邏輯 +- **跨平台通用**：一次設計，到處使用 +- **動態載入**：自動發現和載入相關 skills + +本 marketplace 專案遵循官方規範，並加入了適合團隊協作的最佳實踐，幫助開發者更有效地設計和管理 skills。 + +--- + +**最後更新**：2025-10-19 +**官方 Skills 版本**：2025 年 10 月發布版本