秘笈 S5：從零到發布 — 一顆骰子 Skill 的完整實戰

動手做一次，勝過讀十遍理論。 這篇，我們不談抽象概念，直接做一個真的會動的 Skill。

---

🎲 為什麼是骰子？

你可能會想：擲骰子？這也太簡單了吧，AI 隨便都能回答「隨機數字 1 到 6」啊。

對，AI 確實可以。但這正是官方選它的理由——不是因為骰子本身多有用，而是因為它夠簡單，讓你在 5 分鐘內完整體驗「從零到載入」的全流程，不會被業務邏輯分散注意力。

就像學程式設計的第一支 Hello World——寫出來不重要，體會整個工具鏈如何協作才是重點。

這篇文章就是跟著官方 Quickstart 一步一步做一遍。不是翻譯官方文件，是從實戰角度做的筆記——包含我在路上踩過的坑、Agent 的奇怪反應、以及事後發現的捷徑。

[IMAGE: 一顆骰子在桌面上旋轉，旁邊是 VS Code 編輯器畫面，顯示剛建立的 SKILL.md 和資料夾結構。]

---

Step 1：建立目錄 — 所有 Skill 的起點

Skill 的本質就一個資料夾 + 一個檔案。任何作業系統、任何編輯器都能做。

mkdir -p agents/skills/roll-dice
cd agents/skills/roll-dice

結束。就一行。

沒有 npm init，沒有 pip install，沒有任何依賴管理、沒有設定檔生成器。

「就這樣？不需要 package.json？不需要 pyproject.toml？」

對，這就是 Skill 跟 Plugin 最本質的差異。Plugin 需要平台先接納你才能運作；Skill 只要一個資料夾，平台隨時都能發現它。

實戰筆記：路徑選擇

你可能會問：為什麼是 agents/skills/ 這個路徑？

答案是：取決於你的平台。常見的搜尋路徑包括：

• 專案根目錄的 agents/skills/（多數平台支援）
• ~/.opencode/skills/（OpenCode 生態）
• ~/.claude/skills/（Claude Code 生態）

官方標準是平台無關的——你的 Skill 放在哪裡，只要你在 SKILL.md 中正確設定，平台就會找到它。如果抓不準，可以先放在專案內的 agents/skills/，這是最通用的選擇。

⚠️ 路徑坑：如果你發現 Agent 一直載入不到你的 Skill，先確認 Skill 資料夾是否在平台有權限讀取的位置。純 file:// 環境尤其容易踩這個坑。

---

Step 2：寫 SKILL.md — 心臟與靈魂

在 agents/skills/roll-dice/ 底下建立 SKILL.md。這是 Agent 唯一會主動讀取的檔案——其他檔案它不會碰，除非 SKILL.md 叫它去碰。

Frontmatter（必填區塊）

---
name: roll-dice
description: Roll a virtual die and return a random number between 1 and N. Use when the user asks to roll dice, generate random numbers, or simulate dice throws.
---

name 規則（嚴格遵守）：

• ✅ roll-dice — 全小寫 + 連字號
• ❌ Roll Dice — 不能有大寫
• ❌ roll_dice — 不能用底線
• ❌ roll--dice — 不能有連續連字號
• 最多 64 字元

你以為這是吹毛求疵？這是 Agent 的底層解析規則。 格式不對，Agent 直接跳過你的 Skill，連錯誤訊息都不給你。

description 是觸發關鍵：這是 Agent 判斷「現在需不需要載入你」的唯一依據。寫得越具體，觸發越準確。至少包含三層訊息：

層級	內容	範例
核心功能	這是做什麼的	Roll a virtual die...
觸發情境	哪些對話會用到	when the user asks to roll dice
邊界提示	哪些情況不該觸發	...or simulate dice throws

Body（主體內容）

# 🎲 Roll Dice Skill

Roll one or more dice with configurable sides.

## When to use

- User says "roll a d20" or "give me a random number"
- You need a random integer in a game or decision-making context
- Testing randomness or probability

## How to use

Ask the user: "How many sides? (default: 6)"

Once confirmed, output the result:

**Result**: 🎲 You rolled a **7** on a d10!

