AI Coding Assistant Skill Tutorial

Part 2: 學習撰寫

解構 SKILL.md：如何寫出 AI 看得懂、執行完美的操作手冊

Google Antigravity

Claude Code

YAML Frontmatter Markdown Instructions scripts / data / resources

SKILL.md 的完整結構

一個完整的 Skill 文件包含三個主要部分：

1

Frontmatter (YAML 檔頭)

技能的「身分證」- 定義名稱與觸發描述

2

Description (描述區)

給人類閱讀的簡介，說明這個技能做什麼

3

Instructions (指令區)

給 AI 執行的具體步驟與邏輯

重點：AI 會先讀 Frontmatter 判斷是否呼叫，然後依照 Instructions 一步步執行！

Frontmatter (檔頭) 詳解

位於檔案最上方，用三個短橫線 --- 包起來的 YAML 區塊：

---
name: my-skill-name
description: "這裡寫技能的簡短描述，AI 會根據這個判斷要不要呼叫這個技能。關鍵字很重要！"
---

兩個必要欄位

欄位	說明	範例
`name`	技能的唯一識別名稱（用英文小寫與短橫線）	`flask-app-generator`
`description`	觸發關鍵字描述（最重要！AI 靠這個決定是否呼叫）	`"Generate Flask web apps..."`

注意：description 的內容決定了 AI 什麼時候會自動呼叫你的 Skill！

description 怎麼寫最有效？

description 要包含所有可能的觸發關鍵字，讓 AI 知道何時該呼叫：

撰寫技巧（中英文都可以！）

列出相關動作：
英文：create, build, generate, make, design, fix, review...
中文：建立、產生、設計、修復、檢查、初始化...
列出相關主題：
英文：website, landing page, dashboard, chat, API...
中文：網站、聊天室、表單、資料庫、即時通訊...
中英文混用效果最好！讓使用者用中文或英文都能觸發

範例對比

X 不好的寫法

description: "Flask generator"

太簡略，AI 可能無法正確判斷

O 好的寫法（中英文混用）

description: "Build Firebase chat room. Actions: create chat, 建立聊天室, 即時通訊. Tech: Firebase Auth, Firestore, Google Login."

中英文都能觸發，命中率最高！

Instructions 撰寫原則

Instructions 是給 AI 的執行劇本，使用 Markdown 格式撰寫：

三大原則

1. 結構清楚

