Claude Code Skills 功能解析：它是什麼，以及如何使用

嗨，我是 Lena。去年晚些時候，我和 Claude Code 互動的方式，悄悄發生了一點變化。我原本沒打算注意到它，只是單純想別再重複同樣的解釋。每次開新會話，我都得再說一次：我們的錯誤格式慣例、commit messages 喜歡怎麼寫、Python 函式庫該先選哪些。Claude 每次都會理解，也會給出合適回應，然後到了下一次會話，又把這一切忘掉。那不算失敗，更像是每一次都得從同一個起點重新開始。

然後我開始認真看 Claude Code Skills 這個功能，某些東西就微妙地變了。

什麼是 Claude Code Skills 功能？

SKILL.md 到底是什麼

最簡單地說，skill 就是一個包含 SKILL.md 的目錄，也是一個把說明、scripts 與資源整理好的資料夾，讓 Agent 可以動態發現並載入，從而在特定任務上表現得更好。

這個檔案分成兩個部分：最上方是 YAML frontmatter（位於 --- 標記之間），下面是 markdown instructions。name 欄位會變成斜線指令，description 則幫助 Claude 判斷什麼時候應該自動載入這個 skill。

實際看起來大概像這樣：

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

嗯，好吧。所以它並不是什麼魔法。它本質上是一份結構化文字檔，Claude 會在需要的時候把它讀進來。

Skills 和 system prompts、project rules 有什麼不同

這一點我一開始也有點拿不準。

不同於 prompts 這種面向一次性任務的會話級說明，Skills 是按需載入的，重點在於讓你不必在多次對話中反覆提供同樣的指引。真正關鍵的差別，是 載入時機。system prompt 一直都在；skill 則安靜地待在檔案系統裡，只有當 Claude 判斷它和你正在做的事情相關時，才會被拉進上下文。

這個設計之所以有意思，在於它能在不改動核心 system prompt 的前提下，實現按需擴展 prompt。Skills 更像是可執行的知識包，Claude 只在需要時才載入，既能擴展能力，又能讓主 prompt 保持精簡。

這對我來說是一個很有分量的差異，雖然我到現在還沒完全搞清楚，Claude 究竟在什麼時候才會把某件事判定為「相關」。

如何使用 Claude Code Skills

SKILL.md 檔案應該放在哪裡

Skills 會從多個來源被發現並載入。Claude Code 會掃描使用者設定（~/.claude/skills/）、專案設定（.claude/skills/）、外掛提供的 skills，以及內建 skills，藉此建立可用 skills 清單。

所以，使用者層級 skills 放在 ~/.claude/skills/skill-name/SKILL.md。專案層級 skills 放在儲存庫內的 .claude/skills/skill-name/SKILL.md。每個 skill 都需要自己的命名子目錄。定義在 .claude/skills/ 下、且目錄是透過 --add-dir 加入的 skills，會被自動載入，並支援即時變更偵測，因此你甚至可以在會話進行中直接編輯它們，而不必重啟。

最後這一點，也就是 會話中途修改而不用重啟，是我當時完全沒想到的。這表示你可以在任務進行到一半時調整 skill，然後立刻觀察變化。我覺得這點很值得留意。

Claude 會遵循什麼樣的說明

skill 檔案幾乎可以包含任何說明，但若你先想清楚打算如何呼叫它，通常會更容易決定該放什麼。Reference content 帶進來的是 Claude 應用在目前工作上的知識，例如慣例、模式、風格指南與領域知識。Task content 則是針對具體動作的逐步說明，例如部署、提交或程式碼生成。

你也可以把輔助檔案一起打包進去。Claude 可以執行的 scripts。它可以填寫的 templates。只在需要時才載入的 reference 文件。Claude 會依需求分階段載入資訊，而不是一開始就把上下文吃滿，這是一種漸進式揭露模式。 所以，一個 skill 完全可以比單一檔案豐富得多，同時又不必在每次會話裡都耗掉整個 context window。

如何驗證 skill 是否真的被套用

這部分我到現在還是覺得有點模糊。

根據 official Claude Code skills documentation，決定自動觸發的是 description 欄位：Claude 會在啟動時讀取所有可用 skill 的描述，並用它們來判斷何時呼叫某個 skill。對 200+ 個 prompts 的真實測試顯示，觸發可靠性差異相當大。經過優化的 description 能把觸發率從 20% 拉到 50%；加入 examples 之後，甚至能再提升到 90%。

所以，如果某個 skill 沒有被觸發，第一個最值得回頭改的通常就是 description。寫得更具體一點，把觸發條件寫得更直白一點。Anthropic skills GitHub repository 也直接提過這點：Claude 往往比較容易觸發不足，因此 description 的語言最好對 什麼時候該啟用 說得稍微明確一些。

Skills 擅長做什麼

編碼專案慣例

