zhongwei/gh-mileschou-claude-marketplace-plugins-plugin-dev

Fork 0

Files

Zhongwei Li 7c88e7d08d Initial commit

2025-11-30 08:40:34 +08:00

19 KiB

Raw Blame History

Skills 實施指南

本文件提供詳細的 skill 實施指南，包含檔案結構、格式規範、命名規範和實施步驟。

Skill 檔案結構

基本結構

每個 skill 都是一個獨立的資料夾，裡面的結構如下：

/
├── SKILL.md          # 必須：Skill 定義檔
├── scripts/          # 可選：可執行腳本
│   ├── setup.sh
│   └── helper.py
├── templates/        # 可選：範本檔案
│   ├── config.yaml
│   └── example.md
└── resources/        # 可選：其他資源
    ├── diagrams/
    └── references/

目錄命名規範

官方標準 vs 本專案擴充

根據 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）
核心功能說明
執行步驟

範例：

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

位於檔案開頭，使用 --- 包圍：

---
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 的關鍵：

啟動時預載入：Claude 在啟動時會預載入所有 skills 的 name 和 description 到 system prompt
動態發現：工作時 Claude 會掃描 descriptions 來找到相關的 skills
漸進式揭露：只有在需要時才載入完整的 SKILL.md 內容
Token 效率：每個 skill 只佔用幾十個 tokens，保持 Claude 快速運作

內容要求

description 必須包含兩個關鍵資訊：

✅ What（做什麼）：這個 skill 的核心功能
✅ When（何時使用）：Claude 應該在什麼情況下使用它

格式規範

官方限制：最大 1024 字元
建議長度：50-150 字（一到兩句話）
語言：繁體中文（本專案規範）
語態：使用主動語態，直接說明功能

範例

# ✅ 優秀範例（包含 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 兩種模式
# 問題：太冗長，應該簡潔明瞭

撰寫技巧

直接說明功能
- ✅ 協助解決 Git Rebase 或 Merge 過程中的衝突
- ❌ 這是一個用來解決 Git 衝突的 skill
包含使用時機
- ✅ 在 Git Rebase 或 Merge 過程中遇到衝突時
- ❌ 解決衝突（沒說明什麼時候）
保持簡潔但完整
- ✅ 一到兩句話，涵蓋 What 和 When
- ❌ 過度詳細的功能列表（這些應該放在 SKILL.md 內容中）
使用具體的情境
- ✅ Git Rebase 或 Merge 過程中
- ❌ 當你需要處理版本控制問題時

內容結構

建議的章節順序：

---
name: skill-name
description: 簡短描述
---

# Skill 標題

簡短的介紹（1-2 段）

## 核心功能

- 列出主要功能

## 輸入條件（可選）

- 列出前置條件
- 需要的資訊或工具

## 執行步驟

1. 步驟 1
2. 步驟 2
3. 步驟 3

## 輸出結果（可選）

- 說明產出內容
- 如何被其他 commands/skills 使用

## 使用場景

- 適用情境
- 工作流程範例

## 注意事項

- 安全檢查
- 常見錯誤

## 整合其他工具（可選）

- 相關的 commands、skills、agents

章節說明

核心功能（必須）

列出 skill 的主要功能，使用條列式：

## 核心功能

- 偵測當前的衝突狀態（rebase 或 merge）
- 列出所有衝突的檔案
- 逐個檢視並解決衝突
- 完成 rebase 或 merge 流程

執行步驟（必須）

詳細說明工作流程，使用編號列表：

## 執行步驟

### 1. 準備階段

檢查前置條件：

- 確認工具已安裝
- 驗證環境設定

### 2. 執行階段

1. **第一步**
    - 詳細說明
    - 可能的指令

2. **第二步**
    - 詳細說明
    - 注意事項

### 3. 完成階段

清理和驗證：

- 檢查結果
- 產生報告

使用場景（建議）

提供實際的使用範例：

## 使用場景

### 適用情境

