寫第一個 Skill

不寫程式，只跟 Claude 對話。skill-creator 帶你走完。

課程目標

認識部門 skill skill-creator：你的 skill 編寫教練
學會兩種寫作模式：vibe 模式（快速）vs eval 模式（嚴謹）
親手走完一次「從候選到 SKILL.md」的流程
看懂 Quality Gates——怎麼自我檢查 skill 寫得好不好

一、寫 skill 不需要寫程式

第 1 課就講過——SKILL.md 是自然語言寫的。

但「自然語言寫指示」聽起來簡單，做起來會卡：

「我該寫多細？」
「這段是不是該丟 references/？」
「description 寫得好不好？」

這時候 skill-creator 上場。它不是自動寫 skill 的 AI，它是陪你寫 skill 的教練——它會問你問題、給你模板、檢查你寫得好不好。

二、skill-creator 的對話流程

跑 /skill-creator 後，它會帶你走 5 個階段：

階段 1：Capture Intent（抓意圖）

它會問你：

這個 skill 應該讓 Claude 做什麼？
什麼時候該觸發？（用戶的哪些話 / 哪些情境）
預期輸出格式是什麼？
要不要設置測試案例？

新手提示：第 4 題你可以先說「不要」——走 vibe 模式（下面解釋）。

階段 2：Interview & Research（深入訪談）

它會問細節：

邊界場景有哪些？
輸入輸出格式長怎樣？
有沒有可以參考的範例？
跟哪些既有 skill 可能重疊？

新手提示：誠實回答。如果你不知道某個邊界場景，就說「我也沒想過，先放著」——第 8 課會教你怎麼後續補上。

階段 3：Write SKILL.md（草稿）

skill-creator 根據你的回答幫你草擬一份 SKILL.md。

frontmatter 自動填好
body 結構照部門 SKILL_CONVENTION.md
你看完後可以修改

階段 4：Run Test Cases（跑測試）— 進階

如果你選了「要設置測試案例」，它會：

寫 2-3 個測試 prompt
跑 with-skill 和 without-skill 對照
給你看效果差異

新手提示：第一次寫 skill 不要走這條——直接 vibe 模式。

階段 5：Iterate（迭代改進）

根據你的回饋改 SKILL.md，直到你滿意。

三、Vibe 模式 vs Eval 模式

Vibe 模式（推薦給第一次寫的人）

流程：

跟 skill-creator 對話
它幫你草擬 SKILL.md
你看一下、改一下
直接用——在實際工作中跑跑看
不滿意再回來改

特點：

快——半小時可以寫完一個簡單 skill
沒有正式測試
靠實戰使用累積回饋

適合：

第一次寫 skill 的人
個人用 skill（不上 PR 給部門）
簡單流程（< 5 步驟）

Eval 模式（進階，等你寫過 3-5 個 skill 後再玩）

流程：

跟 skill-creator 對話
設置 evals（測試案例 + 預期輸出）
跑 with-skill / without-skill 對照
看 quantitative 數據（pass rate / token / time）
看 qualitative 結果（你覺得輸出好不好）
改 SKILL.md → 再跑一輪
直到 pass rate 穩定

特點：

慢——一個 skill 可能要花半天到一天
有量化指標
適合上 PR 給部門共享

適合：

重要 skill（部門共用）
有「正確答案」的 skill（資料處理 / 格式轉換）
你想參加部門 skill ratchet（skill-optimize 跑分）

四、實戰：寫一個 `weekly-report` skill

我們走一遍完整流程，假設你要寫部門「週報草稿生成器」。

Step 0：準備候選（從第 5 課的 mining）

候選描述：每週五寫週報，3 段式（本週完成 / 下週計畫 / 阻塞）
訊號：每週 1 次（重複工作 + 抱怨型）
frequency × stability: 中-高
三門診斷：Skill（多步 + 你在迴圈裡）

Step 1：跑 `/skill-creator`

你：/skill-creator
Claude：好的，要做什麼 skill？
你：週報草稿生成器
Claude：好。讓我問你幾個問題：