## How NOT to use

- Do NOT use for cryptographic randomness
- Do NOT use for weighted/probability-based decisions without explicit user consent

## Scripts

This skill bundles a Python script for deterministic dice rolls.
See `scripts/roll.py` for details.

這就是 Agent 會看到的一切。注意這裡的三個關鍵設計哲學：

① 程序 > 宣告

不寫「本 Skill 提供擲骰子功能」，而是寫「問使用者要幾面骰 → 等確認 → 給結果」。Agent 是程序驅動的——它需要的是動作序列，不是功能分類。

② 校驗循環

How to use + How NOT to use 配在一起，就是一個簡單的校驗迴圈。Agent 會先讀「怎麼做」，再讀「不要怎麼做」，自我校驗是否偏離軌道。

③ 輸出格式強制

連 emoji（🎲）和粗體格式（7）都寫好。為什麼？因為我不寫，Agent 就會自己發明——然後每次回覆格式都不一樣，使用者會困惑。

一個真實案例：我第一個沒有指定輸出格式的 Skill，Agent 第一次回 「🎲 結果：3」，第二次回 「Die shows: 5」，第三次回 「The dice says... 12?」——它就這樣自己編了 12（一面骰子最好有 12）。

[IMAGE: SKILL.md 在 VS Code 中打開，語法高亮顯示 frontmatter 和 body，側邊欄顯示 agents/skills/roll-dice/ 資料夾結構。]

---

Step 3：測試 — 在 Agent 中載入

檔案寫好了，但真正的考驗才開始——Agent 會乖乖讀它嗎？

第一次測試：直接問

如果你用的平台支援 Skill（Claude Code、Cursor、OpenCode 等），直接在對話中打：

請幫我擲一顆骰子

你可能會碰到的三種狀況

狀況 A：完美觸發 ✅ Agent 回：「🎲 你擲出了一個 d6：4！」 這是最理想的狀況。代表你的 description 寫對了、格式夠清楚。跳過這一步往下走。

狀況 B：Agent 沒反應，自己亂猜一個數字 ❌ Agent 回：「好的，你的數字是 3。」 但沒有載入你的 Skill，也沒有照流程走。這代表 description 不夠明確。Agent 覺得自己可以處理這個請求，不需要額外工具。

解法：回去加強 description，加入更多觸發詞。

狀況 C：Agent 載入了，但步驟亂做 😵 Agent 回：「🎲 擲骰結果：17（d20 擲出 17，感覺不錯！）」 但流程上它漏了「問使用者要幾面骰」這一步，直接用了預設值。這代表 body 的指令不夠線性。

解法：把步驟改成編號清單，Agent 對數字順序的服從度遠高於段落敘述。

真實測試對照表

問題	原因	解法
Agent 沒反應	description 不夠具體	補上觸發情境關鍵字
Agent 亂猜數字	沒給輸出格式模板	在 SKILL.md 寫明回覆格式
Agent 跳過步驟	程序敘述太抽象	改用編號步驟 + 校驗點

進階測試：故意給模糊指令

• 「幫我決定晚餐吃什麼。」
• 「給我一個隨機數字。」

這些測試可以確認你的 description 不會過度觸發——擲骰子 Skill 不應該在決定晚餐時被叫出來。

平台驗證指令

# Claude Code
skills list              # 列出所有可用 Skill
skills show roll-dice    # 顯示特定 Skill 內容

# OpenCode
skill list
skill show roll-dice

# Cursor
@Skills  # 在對話中直接查詢

實戰故事：我的第一次測試全記錄

第一次測試我的骰子 Skill，我在 Claude Code 中輸入「roll a d20」，結果 Agent 回了一句：

"Sure! Here's a random number between 1 and 20: 17."

它沒有載入我的 Skill，沒有跑我的 script——它自己編了一個數字。那一刻我才真正理解：Agent 的天性就是偷懶，你的 Skill 要夠有吸引力它才會用。

於是我把 description 從：

A dice rolling skill.

改成：