用標題 (##) 分段
用編號 (1. 2. 3.) 列步驟

2. 指令明確

告訴 AI 用什麼工具
read_file, write_to_file, run_command

3. 邏輯完整

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

# 技能說明
本技能將協助使用者建立一個標準的 Flask 專案。

## Step 1: 詢問使用者
Ask user for the project name. If not provided, use "my-app" as default.

## Step 2: 建立目錄
使用 run_command 執行：mkdir -p {project_name}/templates

## Step 3: 建立主程式
使用 write_to_file 建立 app.py...

給 AI 的關鍵指令詞（中英文皆可）

使用這些魔法詞彙可以精確控制 AI 的行為：

"你必須..." / "You MUST..."

必須執行 - 強調不可省略的步驟
例：你必須先確認使用者已建立 Firebase 專案

"先檢查..." / "Check if..."

先檢查 - 執行前的驗證
例：先檢查資料夾是否存在

"詢問使用者..." / "Ask user..."

詢問使用者 - 需要輸入時
例：詢問使用者專案名稱和描述

"如果...就..." / "If...then..."

條件判斷 - 根據情況做不同處理
例：如果檔案已存在，就先詢問是否覆蓋

"禁止..." / "NEVER..."

禁止動作 - 防止危險操作
例：禁止在未確認前刪除檔案

"完成後..." / "After completing..."

完成後動作 - 收尾步驟
例：完成後顯示建立的檔案清單

技巧：中文或英文都可以！AI 都看得懂。用「必須」「禁止」等強調詞讓 AI 更重視！

scripts 資料夾的用途

放置 Python 腳本，讓 AI 透過 run_command 執行複雜邏輯：

# 資料夾結構
my-skill/
  |- SKILL.md
  |- scripts/
       |- search.py      # 搜尋資料的腳本
       |- generate.py    # 生成內容的腳本
       |- validate.py    # 驗證輸入的腳本

使用方式（在 SKILL.md 中）

## Step 3: 搜尋相關資料
使用 run_command 執行 Python 腳本：

```bash
python scripts/search.py --keyword "{{user_keyword}}"
```

將搜尋結果用於後續生成步驟。

適用場景：資料處理、API 呼叫、檔案批次處理、複雜計算等

data 資料夾的用途

存放 CSV、JSON 等資料檔，供 Python 腳本查詢使用：

# 資料夾結構
my-skill/
  |- SKILL.md
  |- scripts/
       |- search.py
  |- data/
       |- styles.csv       # UI 風格資料
       |- templates.json   # 模板設定檔
       |- keywords.txt     # 關鍵字清單

CSV 資料範例 (styles.csv)

name,primary_color,font,description
modern,#3498db,Inter,現代簡約風格
classic,#2c3e50,Georgia,經典傳統風格
playful,#e74c3c,Comic Sans,活潑有趣風格

好處：將資料與邏輯分離，方便維護與擴充！
例如新增一種風格，只需要編輯 CSV，不用改程式碼。

resources 資料夾的用途

存放模板檔案（HTML、JSON、Markdown 等），AI 讀取後填入參數：

# 資料夾結構
my-skill/
  |- SKILL.md
  |- resources/
       |- template.html    # HTML 模板
       |- config.json      # 設定檔模板
       |- readme.md        # README 模板

模板範例 (template.html)

<!DOCTYPE html>
<html>
<head>
    <title>{{project_title}}</title>
    <style>
        body { background: {{primary_color}}; }
    </style>
</head>
<body>
    <h1>{{welcome_message}}</h1>
</body>
</html>

在 SKILL.md 中指示 AI：
"Read the template from resources/template.html, replace all {{placeholders}} with user-provided values, then write to output."

完整的 SKILL.md 範例

以下是一個簡單但完整的 Skill 範例：

---
name: greeting-generator
description: "Generate greeting cards. Actions: create greeting, make card, generate wish. Topics: birthday, wedding, holiday, new year, christmas."
---

# Greeting Card Generator

本技能用於生成各種祝賀卡片。

## How to Use

### Step 1: Ask User
詢問使用者以下資訊：
1. 卡片類型（生日 birthday / 婚禮 wedding / 節日 holiday）
2. 收件人名稱
3. 想要的風格（正式 formal / 溫馨 warm / 幽默 funny）

If user doesn't specify, use default: birthday, "朋友", warm.

### Step 2: Generate Message
根據使用者輸入生成適合的祝賀訊息。
You MUST include the recipient's name in the message.

### Step 3: Create Card
使用 write_to_file 建立 HTML 卡片：
- 檔名格式：greeting_card_{type}.html
- 套用對應的顏色主題
- 將祝賀訊息放入卡片中

### Step 4: Confirm
完成後告知使用者檔案位置，並詢問是否需要修改。

常見錯誤與解決方法

錯誤 1: YAML 格式錯誤

X 錯誤

---
name:my-skill    # 冒號後沒空格
description:"..."  # 冒號後沒空格
---

O 正確

---
name: my-skill    # 冒號後要空格
description: "..."  # 冒號後要空格
---

錯誤 2: description 不夠詳細

問題：description 只寫 "A useful tool"
結果：AI 不知道何時該呼叫這個 Skill
解法：列出所有相關的動作詞與主題詞

錯誤 3: 步驟不清楚

問題："建立檔案然後完成"
結果：AI 不知道要建什麼檔案、存在哪裡
解法：明確指定檔名、路徑、內容格式

Part 2 總結

現在你已經掌握了 SKILL.md 的完整撰寫技巧：

YAML Frontmatter

name + description
技能的身分證與觸發條件

Markdown Instructions

結構化的執行步驟
清楚的條件與邏輯

輔助資料夾

scripts / data / resources
讓 Skill 更強大

關鍵指令詞

MUST / NEVER / Check if
精確控制 AI 行為

好的 description

列出動作詞與主題詞
提高觸發命中率

避免常見錯誤

YAML 格式正確
步驟具體明確

準備好了嗎？讓我們動手實作一個真正的 Skill！

前往 Part 3：實作練習