- 情境 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`

推薦做法：

# 推薦：與資料夾名稱完全一致
資料夾：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：創建檔案結構

# 進入 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

---
name: your-skill-name
description: 一句話說明這個 skill 的核心功能（50-100 字）
---

2.2 撰寫核心內容

按照以下順序組織內容：

主標題和簡介

# Skill 標題

簡短介紹這個 skill 的用途和價值（1-2 段）

核心功能

## 核心功能

- 功能 1
- 功能 2
- 功能 3

執行步驟

## 執行步驟

### 1. 步驟標題

詳細說明...

### 2. 步驟標題

詳細說明...

其他章節（視需要加入）
- 輸入條件
- 輸出結果
- 使用場景
- 注意事項
- 整合其他工具

2.3 撰寫範例

提供實際的使用範例，幫助使用者理解：

## 工作流程範例

\`\`\`
User: [使用者的請求]

Agent: [Claude 的回應]
[執行 skill 的步驟]

User: [使用者的後續互動]

Agent: [完成的回應]
\`\`\`

步驟 3：重構現有程式碼（如果適用）

如果是從現有的 command/agent 中抽取 skill：

3.1 識別要抽取的邏輯

找出重複使用或可以獨立的部分

3.2 更新原始檔案

移除重複的邏輯，改為引用新的 skill：

## 執行步驟

1. 準備工作
2. **使用 `{plugin-name}:{skill-name}` skill** 執行主要邏輯
3. 後續處理

3.3 測試功能

確保重構後功能正常：

測試所有引用這個 skill 的 commands
確認 skill 可以獨立執行
檢查錯誤處理

步驟 4：更新文件

4.1 更新 Plugin README.md

在 plugin 的 README 中加入新的 skill：

## Skills

### {skill-name}

簡短說明這個 skill 的功能。

**位置**：`skills/{skill-name}/SKILL.md`

**主要功能**：

- 功能 1
- 功能 2

**使用方式**：
在 commands 或 agents 中引用這個 skill

4.2 更新 CHANGELOG.md

記錄到 plugin 的 CHANGELOG：

## [Unreleased]

### Added

- 新增 `{skill-name}` skill：{簡短說明}

4.3 更新版本號（如果需要發布）

在 .claude-plugin/plugin.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：可以，但要注意避免循環依賴。

## 執行步驟

1. 使用 `analyze-changes` skill 分析變更
2. 根據分析結果決定策略
3. 執行對應的操作

Q5：如何處理 skill 的版本控制？

A：Skills 的版本跟隨 plugin 的版本。

修改 skill 時更新 plugin 的 CHANGELOG
如果是重大變更，考慮增加 plugin 的 MAJOR 版本號
在 CHANGELOG 中明確記錄 skill 的變更

與其他文件的關聯

SKILL.md：核心判斷標準，決定是否需要創建 skill
official-reference.md：官方格式規範的詳細說明
examples.md：實際案例，看其他 skills 如何實作
best-practices.md：避免實施中的常見錯誤

最後更新：2025-10-19

19 KiB Raw Blame History Unescape Escape

Skills 實施指南

Skill 檔案結構

基本結構

目錄命名規範

必須的檔案

SKILL.md

可選的資源類型

腳本檔案 (scripts/)

範本檔案 (templates/)

輔助資源檔案 (resources/)

SKILL.md 格式規範

YAML Front Matter

name 欄位

description 欄位

內容結構

章節說明

核心功能（必須）

執行步驟（必須）

使用場景（建議）

命名規範

資料夾命名

YAML name 欄位命名

描述性命名

命名最佳實踐

1. 使用動詞開頭

2. 保持簡潔但清楚

3. 避免重複

實施計畫

步驟 1：創建檔案結構

步驟 2：設計 SKILL.md

步驟 3：重構現有程式碼（如果適用）

步驟 4：更新文件

品質檢查清單

檔案結構

YAML Front Matter

內容品質

命名規範

功能驗證

文件更新

整合檢查

常見問題

Q1：應該創建多少個可選資料夾？

Q2：YAML name 必須使用 kebab-case 嗎？

Q3：description 應該寫多長？要包含什麼內容？

Q4：可以在 skill 中引用其他 skills 嗎？

Q5：如何處理 skill 的版本控制？

與其他文件的關聯

19 KiB

Raw Blame History