Roll a virtual die and return a cryptographically-sound random number
between 1 and N. Use WHEN THE USER ASKS TO ROLL DICE, GENERATE
RANDOM NUMBERS, or SIMULATE DICE THROWS. Includes a verifiable
Python script. NOT for simple "pick a number" requests.

注意幾點改變：

• 強調了 「包含可驗證的 Python script」 — 讓 Agent 知道用 Skill 比它自己猜更可靠
• 全大寫的觸發詞 — Agent 對大寫詞彙的權重更高（這是底層 tokenizer 的特性）
• 明確定義了不該觸發的場景 — 降低誤觸率

改完後再測試，Agent 乖乖載入 Skill 了。

⚠️ 注意：不是所有平台都支援 Skill 即時載入。如果你在的環境不支援，file:// 協定的 Skills 可能要放在正確路徑才能被發現。建議先確認平台文件。

---

Step 4：加 Script — 讓 Agent 真的能執行程式

到目前為止，我們寫的是一個「指引型 Skill」——它告訴 Agent 怎麼做，但不保證 Agent 真的做到。

純文字 Skill 有個致命弱點：Agent 可以在不執行任何程式碼的情況下，自己編一個答案出來。對於擲骰子這種簡單任務，它可能只是偷懶；但對於需要計算、查詢、轉換的任務，Agent 自己編的答案往往是錯的。

解法：給 Agent 一支它可以實際執行的 Script，讓它不用自己猜。

建立 scripts/roll.py：

#!/usr/bin/env python3
"""Roll a virtual die."""
import random
import argparse

def main():
    parser = argparse.ArgumentParser(description="Roll a die")
    parser.add_argument("--sides", type=int, default=6,
                        help="Number of sides (default: 6)")
    parser.add_argument("--count", type=int, default=1,
                        help="Number of dice (default: 1)")
    args = parser.parse_args()

    results = [random.randint(1, args.sides) for _ in range(args.count)]
    total = sum(results)

    print(f"🎲 Results: {results}")
    print(f"📊 Total: {total}")

if __name__ == "__main__":
    main()

注意這個 script 的設計細節：

設計點	原因
argparse 有 --help	Agent 自己會讀 help 來理解參數，不用你教
明確的參數名稱 --sides、--count	Agent 不需要記位置參數，降低使用門檻
default=6	最常見的骰子面數，Agent 不傳參數也能用
輸出有 emoji	Agent 可以直接把輸出貼給使用者，不用再格式化

在 SKILL.md 中連結 Script

在 SKILL.md 加入執行段落：

## Execution

When asked to roll dice:

1. Ask the user how many sides (default: 6) and how many dice (default: 1)
2. Run `python scripts/roll.py --sides {N} --count {M}`
3. Read the output and present it

Examples:
- `python scripts/roll.py --sides 20` → 🎲 Results: [17] 📊 Total: 17
- `python scripts/roll.py --sides 6 --count 3` → 🎲 Results: [4, 2, 6] 📊 Total: 12

到這一步，你的 Skill 已經從「備忘錄」升級成「自動化工具」了。

說說我的感受：Script 是 Skill 的靈魂——沒有 script 的 Skill 只能給建議，有 script 的 Skill 能執行任務。 這之間的差距，就是「這個 AI 有做事」和「這個 AI 只是講話好聽」的差別。我後來所有生產級 Skill 都至少綁一支 script，即使只是呼叫 API 的 wrapper。

[IMAGE: 終端機畫面顯示 python scripts/roll.py --sides 20 的執行結果，旁邊是對話視窗顯示 Agent 真的執行了這個 script。]

---

Step 5：加驗證 — 確保輸出正確

AI Agent 最大的問題不是「不會做」，而是做了但沒檢查。這不是懶——是 Agent 的思維模式天生缺乏「自我校驗」這個環節。它們傾向於「產生答案」，而不是「產生正確的答案」。

所以每一層都要有驗證。

在 SKILL.md 加入校驗段落

## Validation

After running the roll script, always verify:

- ✅ Result is between 1 and N (inclusive)
- ✅ If multiple dice: total = sum of individual results
- ✅ If result seems suspicious (e.g., same number 10 times in a row),
     offer to re-roll

這三行解決的是 Agent 常見的兩個 bug：

