## How to Create an Agent Skill**

*A step-by-step guide using Copilot CLI*

---

## What is an Agent Skill?

Agent Skill 就是寫給 AI 看的 **SOP**

傳統 SOP 是寫給「人」執行的作業流程，Agent Skill 就是寫給「AI Agent」執行的版本。
透過 `SKILL.md` 檔案告訴 Agent：何時啟動、如何一步步完成任務。

---

## SOP vs Agent Skill 對照

| 傳統 SOP | Agent Skill |
|----------|-------------|
| 適用情境 | `description`（何時觸發）|
| 執行步驟 | `## Steps`（怎麼做）|
| 注意事項 | `## When NOT to Use` |
| 需要的工具／資源 | `## Tools` |

---

## 三大組成元件

| 元件 | 說明 |
|------|------|
| `SKILL.md` | Markdown 指令文件，定義技能的行為與觸發條件 |
| `description` | 同時說明用途與觸發時機，Agent 讀取後決定是否啟用 |
| `Instructions` | 步驟式操作流程，Agent 逐步執行以完成目標 |

---

## Why Build Agent Skills?

**四大優勢**

**01 自動化重複工作**
將日常任務（報告、彙整、轉換格式）封裝成技能，一鍵完成。

**02 知識可重用**
撰寫一次即可在整個團隊或組織中共享，避免重複造輪子。

**03 精準觸發**
description 中清楚定義使用情境，確保 Agent 在正確時機啟用正確技能。

**04 模組化擴充**
技能可疊加組合，讓 Agent 處理更複雜、多步驟的任務。

---

## Prerequisites & Setup

**安裝步驟**

**Step 01 — 安裝 Copilot CLI**

brew install copilot-cli

**Step 02 — 登入**

copilot login

**Step 03 — 確認環境**

copilot --version

---

## 先安裝 skill-creator

在開始寫 Skill 之前，建議先安裝 **skill-creator**——一個專門幫你建立、優化、測試 Skill 的 Agent Skill。

**為什麼先裝？**

> 用 AI 來幫你寫給 AI 看的 SOP。

skill-creator 可以協助你：
- 把需求或 SOP 直接轉成 `SKILL.md`
- 優化 `description` 讓觸發更精準
- 對 Skill 進行效能評估（evals）

**Step 1 — 安裝 skill-creator**

add skill, name: skill-creator, source: https://github.com/anthropics/skills/tree/main/skills/skill-creator

> 來源：[github.com/anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/skill-creator)

**Step 2 — 開始建立 Skill**

/skill-creator create a new skill, name: my-skill, <這邊填寫你的需求 or SOP>

---

## SKILL.md – File Structure

**真實範例：`create-confident-test-cases`**

---
name: create-confident-test-cases
description: "Design high-quality RSpec test cases through structured
  AI-developer conversation. Usage: /create-confident-test-cases [JIRA-ID].
  Use when the user asks to write tests, design test cases, create specs,
  add test coverage, or mentions testing for any feature or bug fix.
  Also triggers on phrases like 'what should I test',
  'help me think about test scenarios', 'review my test coverage'..."
---

# Create Confident Test Cases

## Usage
/create-confident-test-cases OA-12345   # Fetch from Jira
/create-confident-test-cases            # Describe manually

## Goal
Help developers design test cases they can trust...

## Workflow
### Step 1: Gather requirements
### Step 2: Clarifying questions
### Step 3: Design test scenarios
...

**四大區塊說明**

| 區塊 | 說明 |
|------|------|
| Front Matter | `name` + `description` — description 同時定義用途與所有觸發情境 |
| Usage | 說明如何呼叫此技能，以及支援的參數格式 |
| Goal | 說明這份 SOP 的目標，對應 SOP 的「目的」 |
| Workflow / Steps | 具體的執行步驟，Agent 會依序完成每個動作 |

> **重點**：`description` 裡列出所有可能觸發的關鍵字與情境（中英文、各種說法）

---

## Best Practices

**建議做法（Do）**

- 一個技能只做一件事（單一職責，SOP 的基本原則）
- `description` 涵蓋常見同義詞與觸發情境
- 步驟描述精確、可執行（假設讀者是第一次看到這份 SOP）
- 加入 `## When NOT to Use` 段落，定義邊界
- 版本控管 `SKILL.md`（用 Git）

**避免做法（Don't）**

- 不要把多個不相關功能塞在同一技能
- 不要省略或寫太短的 `description`（這是觸發的關鍵）
- 不要使用模糊的步驟描述
- 不要忽略測試就直接部署

---

## Live Demo – 實作範例

**真實案例：用 skill-creator 建立 `create-confident-test-cases`**

> 不需要自己建資料夾、不需要手寫 SKILL.md。
> 透過 skill-creator 與 AI 對話，讓 AI 幫你寫出 Skill。

**Step 1 — 告訴 skill-creator 你的需求或 SOP**

create a new skill, name: create-confident-test-cases,

我想設計一個幫助開發者寫高品質 RSpec 測試的 Skill。
流程是：
1. 從 Jira ticket 或開發者描述收集需求
2. 透過提問釐清邊界條件
3. 平行從三種用戶視角設計測試情境
4. 合併去重後請開發者 review
5. 交付驗收清單

**Step 2 — 與 AI 互動確認細節**

skill-creator 會根據你的描述：
- 產出 `SKILL.md` 草稿
- 詢問觸發情境、邊界條件等細節
- 優化 `description` 讓觸發更精準

**Step 3 — 測試並持續迭代**

/create-confident-test-cases OA-12345

Skill 寫好後不是終點，而是迭代的開始：

測試 → 跟 AI 討論不足之處 → AI 修改 Skill → 測試 → ...

也可以用 skill-creator 的 **eval** 功能自動評估 Skill 的品質：

/skill-creator eval skill create-confident-test-cases

eval 會測試 Skill 的觸發準確度與執行品質，幫你找出需要改進的地方。

- 發現觸發不準確？告訴 skill-creator，它會優化 `description`
- 步驟有缺漏？描述給 AI，它會補充 SOP 內容
- Skill 越用越好，跟 SOP 一樣需要持續維護與改版

---

## Summary & Key Takeaways

**五大重點回顧**

1. **Agent Skill = AI 版的 SOP** — 會寫 SOP 就能設計 Agent Skill
2. `description` 同時定義用途與觸發時機，沒有獨立的 `triggers` 欄位
3. 遵循「單一職責 + 明確描述 + 具體步驟」三原則
4. 從小技能開始，測試驗證後再擴充為複雜工作流程

---

**Q & A｜歡迎提問**