Skill 解剖學

看清楚一個 skill 的內臟，你才知道自己要寫什麼。

---

課程目標

• 認識 SKILL.md 的兩大區塊：frontmatter + body
• 看懂 frontmatter 的必填 / 選填欄位
• 認識 progressive disclosure：什麼東西塞 SKILL.md，什麼東西丟到 references / scripts
• 知道為什麼「SKILL.md 越寫越長」是新手常見陷阱

---

零、從「跑過 skill」到「看懂 skill」

第 2 課你跑過了現成 skill，看到「按下去，事情自己跑完」。但事情怎麼跑完的？

問你自己一個問題：

如果讓你用人話教一個新同事「team-wrap-up 該怎麼做」，你會怎麼寫？

你大概會寫：

1. 先想想今天做了什麼有意義的事
2. 整理成「完成 / 決策 / 阻塞 / 下一步」四段
3. 寫進部門共享記憶（team-memhall）
4. 順便存成檔案備份

SKILL.md 就是這個「給新同事的指示」的標準格式——只是讀者從「新同事」變成「Claude」。

而且因為 Claude 比新同事更挑剔（它要知道精確邊界、確切觸發條件），SKILL.md 多了一些規則。我們現在就來看這些規則。

💡 不要被結構嚇到——SKILL.md 本質就是一份精簡的 SOP。你寫過任何 SOP 就會寫 SKILL.md。

---

一、一個 skill 資料夾的標準長相

打開任何一個成熟的 skill，結構大致是：

my-skill/                       # 資料夾名 = skill 名（kebab-case）
├── SKILL.md                    # 必要！skill 的「主腦」
├── README.md                   # 給人看的（選填）
├── references/                 # 進階參考文件（選填）
│   ├── decision-tree.md
│   └── examples.md
├── scripts/                    # 輔助腳本（選填）
│   └── helper.py
└── examples/                   # 範例輸入輸出（選填）

只有 SKILL.md 是必要的。其他都是隨需求加。

---

二、SKILL.md = frontmatter + body

打開任何 SKILL.md，頂部會看到一段被 --- 包起來的 YAML：

---
name: weekly-report
description: 週報草稿。當用戶說「寫週報」「weekly report」時觸發。
version: 1.0.0
author: "@yourname"
tags:
  - workflow
  - report
---

# /weekly-report — 週報生成

## 目標
...（這裡開始是 body）

--- 中間那段叫 frontmatter，是 YAML 格式的 metadata。 --- 後面是 body，是 markdown 寫的指令內容。

兩者角色完全不同。

Frontmatter 是「skill 的身分證」

Claude 不會跑 frontmatter 裡的指令。它只是用來：

• 識別 skill（name）
• 決定何時觸發（description）
• 預授權工具（allowed-tools）

Body 是「skill 的劇本」

Claude 會照 body 一步一步跑。body 才是真正的工作指示。

---

三、Frontmatter 必填三欄位

部門 SKILL_CONVENTION.md 規定的最少欄位：

---
name: weekly-report           # [必填] 與資料夾名一致，kebab-case
description: "..."            # [必填] 觸發條件描述
version: 1.0.0                # [必填] 語意化版本（修 bug → patch / 加功能 → minor / 大改 → major）
---

name — 規則

• kebab-case（小寫 + 連字號），例如 weekly-report ✅、weeklyReport ❌、weekly_report ❌
• 必須和資料夾名完全一致
• 簡短，能講清楚就好

description — 第 4 課整堂課都在講這個

description 是 Claude 決定要不要觸發這個 skill 的關鍵。下一課會深入，今天只記住一個公式：

[一句話功能]。[做什麼]。當用戶說「A」「B」「C」時使用。

version — 為什麼要寫

• 你改 typo / 修小 bug → patch（1.0.0 → 1.0.1）
• 你加新功能但向下相容 → minor（1.0.0 → 1.1.0）
• 你大改流程或刪步驟 → major（1.0.0 → 2.0.0）

部門用 version 追蹤誰用什麼版本——當有人 skill 出問題，第一個問就是「你的 version 是多少？」

---

四、Frontmatter 選填欄位（建議都寫）

author: "@MakiDevelop"               # 你的 GitHub handle
tags:                                # 2-5 個分類，方便 search
  - workflow
  - report
argument-hint: "[選填: focus 提示]"  # 用戶在 skill 名後可帶的參數
allowed-tools:                       # 預授權工具，避免每次跑都要按 yes
  - Read
  - Bash(git*)
  - mcp__team-memhall__write_entry
status: experimental                 # active / experimental / deprecated

重點：allowed-tools

這個欄位最值得寫。沒寫的話，skill 每次跑到一個工具都會跳出「Claude wants to use Bash, allow?」打斷你。