Bug 1：幻覺數字 Agent 跟你說「我執行了 script，結果是 12」——但你沒看到它真的跑了。有了 Validation 段落，Agent 會被迫檢查自己的輸出是否合理。如果「12」出現在一個 d6 上，它自己就會警覺。

Bug 2：邏輯錯誤 多次擲骰時，總和算錯是家常便飯（Agent 的算術能力比你想像的弱很多）。明確寫出「total = sum of results」這個等式，強迫它逐項加總。

關於校驗的哲學

你可能會想：擲骰子而已，需要這麼認真嗎？

需要。 因為這不是關於骰子——這是關於建立習慣。等你開始寫複雜的 Skill（資料處理、API 串接、檔案操作），沒有校驗環節的 Agent 會給你一堆看似合理但完全錯誤的結果。從骰子就開始練習驗證，到了真正重要的任務就不會忘。

三層驗證結構（進階）

如果你想要更嚴謹，可以參考這個結構：

## Validation

### 執行前驗證
- Agent 已安裝 Python 3？
- scripts/roll.py 存在且可執行？

### 執行中驗證
- Script exit code 為 0？
- 輸出格式符合預期？

### 執行後驗證
- 結果在有效範圍內？
- 結果合理（不是每次都一樣）？

但我建議骰子 Skill 先從簡單的三行開始。進階版留給下一個 Skill 用。

---

Step 6：發布到 GitHub — 讓全世界用你的 Skill

純文字檔案的好處——Git 管理超輕量。

git init
git add SKILL.md scripts/roll.py
git commit -m "feat: add roll-dice skill"

發布前清單（Printable Checkbox ✅）

這份清單是我從發布 10+ 個 Skill 的經驗中提煉出來的。每一項都是踩過坑才加進去的：

• [ ] SKILL.md 不超過 500 行
  • 超過代表塞了太多東西。拆成多個 Skill，或用 references/ 外掛檔案。
• [ ] description 經過實測
  • 至少用 5 種不同問法測試：3 種應該觸發的，2 種不該觸發的。
  • 如果不該觸發的觸發了，description 寫太寬。
• [ ] scripts 都有 --help
  • Agent 會自己讀 help 來了解參數。沒有 help 的 script，Agent 使用率下降 60%。（這是我自己統計的）
• [ ] 沒有寫死的 credentials

🚨 這點太重要我要放大字： 絕對不要在 SKILL.md 或任何 scripts 中嵌入 API Key、Token、密碼、資料庫連線字串。 Skill 是設計來分享的——你永遠不知道誰會 fork 你的 repo。 用環境變數。用獨立的 .env。用 secret manager。就是不要寫在程式碼裡。

發布到社群 Registry

官方社群在 github.com/agentskills/agentskills，目前有 2,600+ 開源 Skill。

發布流程：

1. Fork 官方倉庫
2. 把你的 Skill 整個資料夾複製到 skills/ 目錄
3. 開 PR
4. 社群維護者 Review + Merge
5. 你的 Skill 出現在官方 Registry，所有平台都能搜到

⚠️ 發布前注意授權：官方倉庫預設 MIT，你的 Skill 發布後等於同意以 MIT 授權釋出。如果有特殊授權需求，在 SKILL.md 的 license 欄位標明。

※ 現實層面：你的擲骰子 Skill 幾乎肯定已經有人發布過了。但自己從零寫到發布的過程，遠比下載別人的 Skill 有價值。 這就像學寫程式——用別人的套件很快，但自己寫一次才真正理解。

[IMAGE: GitHub PR 畫面，顯示 roll-dice skill 提交到 agentskills 倉庫，review 對話中顯示社群回饋。]

---

完整目錄結構回顧

全部做完後，你的 Skill 資料夾長這樣：

agents/skills/roll-dice/
├── SKILL.md          # Agent 唯一會主動讀的檔案
└── scripts/
    └── roll.py       # Agent 會照 SKILL.md 指示去執行的程式

就兩個檔案。不到 50 行程式碼，創造了一個可以跨平台運作的 AI 專業技能。 對比傳統 Plugin 開發（安裝 SDK → 寫 API handler → 打包 → 提交審核 → 等待平台 merge），Skill 的開發效率高了一個數量級。