1. 該讓 Claude 做什麼？
你：掃我這週的 git log + memhall episode，整理成 3 段：本週完成 / 下週計畫 / 阻塞，可以貼進 Slack 或 Email。

2. 什麼時候觸發？
你：當我說「寫週報」「weekly report」「禮拜五的報告」「跟主管交差」時。

3. 預期輸出格式？
你：Markdown，3 段，每段 bullet list，總長 < 500 字。

4. 要不要設測試案例？
你：先不要，走 vibe 模式。

Step 2：skill-creator 草擬 SKILL.md

它會產出類似這樣：

---
name: weekly-report
description: "週報草稿生成器。掃描本週 git log + memhall episode，整理成「本週完成 / 下週計畫 / 阻塞」三段式週報，總長 < 500 字。當用戶說「寫週報」「weekly report」「禮拜五的報告」「跟主管交差」「整理本週進度」時使用。不適用於月報或季報。"
version: 0.1.0
author: "@yourname"
tags:
  - workflow
  - report
status: experimental
allowed-tools:
  - Bash(git*)
  - mcp__team-memhall__search_entries
  - Read
---

# /weekly-report — 週報草稿生成器

## 目標
每週五讓你 5 分鐘寫完週報，不用回想做了什麼。

## 不適用場景
- 月報 / 季報（用 monthly-report）
- 不是這週的工作（請手動）
- 不在 git repo（會降級為純 memhall mode）

## 輸入
- 本週的 git log（自動撈）
- 本週 memhall episode（自動撈）
- 用戶口述「下週計畫」+「阻塞」

## 步驟

### Step 1: 撈本週資料
跑 `git log --since='1 week ago' --all --oneline` 撈 commit。
查 memhall: namespace=shared, since 7 天，type=episode。

### Step 2: 整理「本週完成」
從 git log 提取主要 commit，加上 memhall 的關鍵決策。
用 bullet 列 5-8 條。

### Step 3: 問用戶「下週計畫」
直接問：「下週重點是什麼？」用戶回答後整理 3-5 條 bullet。

### Step 4: 問用戶「阻塞」
直接問：「目前有什麼卡住？」整理 1-3 條 bullet。

### Step 5: 輸出

本週完成

下週計畫

阻塞


## Quality Gates
- [ ] 三段都有內容（不能空）
- [ ] 總長 < 500 字
- [ ] 沒有公司敏感字串（客戶實名 / 金額 / 內部 token）

## 治理邊界
- 此 skill v0.1 experimental，個人用
- 寫好後可考慮上 PR 到 team-skill-lab

Step 3：你看一下、改一下

skill-creator 給的草稿不會 100% 完美。你檢查：

description 觸發詞夠不夠？想想「我累的時候會怎麼說這件事？」
步驟太簡略嗎？某個 step 是不是該拆 2 個？
Quality Gates 漏了什麼？

Step 4：實戰用一次

下個週五你說「寫週報」——看 skill 跑出來的結果。

如果結果好 → 不用改
如果結果有點怪（例如忘了某類資料）→ 回去補 Step 1
如果完全不觸發（你說「禮拜五的報告」它沒反應）→ description 觸發詞不夠 pushy，加更多

Step 5：迭代 1-2 次

通常用 3-5 次就會穩定。穩定後 status 從 experimental 改 active。

五、Quality Gates — 自我檢查清單

寫完 skill，問自己這 8 個問題（部門 SKILL_CONVENTION.md 標準）：

#	問題	OK 標準
1	我有沒有實際用過？	至少在 2-3 個任務測試過
2	它做的事情夠專注嗎？	一個 skill 解決一類問題，不混
3	description 有具體觸發詞嗎？	至少 4 個觸發詞
4	步驟具體嗎？	不是「跟用戶討論」這種模糊指示
5	有寫輸入輸出嗎？	都明確列出
6	有寫不適用場景嗎？	至少 2-3 條
7	有沒有敏感資訊？	沒 API key / 客戶名 / 金額 / 內部 IP
8	body 行數合理嗎？	< 150 行（中型 skill）

任一條不過 → 不該宣稱 skill 完成。

