description 是觸發機制

Skill 寫得再好，description 不對，永遠不會被叫到。

---

課程目標

• 認識 description 是 skill 唯一的觸發機制——不是 skill 名稱、不是 body 內容
• 學會 description 的寫法公式
• 看懂「pushy」（有觸發力）和「模糊」（沒人會用）的差別
• 知道一個叫「description optimization」的迭代手法

---

一、為什麼 description 這麼重要？

回想第 3 課的 progressive disclosure 三層：

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

只有第 1 層永遠在 context。意思是：

• 你裝了 100 個 skill，每個的 name + description 都會被 Claude 隨時看見
• 但 Claude 不會主動讀 SKILL.md 的 body——除非它判斷「這個 skill 該被觸發」
• 判斷依據只有 name + description

所以 description 是 skill 的唯一觸發路徑。

一個比喻

想像你的辦公室有 100 個資料夾，每個資料夾外貼一張小標籤。當有客戶問問題，你只會看標籤決定「這個問題該翻哪個資料夾」。

標籤 = description。

如果標籤寫「寫週報、月報、季報、年報；請在每週五下午整理進度時翻我」——你一眼就知道何時該打開。 如果標籤寫「幫忙做一些事情」——你永遠不會打開它，因為不知道何時該打開。

---

二、description 寫法公式

部門 SKILL_CONVENTION.md 給的公式：

[一句話功能描述]。[具體做什麼]。當用戶說「關鍵字 A」「關鍵字 B」「關鍵字 C」時使用。

三個部分缺一不可：

Part 1：一句話功能（What）

「廠商方案評估（六位一體）。」

讓 Claude 一眼知道「這 skill 做什麼」。

Part 2：具體做什麼（How）

「讀取廠商提案 PDF/Doc，多 Agent 協作分析技術架構、報價合理性、市場行情、廠商背景，輸出 Google Doc 報告 + Google Sheet 比較表。」

讓 Claude 知道「這 skill 跟其他相似 skill 有什麼差別」。

Part 3：觸發詞清單（When）

「當用戶說『評估這份提案』『vendor eval』『廠商報價分析』時使用。」

這是最重要的一段。Claude 看用戶剛說的話像不像這些觸發詞，來決定要不要跑。

---

三、好 vs 壞：對照範例

範例 1

❌ 壞 description：

description: "幫助用戶做分析"

問題：

• 太抽象，「分析」是什麼分析？
• 沒有觸發詞，Claude 不知道用戶說什麼話該叫它
• 跟其他 100 個 skill 撞名（很多 skill 都「做分析」）

✅ 好 description：

description: "EDA 探索性數據分析。從 DuckDB / CSV / xlsx 跑完整分析框架，產出多 Tab Excel 報告（含分布、相關性、異常值）。當用戶說「跑 EDA」「探索性分析」「看一下這份資料」「資料初探」時使用。"

差別：

• 明確說資料源（DuckDB / CSV / xlsx）
• 明確說產出（多 Tab Excel）
• 4 個觸發詞，cover 不同講法

範例 2

❌ 壞 description：

description: "週報"

✅ 好 description：

description: "週報草稿生成器。掃描本週 git log + 本週 memhall episode，自動整理成「本週完成 / 下週計畫 / 阻塞」三段式週報，可貼進 Slack 或 Email。當用戶說「寫週報」「weekly report」「禮拜五報告」「跟主管交差」「整理本週進度」時使用。不適用於月報或季報——那些用 monthly-report。"

差別：

• 明確排除（不適用月報）→ 避免誤觸發
• 觸發詞包含日常講法（「跟主管交差」「禮拜五報告」）

範例 3

❌ 壞 description：

description: "這是一個 skill，可以幫你處理客戶相關的事情，包括聯絡、追蹤、報告、分析等等。"

✅ 好 description：

description: "客戶 onboarding 自動化。給客戶名稱 + 簽約日期，產生：(1) 客戶資料夾 in Google Drive (2) 內部 Slack channel (3) 歡迎信草稿 (4) Salesforce 紀錄。當用戶說「新客戶 onboarding」「客戶開戶」「設定新客戶 X」時使用。不負責簽約後的日常追蹤——那些用 customer-followup。"

差別：

• 範圍明確窄化——onboarding 一件事，不是「客戶相關所有事情」
• 步驟具體（4 個明確 outputs）
• 明確排除「日常追蹤」（指向另一個 skill）

---

四、寫 description 的「pushy」原則

部門希望 description 寫得有觸發力——稍微「強迫推銷」自己一點。

Claude 有「undertrigger」傾向——它寧可不觸發 skill 也不要錯觸發。所以你不主動 push，它就不會用。

讓 description 更 pushy 的招式

1. 多列觸發詞（5-10 個都 OK）

   • ✅ 「當用戶說『寫週報』『weekly report』『禮拜五報告』『主管交差』『整理本週進度』時使用」
   • ❌ 「當用戶說『寫週報』時使用」

2. 加「proactively apply」/「強烈建議」

   • ✅ 「當用戶在寫提案、客戶報告、簡報時，強烈建議主動觸發提供 EDA 數據支援」