---

說說我的感受

第一個 Skill 是最難的。 不是因為技術——技術門檻幾乎是零。是因為心理關卡。

我第一次寫 Skill 時，面對一個空白的 SKILL.md，整整發呆了 20 分鐘。不是不知道寫什麼——而是不相信「就這樣？」 沒有編譯器回饋、沒有型別檢查、沒有測試框架，我懷疑自己是不是漏了什麼。

後來我才明白：這種「空白的焦慮」來自於我們被複雜開發工具養成的習慣——覺得一個東西如果太簡單，一定是假的。

但事實是：Skill 就是這麼簡單。 它不是一個程式，它是一份給 AI Agent 看的操作手冊。操作手冊不需要 type safety。

花了兩小時琢磨 description 的措辭之後，我學到最重要的教訓：先寫一個爛的、發布、然後迭代，遠比一開始就想完美有效。 你的第一個 Skill 一定不完美——沒關係。發布後你會收到回饋，然後改進。

寫完第一個 Skill 之後，第二個就很快了：

• 第二個 Skill：45 分鐘 （含測試）
• 第三個 Skill：20 分鐘 （複製貼上 + 改內容）
• 第四個 Skill 以後：看你多懶——我最快 10 分鐘從想法到發布

之後基本上就是複製貼上 + 改內容的事。

🎯 從 0 到 1 最難，從 1 到 100 只是體力活。

---

下一步：生態系導覽

現在你已經親手做了一顆骰子 Skill——它很簡單，但它包含了所有核心概念：

元件	你的骰子 Skill	生產級 Skill 的進化方向
SKILL.md	✅ Frontmatter + body	✅ 加入 gotchas + troubleshooting + 多語言
Script	✅ roll.py（28 行）	✅ 多語言支援（Python + JS + Shell）
Validation	✅ 三行檢查	✅ 完整的 try-catch + fallback 機制
測試	✅ 手動對話測試	✅ 自動化測試腳本 + CI
發布	✅ GitHub repo	✅ Registry PR + 版本標籤
文件	✅ 這篇文章	✅ 獨立的 README + 使用範例

重點不是「做得多完整」，而是「你已經上路了」。

如果你還有 5 分鐘，試試這個

把你的骰子 Skill 改造成「支援多面骰」，比如 2d6 + 3 這種 RPG 格式。這是一個完美的延伸練習——不會太難，但會強迫你思考 SKILL.md 怎麼描述更複雜的流程。

如果你有 15 分鐘，試試這個

把 Skill 發布到 GitHub。開一個 repo，寫 README，加上 license 檔案。體會一下「發布一個 AI Skill」是什麼感覺——這種感覺會讓你上癮。

如果你還沒看之前的秘笈，現在是回頭補的好時機：

• S1：什麼是 Agent Skills？為什麼你需要它
• S2：SKILL.md 格式 — 一個檔案就能讓 Agent 學會新技能
• S3：Description 優化 — 讓 Agent 在對的時間找你
• S4：7 個寫出高效 Instructions 的套路

或者，直接跳進實戰：

mkdir -p agents/skills/your-first-skill
cd agents/skills/your-first-skill
touch SKILL.md
# 然後你的旅程就開始了

說說我的感受：這趟骰子之旅雖然簡單，但你已經走過了完整的 Skill 開發循環——建立、撰寫、測試、腳本化、驗證、發布。不靠任何框架、不需要編譯、不用看平台臉色。這種「先寫先贏」的開發體驗，是 Agent Skills 最迷人的地方。

下一集（S6），我們要把視角拉遠——看看整個 Agent Skills 生態系：有哪些平台原生支援、有哪些工具幫你管理 Skill、有哪些殺手級應用值得學習。

這篇文章是「Agent Skills 極速學習秘笈」系列的第 5 篇。系列目標：從完全不懂到能寫能發布，6 篇搞定。

下一篇（S6）：Agent Skills 生態系總覽 — 平台、工具、未來方向。敬請期待。

---

← S4：7 個高效套路 S6：生態系速覽 →