816 lines
19 KiB
Markdown
816 lines
19 KiB
Markdown
# 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
|