zhongwei/gh-mileschou-claude-marketplace-plugins-plugin-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:40:34 +08:00
commit 7c88e7d08d
10 changed files with 3266 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "plugin-dev",
"description": "Plugin development tools",
"version": "0.1.0",
"author": {
"name": "Miles Chou"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# plugin-dev
Plugin development tools

461
commands/create-skill.md Normal file
View File

@@ -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 中的版本管理規範

69
plugin.lock.json Normal file
View File

@@ -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": []
}
}

220
skills/quick-fix/SKILL.md Normal file
View File

@@ -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 的實際功能一致

327
skills/skills-development/SKILL.md Normal file
View File

@@ -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+ 個<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](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)

740
skills/skills-development/best-practices.md Normal file
View File

@@ -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

386
skills/skills-development/examples.md Normal file
View File

@@ -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

815
skills/skills-development/implementation.md Normal file
View File

@@ -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`<br>`resolvingConflict`<br>`resolving_conflict` |
| `skills-development` | `skills-development` | `Skills-Development`<br>`skillsDevelopment`<br>`SKILLS-DEVELOPMENT` |
| `quick-fix` | `quick-fix` | `Quick-Fix`<br>`quickFix`<br>`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

231
skills/skills-development/official-reference.md Normal file
View File

@@ -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 月發布版本