Agent Skills 是什麼：教 Claude 一次，永遠會用

你有沒有算過，同一段話你對 Claude 講過幾次？每次審 PR 都重新描述一次回饋格式，每次寫 commit 訊息都再提醒一次偏好的寫法，每次都把團隊的程式規範貼一遍。重複解釋同一件事，就是一個還沒被寫下來的 skill。

skill 的概念很簡單：把「怎麼做某件事」寫成一份說明檔，教 Claude 一次；之後只要你的請求跟這件事有關，它就自動把說明載進來照做。這篇帶你搞懂 skill 是什麼、放哪裡、跟 CLAUDE.md 與其他客製化方式怎麼分工。

skill 就是一份會自己出現的說明書

正式一點的定義：skill 是一個裝著指示與資源的資料夾，Claude Code 能自動發現並拿來把特定任務做得更準。每個 skill 的核心是一份 SKILL.md，開頭的 frontmatter 寫兩件事：name（名稱）與 description（描述），底下的內文就是實際的指示，例如你的審查清單、格式偏好、做事步驟。

---
name: pr-review
description: Reviews pull requests for code quality.
  Use when reviewing PRs or checking code changes.
---

底下寫你的審查清單與回饋格式，Claude 會照著做。

其中 description 是靈魂：Claude 靠它決定要不要用這個 skill。你請 Claude 審 PR 時，它會拿你的請求跟所有可用 skill 的描述比對，找到相符的那個並載入套用。這也解釋了為什麼 skill 會「越寫越準」：描述跟你的說話習慣越貼近，它出場的時機就越對。

把 skill 想成一位待命的專家，description 是他名片上那行「找我做什麼」。名片寫得清楚，工作才會被派到他手上。

自動比對是怎麼運作的

重點在「按需載入」這個設計。Claude Code 啟動時掃描 skill 目錄，但只載入每個 skill 的名稱與描述，內文都還在門外。你送出請求後，它做語意比對：例如「解釋一下這個函式在做什麼」會對上一個描述寫著「用視覺圖解說明程式碼」的 skill，因為意圖重疊。比對成功、經你確認後，完整的 SKILL.md 才會被讀進 context 照著執行。

這個設計解決了 context 的經濟問題：你的 PR 審查清單，不需要在你除錯的時候佔位子。用得到才進來，用不到只留一行描述。

skill 放哪裡：個人與專案

• 個人 skill 放在家目錄的 ~/.claude/skills：跟著你走遍所有專案，適合放你個人的 commit 風格、文件格式、喜歡的解說方式。
• 專案 skill 放在 repo 根目錄的 .claude/skills：跟著版本控制走，誰 clone 這個 repo 誰就自動擁有，適合放團隊標準、品牌規範這類全隊共用的知識。

專案 skill 跟程式碼一起被 commit，也就是說團隊知識可以用發 PR 的方式演進：有人改良了審查清單，全隊下次 pull 就同步升級。

這是 skill 最被低估的價值：它把「資深同事腦中的默契」變成看得見、改得動的檔案。新人第一天 clone 專案，就繼承了全隊的做事方法；老手改進了流程，也不再需要開會宣導，改檔案就是宣導。知識從口耳相傳變成版本控制的一部分。

跟其他客製化機制怎麼分工

Claude Code 的客製化選項不只 skill 一種，選錯工具會把事情弄複雜。用一張表分清楚：

一個好記的分法：CLAUDE.md 是常識，skill 是專業。常識每天都要在場，專業在需要時到場就好。而 subagent 是「另一個人」，skill 是「給現在這個人的一本手冊」，兩者甚至可以搭配：讓自訂的 subagent 掛上特定 skill 出任務。

什麼時候該寫一個 skill

判斷法一句話就講完：如果你發現自己在對 Claude 重複解釋同一件事，那就是一個等著被寫下來的 skill。常見的候選：團隊的程式審查標準、commit 訊息格式、品牌文案指南、特定框架的除錯清單。下一篇我們就動手寫第一個。

反過來，有兩種東西不適合做成 skill。一種是每次對話都需要的原則，那是 CLAUDE.md 的工作；另一種是一次性的任務指示，講一次就結束的事不值得建檔。skill 的甜蜜點是「重複發生、但不是每次都發生」的任務知識：頻率高到你懶得重講，又沒高到該常駐 context。

用這把尺量一輪你的日常工作，通常馬上就能列出兩三個候選。