寫成 Bash(git*) 表示「允許所有 git 開頭的 bash 命令」。寫成 Bash 表示「允許全部 bash 命令」（風險高，不建議）。

第 8 課會教你怎麼安全地設定這個欄位。

---

五、Body 的標準骨架

部門推薦的 body 結構（出自 SKILL_CONVENTION.md）：

# /skill-name — 標題

## 目標
一段話說明這個 Skill 解決什麼問題。

## 不適用場景
列出什麼情況不該用這個 Skill。

## 輸入
需要什麼參數或資訊。

## 步驟 / Decision Model
核心工作流程，Step by step。

## 輸出
最終產出什麼。

## Quality Gates
完成後的自我檢查清單。

## Heuristics（選填）
經驗法則、常見陷阱、快速判斷依據。

重點：

• 「不適用場景」絕對不能省——它幫 Claude 判斷「這次不該用我」，避免誤觸發
• 「步驟」要具體，不是「跟用戶討論一下」這種模糊指示
• 「Quality Gates」是 checklist 型——- [ ] 已完成 X 這種

---

六、Progressive Disclosure — 三層載入機制

這是 skill 設計最重要的概念，也是新手最常踩的坑。

三層載入

Claude Code 處理 skill 時用三層機制：

層	內容	何時載入
第 1 層	frontmatter（name + description）	永遠在 context
第 2 層	SKILL.md body	skill 觸發時載入
第 3 層	references / scripts	需要時才讀

為什麼這很重要？

第 2 層的東西會永久留在你的對話 context 裡——直到你結束 session 或 /clear。

如果你的 SKILL.md body 寫了 1000 行，每次 skill 觸發後，這 1000 行就壓在你的對話裡，直到 session 結束。對話越長，這 1000 行就被反覆計費。

兩個觀察

「第二層（SKILL.md body）會永久留在主對話的 context window 裡。對一個『查完就走』的推薦型 skill 來說，這很浪費。」

— 王拐子, Threads, 2026-03

「Reference files——需要時才讀。」這就是 progressive disclosure。

---

七、SKILL.md body 應該多長？

部門慣例：

規模	行數	適合
小 skill	30-60 行	單一明確流程
中 skill	60-150 行	含選擇 / 分支
大 skill	150-300 行	複雜流程 + 多 mode
過大 ❌	300+ 行	該拆出來

原則：超過 150 行，就要問自己「是不是有東西該丟到 references/？」

該丟到 references/ 的東西

• 詳細決策樹（body 只放決策骨架，細節指向 references）
• 範例輸入輸出
• 跟其他 skill 的對照表（如果太長）
• 教學性質的解釋（為什麼這樣設計）

該留在 SKILL.md body 的東西

• 觸發後馬上要做的步驟
• 失敗處理（必看）
• Quality Gates（不能漏的檢查）
• 跟其他 skill 的差異對照表（要在 body，避免誤觸發）

---

八、看一個真實案例：team-wrap-up

打開部門的 team-wrap-up SKILL.md：

通常是 100-130 行——這是中等規模 skill 的甜蜜點。如果你打開來看（cat ~/.claude/skills/team-wrap-up/SKILL.md），你會發現：

• frontmatter 約 15 行
• body 第一段「與相似 skill 差異」是表格——避免誤觸發
• 「不適用場景」明確寫 3-4 條
• 「流程」分 5-6 個 step，每個 step 短
• 「失敗處理」+「治理邊界」結尾

這就是部門想看到的標準。

---

九、結論

• SKILL.md = frontmatter（YAML metadata）+ body（markdown 指令）
• frontmatter 必填三欄：name / description / version
• body 結構照 SKILL_CONVENTION.md 走，不要重新發明
• Progressive disclosure：詳細內容丟 references/，body 只放決策骨架
• 中型 skill 甜蜜點：60-150 行 body
• 下一課深入 description——它決定 skill 會不會被叫到

---

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

SKILL.md 的結構不是死規定，是部門慣例的結晶。AI 可以幫你檢查對齊，但部門慣例哪些值得堅持、哪些可以彈性，是你判斷。

你的人類優勢：

• 你知道哪些細節在部門 review 時會被打回——這些經驗 AI 不知道
• 你知道你寫的 skill 給誰用——若是給業務同事，body 的口氣要更白話；給工程師可以更技術

可以這樣跟 AI 說：

這份 SKILL.md [貼上內容]。請對照 ~/GitHub/claude-team-skill-lab/SKILL_CONVENTION.md，列出哪些欄位/段落不符合慣例，哪些行是不是該下放到 references/。給我修改清單，但不要直接改——我自己改。

---

練習題

yaml\n---\nname: WeeklyReport\ndescription: 寫週報用的\n---\n```", "instructions": "至少指出 2 個問題，並寫出修正版。", "hint": "看 name 命名規則 + description 寫法公式 + 必填欄位是不是都齊了。" }