---

name: skill-development description: 開發新 Agent Skills 的標準化工作流程。當使用者要求建立新技能、轉化工作流程為技能、或詢問 SKILL.md 格式時自動啟用。包含技能結構設計、YAML frontmatter 規範、觸發關鍵字最佳實踐、資源檔案組織。A meta-skill for creating new Agent Skills with standardized workflow, SKILL.md format specification, trigger keyword design, and resource organization best practices. metadata: author: singular-blockly version: '1.0.0' category: meta license: Apache-2.0

Agent Skill 開發技能 Skill Development Meta-Skill

開發新 Agent Skills 的標準化工作流程與最佳實踐。 A standardized workflow and best practices for developing new Agent Skills.

適用情境 When to Use

• 需要將重複性工作流程轉化為技能
• 建立新的專案特定技能
• 詢問 SKILL.md 格式規範
• 設計技能的觸發關鍵字
• 組織技能的輔助資源
• 查找現有可用的 Skills（避免重複造輪子）

查找現有 Skills Finding Existing Skills

在開發新技能前，建議先搜尋是否已有合適的現成技能可以採用或參考。

可信賴的 Skills 來源 Trusted Skill Sources

以下來源經過官方認可或社群驗證，可安全使用：

搜尋現有技能 Search for Existing Skills

1. 在 GitHub 搜尋

   Copy# 搜尋技能檔案
   gh search code "name:" --filename=SKILL.md --language=markdown
   
   # 搜尋特定功能的技能（例如：code review）
   gh search repos "agent skills code review" --sort=stars
   

2. 瀏覽官方集合

   Copy# 列出 awesome-copilot 的技能目錄
   gh api repos/github/awesome-copilot/contents/skills --jq '.[].name'
   
   # 列出 anthropics/skills 的技能
   gh api repos/anthropics/skills/contents --jq '.[].name'
   

3. 查看技能詳情

   Copy# 讀取特定技能的 SKILL.md
   gh api repos/{owner}/{repo}/contents/skills/{skill-name}/SKILL.md \
     --jq '.content' | base64 -d
   

安全性檢查 Security Checklist

採用第三方技能前，務必執行以下檢查：

安裝第三方技能 Installing Third-Party Skills

Copy# 1. Clone 或下載技能目錄
git clone --depth=1 --filter=blob:none --sparse \
  https://github.com/{owner}/{repo}.git temp-skills
cd temp-skills
git sparse-checkout set skills/{skill-name}

# 2. 複製到專案
cp -r skills/{skill-name} /path/to/project/.github/skills/

# 3. 審查並客製化
code .github/skills/{skill-name}/SKILL.md

# 4. 清理
cd .. && rm -rf temp-skills

⚠️ 安全警告 Security Warning

永遠不要盲目信任來源不明的技能。Skills 雖然主要是文字指令，但可能包含：

• 誘導 AI 執行危險操作的指令
• 惡意腳本（在 scripts/ 目錄中）
• 外洩敏感資訊的 prompt injection

VS Code 提供了腳本執行控制，包括自動核准選項和允許清單。 詳見 VS Code 安全性文件

技能結構規範 Skill Structure Specification

目錄結構 Directory Structure

Copy.github/skills/{skill-name}/
├── SKILL.md                 # 必要：主要技能指令
├── references/              # 選用：參考文件
│   └── REFERENCE.md
├── scripts/                 # 選用：可執行腳本
│   └── helper.sh
├── assets/                  # 選用：範本和靜態資源
│   └── template.md
└── examples/                # 選用：使用範例
    └── example-1.md

命名規則 Naming Rules

SKILL.md 格式規範 SKILL.md Format

YAML Frontmatter（必要）

Copy---
name: skill-name # 必要：技能識別名稱
description: | # 必要：觸發描述（最多 1024 字元）
    中文描述。English description.
    包含關鍵字幫助 AI 決定何時載入。
metadata: # 選用：額外元資料
    author: your-name
    version: '1.0.0'
    category: category-name
license: Apache-2.0 # 選用：授權條款
compatibility: VS Code 1.108+ # 選用：環境需求
allowed-tools: Bash(git:*) Read # 選用：預先授權工具（實驗性）
---

關鍵欄位說明 Key Fields

name 欄位

• 必要，最多 64 字元
• 只能包含小寫字母、數字、連字號
• 必須與技能目錄名稱完全相同

description 欄位

• 必要，最多 1024 字元
• 這是 AI 決定是否載入技能的關鍵
• 應包含：
  • 技能功能描述
  • 適用情境
  • 觸發關鍵字（中英文）

內容主體 Body Content

Copy# 技能名稱 Skill Name

