做第一個 Skill：資料夾長什麼樣、為什麼它沒被叫出來

SOP 改寫成 AI 能跑的格式、流程拆成節點之後，你手上會累積幾十份指令。下一個問題是：這些指令放哪裡？AI 怎麼知道什麼時候該用哪一份？

全部塞進常駐檔是最糟的答案，常駐的東西每輪都付費，還會互相稀釋。正確的容器叫 Skill：一份指令一個資料夾，平常只有一行簡介在 AI 眼前，對話命中了才整份載入（三層載入）。

這一篇講三件事：資料夾長什麼樣、怎麼命名和寫簡介、以及最常見的失敗——做好了它卻不用。

資料夾結構與放置位置

一個 Skill 是一個資料夾，裡面必須有一個 SKILL.md（大寫，檔名固定）。其他都是選配：參考檔、腳本、範例。

SKILL.md 開頭是 frontmatter（檔案最上面用 --- 包起來的幾行設定），兩個欄位。name：最多 64 字，只能小寫字母、數字、連字號，不能含 anthropic、claude 這兩個保留字，Claude Code 裡可以省略，預設用資料夾名。description：最多 1,024 字，必填，寫這個 Skill 做什麼和什麼時候用。

放哪裡決定誰能用。個人用的放 ~/.claude/skills/<名稱>/，所有專案都看得到；專案用的放 .claude/skills/<名稱>/，跟著 git 走，同事也能用。Claude Code 的文件補了一個細節：frontmatter 的 --- 必須是檔案第一行，否則整份會被當成內容。

命名建議用動名詞：processing-pdfs、analyzing-spreadsheets、writing-weekly-reports。名詞片語（pdf-processing）也可以。避免 helper、utils、tools 這種看不出用途的名字，不只人看不懂，AI 挑技能時也靠這個。

為什麼它沒被叫出來

新手最常撞的牆叫 Trigger Failure：Skill 寫好了、放對位置了，你講到相關的事，AI 當沒看見，自己 freestyle。

原因幾乎都在 description。官方文件說得很直接：AI 從可能上百個 Skill 裡挑，只靠 description。所以這一行要滿足三條。

第三人稱。「Processes Excel files and generates reports」可以；「I can help you process Excel files」不行，「You can use this to…」也不行。理由是 description 會被注入系統提示詞，人稱不一致會干擾判斷。

寫「做什麼」和「什麼時候用」，兩個都要。官方範例：「Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.」後半句是觸發條件，沒有它 AI 不知道什麼情況該想起這個技能。

放進你平常會講的字。你平常說「幫我弄週報」，description 裡就要有「週報」；你說「整理一下試算表」，就要有「試算表」。不要只寫技術名詞。

另外一個常被忽略的欄位：disable-model-invocation: true。加了這行，AI 不會自己決定用這個 Skill，只有你打 /名稱 才會啟動。官方建議有副作用的技能（部署、寄信、發訊息）都加，你不會想讓它因為「程式看起來好了」就自己部署。

動手做

第一個 SKILL.md 的範本在這裡。建 .claude/skills/writing-weekly-reports/SKILL.md，貼進去改成你的：

---
name: writing-weekly-reports
description: Drafts weekly status reports for managers from the week's notes and commits, prioritizing blockers and next actions. Use when the user mentions 週報, weekly report, status update, or asks to summarize the week.
---

# 週報

## 心法
週報是給主管看的。挑資訊的標準不是「我做了什麼」，是「主管需要知道嗎」。
卡點（blocker）與下週動作排最前面，完成事項其次，細節不放。

## 步驟
1. 執行 scripts/fetch.sh 取得本週紀錄，讀取其輸出。
2. 依心法挑選，草擬三段：卡點／下週動作／本週完成。
3. 輸出前對照 reference.md 的格式範例。

## 不做
不編造沒有紀錄的進度；資料不足的項目標「待補」。

做完在對話裡打 /writing-weekly-reports 測手動觸發；再用自然語言說「幫我弄週報」測自動觸發。第二個不成功，回頭改 description。已經有 Skill 但 AI 不用它的，把 description 貼給 AI 檢查：

下面是一個 Skill 的 description。請檢查三件事並改寫：
1. 是不是第三人稱（不能有 I／You 開頭）。
2. 有沒有同時寫「做什麼」和「Use when…什麼時候用」。
3. 「什麼時候用」裡有沒有使用者平常會講的口語字眼（中英文都列）——列出三個我可能會說、但目前沒寫進去的說法。
改寫後不超過 1,024 字，key use case 放最前面。
目前的 description：（貼上）

網頁版沒有 Skill 機制，最接近的替代是 Claude 專案的「專案指令」，一個專案一個技能。

做對了的樣子：用自然語言（不打 /）講到那件事，AI 主動用了這個 Skill；description 裡有至少兩個你平常真的會說的字；有副作用的技能加了 disable-model-invocation: true，AI 沒有自己啟動過；同事 clone 專案之後，不用你解釋就能用同一個技能。

第一個 Skill 該做什麼？想一件你每週都在對 AI 重複解釋的工作。先只寫 description 那一行，寫到你自己看了會說「對，我就是這樣講的」。

Skill 是一個資料夾，SKILL.md 必有，參考檔和腳本選配。name 小寫連字號 64 字內；description 1,024 字內，第三人稱，寫做什麼加什麼時候用。沒被叫出來，九成是 description 沒有你平常會講的字。有副作用的技能加 disable-model-invocation: true，只准你手動啟動。

站內延伸

• 主文件太肥怎麼拆 → 500 行剪法
• 上線前怎麼測 → 評估先行
• 一份做好的手冊 → 找工具Skill 手冊

來源： Anthropic：Skill authoring best practices（name／description 的字數與字元限制、第三人稱、動名詞命名、description 範例）；Claude Code：Skills（放置位置、frontmatter 第一行規則、disable-model-invocation）。