3. 明列場景（不只是觸發詞）

   • ✅ 「適用情境：產品提案、客戶月報、季度檢討、行銷活動評估」

4. 明列「該排除」

   • ✅ 「不適用於：私人聊天、單純問問題、跟簡報無關的對話」
   • 有「不適用」會讓 Claude 更敢觸發——因為它知道誤觸發會被抓到

---

五、Description Optimization — 一個進階手法

部門有個 skill 叫 skill-optimize。它做一件事：

1. 給它一個寫好的 SKILL.md
2. 它幫你產 20 個「該觸發 / 不該觸發」的測試 query
3. 跑 description 的觸發率
4. 自動提案改寫 description，再跑測試
5. 迭代到觸發率最高為止

你不需要在第一次寫 description 就完美——寫個 v0，跑個幾次實戰，發現該觸發但沒觸發 / 不該觸發卻觸發了，回頭改 description。

第 7 課會帶你跑一次 skill-optimize。

---

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

description: "部門 session 收尾。將本 session 的關鍵決策 / 進度 / 下一步寫入 team-memhall（部門共享記憶）。當用戶說「team 收工」「team-wrap-up」「部門收尾」「team session 結束」「寫進部門記憶」時使用。寫入需要先設定 team-memhall MCP server（見 setup/team-memhall-onboarding.md）。"

拆解：

• What：「部門 session 收尾」
• How：「將本 session 的關鍵決策 / 進度 / 下一步寫入 team-memhall」
• When（觸發詞）：5 個
  • 「team 收工」
  • 「team-wrap-up」
  • 「部門收尾」
  • 「team session 結束」
  • 「寫進部門記憶」
• 限制：「寫入需要先設定 team-memhall MCP server」（讓 Claude 知道何時該降級）

這是 description 寫法的範本。

---

七、寫 description 的 4 步流程

下次你寫 skill 時，按這 4 步：

Step 1：寫一句話功能描述

問自己：「我能用 5-10 個字說清楚這 skill 做什麼嗎？」說不清楚 → skill 範圍太大，先拆。

Step 2：寫具體做什麼

把流程的輸入 → 輸出寫清楚。包括用什麼工具、產出什麼格式。

Step 3：列觸發詞清單

問自己：「正常人會怎麼講這件事？」

• 中文怎麼說？
• 英文 / 縮寫怎麼說？
• 業務同事怎麼說？
• 你自己懶得時候怎麼說？

把這些都寫進觸發詞清單。

Step 4：寫「不適用場景」

明確排除掉鄰近 skill 會做的事。讓 Claude 知道「這個情境不該叫我」。

---

八、結論

• description 是 skill 唯一的觸發機制
• 公式：[功能]。[做什麼]。當用戶說「A」「B」「C」時使用。
• 寫得 pushy 一點——Claude 有 undertrigger 傾向
• 多列觸發詞、明列場景、明列排除——三大武器
• 寫 v0 後可以用 skill-optimize 迭代
• 下一課我們學「怎麼從對話自動撈 skill 候選」

---

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

description 的觸發詞是「正常人會怎麼講這件事」的清單。AI 知道語法，但不知道你部門的口頭禪——這是你的領域知識。

你的人類優勢：

• 你知道部門同事累的時候會怎麼簡寫（「禮拜五的報告」「給老闆交差」）
• 你知道哪些觸發詞會跟其他 skill 撞——這要看部門 skill 全貌才判斷得到

可以這樣跟 AI 說：

我要為這個 skill 寫 description：[功能 + 做什麼]。請給我 8 個觸發詞候選，要包含：(1) 正式講法 (2) 業務同事口頭禪 (3) 累的時候簡寫 (4) 中英混雜 (5) 跟主管交差語境。我會挑 5 個最像我們部門講話方式的。

---

練習題

yaml\ndescription: "幫忙寫文件"\n```\n\n假設這個 skill 的功能是：把對話記錄整理成正式的會議紀要 .docx，自動分「決議事項 / 待辦事項 / 待確認事項」三段。", "instructions": "用「[功能]。[做什麼]。當用戶說『A』『B』『C』時使用。」的公式改寫，至少 4 個觸發詞，並加上「不適用場景」一句。", "hint": "想想正常人會怎麼講「整理會議紀要」這件事——「會議記錄」「meeting notes」「會議備忘」「議事錄」。" }

yaml\ndescription: "這是一個強大的 skill，可以幫你處理各種與資料分析、商業智慧、儀表板、報表、KPI 追蹤、洞察報告等業務分析相關的需求，無論是要做月度檢討、年度策略、客戶分析、產品分析、競品分析、市場分析、流量分析、轉換漏斗分析等等都可以使用。"\n```", "instructions": "指出至少 2 個問題（提示：範圍 / 觸發詞 / 排除）。然後寫一份改進版 description，假設它真正的功能是「跑 OMO 電商月度檢討（GMV / 客戶留存 / 商品 PR 值四象限）」。", "hint": "「什麼都能做」= 「什麼都做不好」。範圍越窄，description 越強。" }