Claude Code Skill怎麼寫、SKILL.md放什麼？Anthropic官方揭9大實戰用法

Anthropic 自家團隊用 Claude Code 的 Skills 用到什麼程度？官方部落格給了一個數字：截至 2026 年 6 月 初，Anthropic 內部有「數百個」skill 在活躍使用。

這篇文章由 Anthropic 技術成員、參與 Claude Code 的 Thariq Shihipar 撰寫，他把團隊一路踩過的坑，整理成一份「skill 怎麼做才有效」的實戰心得。

多數人對 skill 的第一印象是：「不就是一個 markdown 檔，把指令寫進去就好？」但這篇文章最想破除的，正是這個誤解。同樣是做一個 skill，把它當成一個檔案、跟把它當成一個「可以放腳本、資料、範本的資料夾」，最後好不好用差很多。

如果你還沒建過第一個 Skill，建議先看這篇：〈Claude Skills 是什麼、怎麼用？新手零基礎入門教學，不用每次重貼提示詞〉，從零開始會比較順。本文從「已經會建 Skill」的起點出發，聚焦在怎麼寫得更有效。

為什麼資料夾比單一檔案好用？

skill 可以理解成一種「脈絡工程」（context engineering）：在對的時機，把對的資訊餵給 AI。

如果把所有東西塞進一個檔案，等於每次都把整本說明書攤在 Claude 面前。因此，改成資料夾結構、搭配「漸進揭露」（progressive disclosure，需要時才讀對應檔案），Claude 才不會被無關內容干擾。

Anthropic 官方文件也建議把詳細 API 文件、範例、腳本等 supporting files 放在 skill 資料夾裡，並由 SKILL.md 說明何時讀取。

第一步：先用「9 大分類」找出你該做哪種 skill

Anthropic 盤點內部 skill 後，發現它們大致聚成 9 種類型。官方也提醒，這不是 definitive list（完整定義全集），但可以當成一張地圖，幫你看出自己還缺哪種 skill。

重點是，最好的 skill 通常只做一類；想做太多事的會橫跨多類，反而把 agent 搞混：

• 函式庫與 API 參考：教 Claude 正確使用某個函式庫、CLI 或 SDK，附上常踩的雷。
  
• 產品驗證：描述怎麼測試、驗證程式碼有沒有真的動。Anthropic 說這類對產出品質「可量測的影響最大」，值得花一週做到極好。
  
• 資料抓取與分析：接上你的資料與監控系統，內含抓資料的腳本、儀表板代號。
  
• 業務流程與團隊自動化：把重複工作流（如每日 standup、開票）收成一個指令。
  
• 程式碼鷹架與範本：自動生出新服務、新模組的樣板。
  
• 程式碼品質與審查：強制團隊的程式風格、協助 code review。
  
• CI/CD 與部署：顧 PR、跑測試、漸進部署、出問題自動回滾。
  
• Runbooks（故障排除手冊）：接到一個症狀，走完多工具調查，產出結構化報告。
  
• 基礎設施操作：執行例行維運，對破壞性動作加上護欄。
  

第二步：把最高價值的「Gotchas（陷阱）」區塊寫好

原文有一句重話：任何 skill 裡訊號最高的內容，就是 Gotchas 區塊。它指的是 Claude 使用這個 skill 時最常踩的失敗點，要隨時間累積、持續補充。這些往往是「文件不會寫、但你被坑過才知道」的細節。

用一個非工程師也懂的場景來想：假設你做一個幫忙整理員工請假的 skill，下面這幾種「踩過才知道」的眉角，就值得寫進 Gotchas：

範例一：「同一張假單可能改過好幾次，要抓『最後核准』那一版，不是最早送出的那張。」

範例二：「業務部口中的『出差』，在人資系統裡叫『公假』，其實是同一件事，只是部門叫法不同。」

範例三：「系統顯示『已送出』不代表假請成功了，還要看主管那關有沒有按下核准。」

其實原文舉的是工程場景（資料表要認「版本最高」那列、而非時間最新的；同一個值在不同系統有不同名稱；測試環境就算沒真的成功也會回報成功）。

但道理都一樣：要把這種「平常沒人會特別告訴你、出過包才學到」的細節寫下來，skill 才會越用越準。

第三步：描述（description）要寫給模型看，不是寫給人看

這是最容易被忽略、卻最關鍵的一點。Claude Code 啟動 session 時，會建立一份可用 skill 與 description 的清單，用它判斷「使用者這個請求，有沒有對應的 skill 可以用」。

所以 description 欄位不是給人看的摘要，而是「什麼情況下該觸發我」的說明。實務上，把觸發詞（例如 babysit）直接寫進描述，命中率會更高。

第四步：給 Claude 腳本與檔案，讓它「組合」而不是「重造」

把可重複的動作寫成腳本交給 Claude，它就能把每一回合花在「決定下一步做什麼」，而不是重打一次樣板。進階一點還能用「隨選 hooks」（on-demand hooks），只在這個 skill 被呼叫時才生效，例如官方文中提到的 /careful（動正式環境時才開，自動擋掉 rm -rf、DROP TABLE、force-push 等危險指令）、/freeze（debug 時只准改特定資料夾，避免手滑「修好」無關的程式碼）。

把上面幾個原則合起來，一個五臟俱全的 SKILL.md 大概長這樣，你可以複製後改成自己的版本：

---name: weekly-reportdescription: 彙整這週完成的工作，產生給主管看的週報。當使用者說「跑週報」「整理這週進度」時觸發。---# 週報產生器## 怎麼做1. 讀 config.json 取得週報要寄給誰、用什麼格式；若還沒設定，先問使用者。2. 彙整這週完成的事項，只列「跟上週相比的新進度」，不要把舊的重講一遍。3. 把這次的週報存進 reports.log（只新增、不覆蓋），下次執行時讀自己的歷史，自動判斷哪些是新的。## Gotchas（踩過的坑）- 「標記完成」不等於真的結案，有些項目會被退回重做，狀態要看最新的那一版。- 同一件事這週可能改過好幾次，只取最後定案的版本，別把過程中的草稿都列進去。## 參考- 欄位與格式範本見 references/format.md（需要時再讀，不必一開始全載入）。

動手前要知道的兩個前提

第一，skill 不是免費的。官方文件說明，一般 session 中，skill 的 description 會進入 context，完整 SKILL.md 則是在使用者或 Claude 呼叫後才載入；因此每多一個放進專案的 skill，都會增加一點模型需要掃描的脈絡。

團隊規模一大，Anthropic 建議的做法是改用 plugin marketplace，讓成員自己挑要裝哪些，而不是全部塞進每個專案。

第二，別想一次寫到完美。Anthropic 強調，他們最好用的 skill 多半是從「寥寥幾行字加一個 gotcha」起步，再因為大家持續在 Claude 撞到新狀況時補上去，才慢慢變強。

所以結論很簡單，skill 的價值不在你寫了多少，而在你有沒有告訴 Claude「它原本不知道、或老是做錯的那件事」。先做一個小的，撞到坑就補一條 gotcha，這比一開始追求完整更有效。

資料來源：Anthropic《Lessons from building Claude Code: How we use skills》(Thariq Shihipar)、Claude Code Docs：Skills、Claude Code Docs：Plugins

本文初稿為AI編撰，整理．編輯/ 李先泰

延伸閱讀

富比士公布2026台灣50大富豪榜！日月光張家兄弟登首富，8位新富豪全來自半導體與AI！
輝達台灣總部曝光！黃仁勳：公司蓋這麼美，還想 WFH？
「加入《數位時代》LINE好友，科技新聞不漏接」