六、Frontmatter 範本（可以複製貼上）

---
name: <kebab-case-name>
description: "<一句話功能>。<具體做什麼>。當用戶說「A」「B」「C」「D」時使用。<不適用場景>。"
version: 0.1.0
author: "@<your-github-handle>"
tags:
  - <category>
  - <subcategory>
argument-hint: "[選填: ...]"
allowed-tools:
  - Read
  - Bash(git*)
  - <其他需要的工具>
status: experimental
---

把它存到 ~/Templates/SKILL_TEMPLATE.md 當你的快速範本。

七、結論

skill-creator 是寫 skill 的對話教練，不是自動寫 skill
第一次寫 → vibe 模式（快），3-5 個 skill 後再玩 eval 模式
流程：候選 → skill-creator 訪談 → 草擬 → 改 → 實戰 → 迭代
Quality Gates 8 條，任一不過就不算寫完
下一課我們學「避坑」——新手最容易踩的 5 個雷

AI 協作：學了這個，跟 AI 怎麼配合？

skill-creator 是設計給「你跟 AI 對話寫 skill」的工具——它不是要你獨自硬寫。但 AI 不知道你工作的真實流程，所以訪談階段的回答品質決定 SKILL.md 品質。

你的人類優勢：

你知道你工作的隱性步驟（例如「打開 Slack 之前要先確認 VPN 連上」）——這些 AI 永遠猜不到
你知道哪些 edge case 你真的會遇到，哪些是 AI 想出來但你一輩子不會碰的

可以這樣跟 AI 說：

我要寫一個 skill 叫 [名稱]。我接下來會描述流程，請扮演 skill-creator 訪談我——一次只問一個問題，不要假設我已經想清楚。當我說「我不確定」時，請問更具體的子問題，不要直接幫我決定。

寫第一個 Skill

課程目標

一、寫 skill 不需要寫程式

二、skill-creator 的對話流程

階段 1：Capture Intent（抓意圖）

階段 2：Interview & Research（深入訪談）

階段 3：Write SKILL.md（草稿）

階段 4：Run Test Cases（跑測試）— 進階

階段 5：Iterate（迭代改進）

三、Vibe 模式 vs Eval 模式

Vibe 模式（推薦給第一次寫的人）

Eval 模式（進階，等你寫過 3-5 個 skill 後再玩）

四、實戰：寫一個 `weekly-report` skill

Step 0：準備候選（從第 5 課的 mining）

Step 1：跑 `/skill-creator`

Step 2：skill-creator 草擬 SKILL.md

本週完成

下週計畫

阻塞

Step 3：你看一下、改一下

Step 4：實戰用一次

Step 5：迭代 1-2 次

五、Quality Gates — 自我檢查清單

六、Frontmatter 範本（可以複製貼上）

七、結論

AI 協作：學了這個，跟 AI 怎麼配合？

練習題

挑戰任務

寫第一個 Skill

課程目標

一、寫 skill 不需要寫程式

二、skill-creator 的對話流程

階段 1：Capture Intent（抓意圖）

階段 2：Interview & Research（深入訪談）

階段 3：Write SKILL.md（草稿）

階段 4：Run Test Cases（跑測試）— 進階

階段 5：Iterate（迭代改進）

三、Vibe 模式 vs Eval 模式

Vibe 模式（推薦給第一次寫的人）

Eval 模式（進階，等你寫過 3-5 個 skill 後再玩）

四、實戰：寫一個 weekly-report skill

Step 0：準備候選（從第 5 課的 mining）

Step 1：跑 /skill-creator

Step 2：skill-creator 草擬 SKILL.md

本週完成

下週計畫

阻塞

Step 3：你看一下、改一下

Step 4：實戰用一次

Step 5：迭代 1-2 次

五、Quality Gates — 自我檢查清單

六、Frontmatter 範本（可以複製貼上）

七、結論

AI 協作：學了這個，跟 AI 怎麼配合？

練習題

挑戰任務

四、實戰：寫一個 `weekly-report` skill

Step 1：跑 `/skill-creator`