這時我才開始更清楚地看到它的價值。如果你的團隊有一套固定模式，例如 API 回應該怎麼組織、錯誤物件該長什麼樣、非同步流程該怎麼處理，你可以把這些一次寫進 skill，之後就不用每次都重新解釋。

替 Agent 建立一個 skill，很像是在替新同事整理 onboarding 指南。這個比喻對我很有感。它不是永久記憶，更像是一張 Claude 隨手可取的參考單。

可重複的輸出格式

那些任務型 skills，也就是透過斜線指令呼叫的那種，很適合處理 commit message 生成、PR 描述、部署檢查清單之類的任務。它們擅長的是把輸出的 形狀 固定下來，而不只是提供籠統的指引。

給 Claude 帶入領域特定上下文

Skills 會把你的專業知識打包成可組合的資源，藉此擴展 Claude 的能力，讓通用 Agent 更像是貼合需求的專用 Agent。對那些工作在細分技術領域的團隊，例如自訂 DSL、內部工具鏈或特殊合規規則，這件事就會顯得特別有用。

Skills 做不到什麼

沒有跨會話學習

Skills 不會自己更新。它們不會觀察什麼方法有效，再回頭改寫自己的說明。一次會話開始時，SKILL.md 裡寫了什麼，Claude 就照著什麼工作，除非你手動去改。Anthropic engineering blog on Agent Skills 說得很直接：「Iterate with Claude — as you work on a task with Claude, ask Claude to capture its successful approaches into the skill.」這裡的 capture 仍然是人的步驟，不是 Claude 自動完成的。

沒有執行回饋閉環

如果 Claude 執行某個 skill 後產生了錯誤結果，這個 skill 本身不會因此更新。沒有任何訊號會回流到這套說明裡。無論上次發生了什麼，下次仍然會套用同樣的指引。

無法在團隊或 Agent 之間自動共享

Custom skills 是每個使用者各自持有的；它們不會在整個組織中自動共享，也無法由管理員集中管理。某位開發者寫出來的 skill，不會自動流向隊友的環境。它要嘛留在本地，要嘛放進專案目錄，再透過手動方式分享出去。

這點我一直反覆在想。定義一致 Agent 行為的能力是真實存在的，但分發問題仍然沒有被真正解掉。

靜態 Skills 之後會是什麼

從檔案式說明走向可驗證、可繼承的能力

Skills 這個功能確實解決了一個真問題：重複解釋上下文。你不再需要一遍遍重說，而是開始把它編碼下來。

但我一直反覆注意到一個空缺。一次成功修復、一套得來不易的除錯模式、一串終於穩定起作用的 prompt sequence，這些經驗依然不會流動。它們留在那一次會話裡，或者最多在有人記得時，被手動整理回 SKILL.md。

這背後其實有個更大的問題，我還在試著把它說清楚。大概是 被給出的說明 和 在許多 Agent 身上都被驗證過的行為 之間的差別。Skills 屬於前者。它們設計得很好，可組合，也的確有用。但它們依然是靜態工件，由人建立、由人維護，而且作用域是局部的。

如果某種成功方法能被浮現出來、被驗證，然後再提供給其他遇到相似問題的 Agent，會是什麼樣子？那已經是另一類基礎設施問題了。skills 格式本身不回答這個問題，而且它大概也不是要回答這個問題。

……我還會繼續想這件事。

FAQ

1. Claude Code 裡的 Skills 功能是什麼？ Claude Code Skills 功能 讓你能透過結構化的 SKILL.md 檔案擴展 Claude 的行為；每個檔案都包含 YAML frontmatter 與 markdown 說明，當任務和 skill 的 description 相符時，Claude 會動態載入它。
2. 我要怎麼為 Claude Code 建立一個 SKILL.md 檔案？ 在 .claude/skills/your-skill-name/ 下建立資料夾，然後在裡面加入一個 SKILL.md 檔案。先寫 YAML frontmatter（name 和 description 是必填欄位），再寫 markdown 說明。Anthropic skills repository 裡有一個 template-skill 可作為起點。
3. Claude Code Skills 會在會話之間持續生效嗎？ 持續存在的是這個 檔案。Claude 對它的使用記憶不會保留。每次會話裡，Claude 都會重新讀取 skill 的 description 和 instructions。內建的跨會話學習並不存在。
4. 我可以把 Claude Code Skills 分享給團隊嗎？ 你可以手動共享 skill 目錄，例如透過儲存庫裡的 .claude/skills/ 資料夾，或借助支援跨平台可攜性的 Agent Skills 開放標準。但目前還沒有組織層級的自動同步機制。
5. Claude Code Skills 和專案規則有什麼差別？ 專案規則（例如 CLAUDE.md）設定的是整個專案的整體行為。Skills 則是模組化、面向特定任務的能力包。它們會依 Claude 正在做什麼而有條件地載入，而不是一直常駐在上下文裡。你可以把 CLAUDE.md 理解為常駐式說明，把 skills 理解為按需調用的專長。