簡短描述。Brief description.

## 適用情境 When to Use

-   情境 1
-   情境 2

## 工作流程 Workflow

### Phase 1: 步驟名稱

1. 步驟說明
    ```bash
    command example
    ```

檢查清單 Checklist

• 項目 1
• 項目 2

相關資源 Related Resources

參考 完整範本

Copy
## 設計最佳實踐 Design Best Practices

### 1. 觸發關鍵字設計 Trigger Keyword Design

**有效的 description 範例**：
```yaml
description: 修復 npm 依賴安全漏洞的完整工作流程。當使用者提到安全警告、Dependabot alerts、CVE 漏洞、npm audit 問題時自動啟用。

關鍵字策略：

• 包含中英文關鍵字
• 涵蓋同義詞（安全漏洞、security vulnerability、CVE）
• 描述具體使用情境
• 避免過於通用的詞彙

2. 漸進式揭露 Progressive Disclosure

技能應該分層載入以節省 context：

建議：

• SKILL.md 主體保持在 500 行以內
• 將詳細參考資料移至 references/ 目錄
• 使用相對路徑連結資源

3. 雙語支援 Bilingual Support

本專案要求雙語文件：

Copy## 工作流程 Workflow

### Phase 1: 分析 Analysis

說明文字。
Description text.

4. 可操作性 Actionability

技能應該提供：

• ✅ 具體的命令範例
• ✅ 可複製的程式碼片段
• ✅ 清晰的檢查清單
• ✅ 範本檔案

5. 資源檔案組織 Resource Organization

開發工作流程 Development Workflow

Step 1: 分析需求

1. 識別重複性工作流程
2. 列出所有步驟和決策點
3. 收集常用命令和範本

Step 2: 設計結構

1. 決定技能名稱（遵循命名規則）
2. 撰寫觸發 description
3. 規劃目錄結構

Step 3: 撰寫 SKILL.md

1. 建立 YAML frontmatter
2. 撰寫工作流程步驟
3. 加入命令範例和檢查清單

Step 4: 建立輔助資源

1. 建立範本檔案
2. 撰寫參考文件
3. 新增腳本（如需要）

Step 5: 驗證

Copy# 驗證目錄結構
ls -la .github/skills/{skill-name}/

# 確認 SKILL.md 存在
cat .github/skills/{skill-name}/SKILL.md | head -20

# 驗證 YAML frontmatter（如有 skills-ref 工具）
skills-ref validate .github/skills/{skill-name}

Step 6: 驗證連結 Link Verification

確保所有內部連結都指向有效的檔案：

1. 提取 SKILL.md 中的相對路徑連結

   Copy# 找出所有 Markdown 連結
   grep -oE '\[.+\]\(\./[^)]+\)' .github/skills/{skill-name}/SKILL.md
   

2. 驗證連結目標存在

   Copy# 檢查每個連結的目標檔案
   # 例如：./assets/template.md → 確認 assets/template.md 存在
   ls .github/skills/{skill-name}/assets/template.md
   

3. 常見連結問題

   問題	說明	解決方案
   相對路徑錯誤	../../file.md 層級計算錯誤	從 SKILL.md 位置重新計算路徑
   檔案不存在	連結指向未建立的檔案	建立檔案或移除連結
   大小寫不符	Template.md vs template.md	統一使用小寫檔名

4. 外部連結驗證（選用）

   Copy# 檢查外部連結是否可存取（需要網路）
   curl -s -o /dev/null -w "%{http_code}" https://example.com/page
   

範本 Templates

最小化技能範本 Minimal Skill Template

參考 minimal-skill-template.md

完整技能範本 Full Skill Template

參考 full-skill-template.md

檢查清單 Checklist

結構檢查

• 技能目錄在 .github/skills/ 下
• 目錄名稱符合命名規則
• SKILL.md 存在且格式正確

Frontmatter 檢查

• name 與目錄名稱一致
• description 清楚且包含觸發關鍵字
• description 不超過 1024 字元

內容檢查

• 包含適用情境說明
• 工作流程步驟清晰
• 命令範例可執行
• 雙語支援完整

資源檢查

• 輔助檔案使用相對路徑連結
• 範本檔案可直接使用
• 無重複或冗餘內容

連結驗證 Link Verification

• 所有內部相對路徑連結目標檔案存在
• 連結路徑層級計算正確（./、../）
• 外部連結 URL 格式正確
• 無孤立連結（指向已刪除/移動的檔案）

相關連結 Related Links

• Agent Skills 官方文件
• Agent Skills 規範
• Anthropic Skills 範例庫
• Awesome Copilot Skills