Part 7B:SKILL.md 撰寫教學

三大組成部分:Frontmatter、Description、Instructions

YAML 格式 觸發關鍵字 步驟撰寫 指令詞

曾慶良(阿亮老師) | AI 協作簡報實戰工作坊

📝 SKILL.md 的三大部分

🪪

1. Frontmatter

技能的「身分證」

YAML 格式
定義 name 和 description

📋

2. Description

給人類閱讀的簡介

說明這個 Skill
能做什麼事情

📜

3. Instructions

給 AI 執行的步驟

詳細的操作指令
與執行流程

---
name: my-skill-name              ← Frontmatter 開始
description: "觸發關鍵字..."      ← description 決定何時觸發
---                              ← Frontmatter 結束

# My Skill                       ← 標題(給人看的)

這個 Skill 的功能說明...          ← Description 區

## Instructions                  ← Instructions 區開始

### Step 1: 詢問使用者
1. Ask user for project name
2. Ask user for description
...

🪪 Frontmatter 詳解(YAML 格式)

📄 基本格式

---
name: project-initializer
description: "Initialize new projects.
Triggers: init project, 初始化專案,
create project, setup project."
---

📌 兩個必要欄位

欄位說明
name技能的唯一識別名稱
(英文小寫 + 短橫線)
description觸發關鍵字描述
決定 AI 何時觸發!

⚠️ 常見錯誤

錯誤 1:冒號後沒空格
name:my-skill  ❌ 錯誤
name: my-skill ✅ 正確
錯誤 2:減號數量錯誤
--    ❌ 只有兩個
---   ✅ 三個減號(正確)
----  ❌ 四個減號
💡 提示:可用線上 YAML 驗證器檢查格式是否正確

📋 Description 怎麼寫最有效?

🔥 超級重要!description 欄位決定了 AI 何時會自動觸發這個 Skill

✍️ 撰寫技巧(中英文混用最好!)

  • 列出動作詞:
    create, build, generate, make, design, fix, review
  • 列出主題詞:
    website, landing page, dashboard, chat, API
  • 加入中文:
    建立、生成、製作、聊天室、專案、初始化
關鍵字越多,觸發率越高!

❌ 不好的範例

"A skill for chat."

↑ 太簡短,AI 很難判斷何時使用

✅ 好的範例

"Initialize new projects with
standard files.
Triggers: init project, 初始化,
create project, setup project,
建立專案.
Creates: README.md, .gitignore,
package.json"

📜 Instructions 撰寫三大原則

🏗️

1. 結構清楚

  • 用標題 ## 分段
  • 用編號 1. 2. 3. 列步驟
  • 每個 Step 一個明確任務
🎯

2. 指令明確

  • 指定工具:read_file
  • 指定路徑:resources/xxx
  • 指定動作:replace, create
🔄

3. 邏輯完整

  • 考慮各種情況
  • 加入條件判斷
  • 加入錯誤處理
## Instructions

### Step 1: Gather Information
1. Ask user for project name (MUST be lowercase with hyphens)
2. Ask user for project description

### Step 2: Create Files
1. Read template from resources/readme-template.md
2. Replace {{PROJECT_NAME}} with user's project name
3. Write the file to ./README.md

### Step 3: Verify and Report
1. Check if all files were created successfully
2. Display a summary to the user

🔑 給 AI 的關鍵指令詞(超重要!)

指令詞 用途 範例
MUST / 必須 強調不可省略的步驟 必須先確認使用者已建立 Firebase 專案
Check if / 先檢查 執行前的驗證 先檢查資料夾是否存在
Ask user / 詢問使用者 需要使用者輸入時 詢問使用者專案名稱和描述
If...then / 如果...就 條件判斷 如果檔案已存在,先詢問是否覆蓋
NEVER / 禁止 防止危險操作 禁止在未確認前刪除檔案
After completing / 完成後 收尾步驟 完成後顯示建立的檔案清單
💡 提示:中英文都可以使用!AI 都能理解。混用效果最好。

📄 完整 SKILL.md 範例

---
name: project-initializer
description: "Initialize new projects with standard files.
Triggers: init project, 初始化專案, create project, setup project, 建立專案.
Creates: README.md, .gitignore, package.json with customized content."
---

# Project Initializer

This skill creates standard project files with customized content.

## Instructions

### Step 1: Gather Information
1. Ask user for the project name (MUST be lowercase, use hyphens for spaces)
2. Ask user for a brief project description (1-2 sentences)

### Step 2: Create README.md
1. Read the template from `resources/readme-template.md`
2. Replace `{{PROJECT_NAME}}` with the user's project name
3. Replace `{{PROJECT_DESCRIPTION}}` with the user's description
4. Write the result to `./README.md`

### Step 3: Create .gitignore
1. Read the template from `resources/gitignore-template.txt`
2. Write the content to `./.gitignore` (no modifications needed)

### Step 4: Create package.json
1. Read the template from `resources/package-template.json`
2. Replace `{{PROJECT_NAME}}` and `{{PROJECT_DESCRIPTION}}`
3. Write the result to `./package.json`

### Step 5: Report Completion
1. List all created files
2. Show a brief summary of what was set up
3. NEVER delete or overwrite existing files without user confirmation

📊 SKILL.md vs README.md 的差異

項目 README.md(傳統方式) SKILL.md(進階方式)
用途 給人類閱讀的專案說明 給 AI 執行的操作手冊
觸發方式 手動貼給 AI 看 AI 自動偵測並觸發
格式要求 自由格式 需要 YAML Frontmatter
放置位置 專案根目錄 .agent/skills/ 或 .claude/skills/
可擴展性 單一檔案 可搭配 scripts/data/resources
💡 結論:SKILL.md 是 README.md 的「進化版」,專為 AI 協作設計!

📋 Part B 重點回顧

📝 SKILL.md 三大部分

  • Frontmatter:name + description(YAML 格式)
  • Description:給人類看的功能說明
  • Instructions:給 AI 執行的步驟

🔑 關鍵技巧

  • description 要包含多個觸發關鍵字
  • 中英文混用觸發率最高
  • 善用 MUST / NEVER / Ask user 指令詞
  • 步驟要結構清楚、指令明確

⚠️ 常見錯誤提醒

  • YAML 冒號後要有空格:name: my-skill
  • 前後要用三個減號:---
  • description 太簡短會導致無法觸發

🎉 Part B 完成!

你已經學會撰寫 SKILL.md 了

接下來學習進階資料夾結構:scripts / data / resources