大家好，我是 Lena。2025 年底，有些東西在安靜地變了。我不是一下子就注意到，而是慢慢才感覺到，就像大多數真正的變化一樣。
我一直在觀察 Claude Code 如何在不同專案之間處理重複任務。那個模式很熟悉：同樣的說明，每次都要用略微不同的方式重寫；同樣的上下文，每次都要重新解釋。我開始覺得，缺的不是模型本身，而是 模型與實際工作之間的那一層。
現在，這一層有了名字。它叫 Claude Code Skills。
什麼是 Claude Code Skills？
從最簡單的層面來看，一個 Claude Code skill 就是一個資料夾。這個資料夾裡有一個叫 SKILL.md 的檔案。當 Claude Code 偵測到這個資料夾時，它會讀取該檔案，把裡面的說明載入上下文，並據此調整自己的行為。
我一直反覆回到這個定義，因為它聽起來幾乎簡單得過頭了。但只要你多想一會兒，就會發現它背後的含義，比最初看見的還要大。
Skills 不是你每次對話一開始都要貼上的 prompt。它們是 可重複使用的行為包，Claude 會自動發現並在相關時刻套用。你安裝一次，Claude 就會在有需要時把對應的上下文拉進來，而不用你一再提醒。
SKILL.md 格式如何運作
每個 skill 都從同一種兩段式結構開始。SKILL.md 是一份 markdown 檔案，分為 frontmatter 和內容兩部分。frontmatter 負責設定 skill 如何 運作（permissions、model、metadata），而 markdown 內容則告訴 Claude 該做什麼。
最小示例如下：
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude will follow when this skill is active]
name 欄位會變成斜線指令。description 欄位則是 Claude 在判斷要不要載入這個 skill 時，最先讀取的內容。這段 description 對 skill 選擇至關重要：Claude 會靠它從可能多達 100+ 個可用 skills 中，挑出最合適的那一個。你的 description 必須提供足夠細節，讓 Claude 知道 什麼時候 應該選用這個 skill；至於其餘實作細節，則放在 SKILL.md 主體裡。
這點很容易被低估。我前幾次嘗試就寫錯了：description 在技術上沒問題，但在行為觸發上太模糊。結果 skill 不是在錯的時候被載入，就是根本沒被載入。description 不只是 metadata，它本質上是一個路由決策。
如果你想看完整規格，可以直接閱讀 official Claude Code Skills documentation。
你可以編碼哪些行為
事情從這裡開始才真正變得有意思。Skills 不只限於文字說明。每個 skill 都是一個目錄，裡面除了主 SKILL.md 外，還可以放 Claude 要填寫的模板、展示預期格式的範例輸出，以及 Claude 能執行的腳本。
在實務裡，這代表你可以編碼：
- 程式設計慣例 — 團隊如何命名函式、如何組織測試、如何處理錯誤
- 工作流程模式 — Claude 在生成報告或處理檔案時應該遵循的多步流程
- 可執行腳本 — 確定性的驗證邏輯、檔案轉換、外部 API 呼叫
- 參考文件 — Claude 按需讀取的詳細規格，不用把每次會話都塞得很滿
關鍵的設計洞察在於：當某個 skill 被觸發時，Claude 會透過 bash 從檔案系統讀取 SKILL.md，把裡面的說明帶進 context window。如果這些說明引用了其他檔案，Claude 也會一併讀取。若說明中提到可執行腳本，Claude 會執行它們，並只拿到輸出結果，腳本程式碼本身不會進入上下文。
這點很細微，但很重要。skill 是 按需延後載入 的。你完全可以把一份 50 頁的參考文件打包進 skill，Claude 只會拉進真正需要的部分。
建立你的第一個 Claude Code Skill
老實說，我第一個 skill 寫得不太好。不是壞掉了，只是……不夠精確。它的觸發範圍太寬，說明會和對話本身搶控制權，我花在解釋「我到底要什麼」上的時間，甚至比直接自己打出來還多。
如果重來一次，我會這樣做。
檔案放置與格式
對 Claude Code 來說，skills 放在專案目錄裡的 .claude/skills/，或放在全域生效的 ~/.claude/skills/。Claude Code 目前只支援 Custom Skills，所以建立 skill 的方式，就是一個目錄加一個 SKILL.md 檔案。
資料夾名稱就是 skill 的識別。盡量使用小寫與連字號。目錄結構通常像這樣：
my-skill/
├── SKILL.md ← required
├── examples/ ← optional but helpful
│ └── sample.md
└── scripts/ ← optional
└── validate.sh
SKILL.md 的 frontmatter 必須有兩個欄位：name 和 description。name 只能使用小寫字母、數字和連字號。description 則最好固定用第三人稱來寫，因為這段文字會被注入 system prompt，視角不一致時容易影響 skill discovery。
如何驗證你的 Skill 是否真的被套用
我一開始也被這點搞糊塗過。介面裡沒有明確的「skill 已載入」提示。我後來發現最實用的方法，是直接問 Claude：「What skills do you have access to?」它通常會把清單列出來。你也可以觀察 Claude 在那些理應觸發 skill 的任務上，行為有沒有發生變化。
更可靠的測試方式還是看行為：讓 Claude 在有 skill 與沒有 skill 的情況下完成同一個任務。如果輸出模式真的往你寫進去的方向改變，就表示 skill 在運作。理解觸發機制，也有助於設計出更好的 skills。Skills 會以名稱與 description 的形式出現在 Claude 的可用 skills 清單裡，Claude 會根據 description 判斷是否要參照某個 skill。對那些它本來就能輕鬆處理的簡單單步任務，即使 description 相符，Claude 也未必會去參照這個 skill。
Skill 設計中最常見的錯誤
Anthropic skill authoring best practices guide 已經整理得很好了，但我最常看到的幾類問題是：
- description 太模糊 — Claude 不理解 skill 的邊界，就無法穩定路由到它
SKILL.md塞得太滿 — 不要試著把所有東西都塞進同一個檔案，細節請拆到參考文件裡- 沒有範例 — 缺少具體範例的 skill，輸出往往更不穩定
- 說明過時 — 不要把很快就會失效的資訊直接寫死；如果是版本相關說明，最好放在可折疊區塊裡，或清楚標上日期
在專案與團隊之間共享 Skills
這裡事情開始真正變得有用，但現有的限制也會一起浮現。
SKILL.md 共享的目前限制
Skills 仍然是基於檔案分發的。這代表共享它們，本質上還是在分發檔案：zip 資料夾、Git 儲存庫、手動複製。現在的分發模型，仍要求個別使用者先下載 skill 資料夾，再把它放進 Claude Code 的 skills 目錄裡。組織層級的 skills 則可以由管理員部署到整個工作區；這項能力在 2025 年 12 月推出，支援自動更新與集中管理。
這已經是很有意義的進步。但它仍然意味著，skill 本身是一個靜態工件。當它所編碼的底層工作流程改變時，skill 不會自動更新。總得有人去維護它。
2025 年 12 月，Anthropic 將 Agent Skills 規格釋出為開放標準，OpenAI 也在 Codex CLI 採用了同樣格式。Skills 是 model-invoked，也就是 AI 會依上下文自動決定何時使用它們。這種互通性是真實而有價值的。你為 Claude Code 建立的 skill，原則上也能在 Cursor 或其他相容環境中運作。你可以瀏覽 Anthropic skills GitHub repository，看看社群已經貢獻了哪些範例。
跨 Agent 共享層可能會長什麼樣
這一部分我還在繼續摸索。
現在，一個 skill 是由人撰寫、由人審查，再手動分發的。Agent 會執行它，但不會改進它。它不會從結果裡學習，不會傳播成功的變體，也不會在說明和真實有效做法逐漸漂移時主動示警。
如果真的要有一層跨 Agent 的共享機制，它需要的不只這些：執行驗證、品質評分、版本脈絡。靜態的 SKILL.md 很擅長表達 意圖，卻不會記錄 結果。
我還沒有在哪裡看過，這個問題被處理得真正乾淨。
天花板：Claude Code Skills 會在哪裡開始失效
靜態檔案 vs. 自適應學習
Skills 是說明，不會觀察自己的表現。如果某個 skill 編碼了一種六個月前還很有效的除錯模式，但後來因模型更新或 API 變動而不再那麼可靠，skill 本身不會察覺。最後察覺的人，還是你。
Skills 是活文件。你得根據它們長時間的表現持續迭代。這當然是好的建議，但也意味著迭代負擔完全落在作者身上。Agent 無法參與修正自己正在遵循的那份說明。
沒有執行驗證，也沒有修復閉環
當 skill 被執行後，如果結果錯了，skill 機制本身不會攔住這件事。Claude 只是照著 SKILL.md 去做。如果結果沒有貼合原本意圖，這個閉環不會自動補上。
對那些編碼穩定慣例的 skills，例如程式碼風格或文件結構，這個問題沒那麼大；但對那些編碼動態工作流程、而正確性又高度依賴具體任務的 skills，問題就會更明顯。
缺乏可重用的共享網路
今天的 skills 要嘛是本地的，要嘛是公開放在 GitHub 上的。還沒有一層常駐的共享機制，能讓某類問題的成功解法，在經過測試、驗證與版本追蹤之後，被其他面臨相似問題的 Agent 發現並繼承。
SkillsMP community marketplace 算是朝這個方向跨出的早期一步。它對發現別人做了什麼很有幫助。但它收錄的 skills 依然是靜態檔案。它們沒有稽核紀錄，不知道自己被使用了多少次，也不知道結果如何。
Skills 之後會是什麼
從靜態說明走向可驗證、可繼承、可交易的能力
這個問題，我已經想了一陣子。
Claude Code skills 解決的是一個真問題：它讓 Agent 的行為變得可重複、可移轉。這一點並不小。在 skills 出現之前，上下文必須在每次會話裡重新建立；現在不必了。
但 skill 仍然是由人寫出來的工件。它記錄的是某個人 以為 有效的方法，而不是在什麼條件下、以什麼失敗模式、究竟 真正有效 過的方法。
下一層形態，不管最後會變成什麼，可能都更像是一種帶有來源脈絡的能力，而不是單純的檔案格式。它會說：這種方法在這些條件下被嘗試過，成功率是多少，在這些邊界情境裡失敗過，由哪些作者修訂過，又被哪些 Agent 在相近場景裡實際使用過。
那已經不是一份 markdown 檔案可以描述完的基礎設施了。
我還沒有完全想明白，這條裂縫意味著什麼。但它看起來並不偶然，更像是下一件值得持續觀察的事。
FAQ
- Claude Code 裡的
SKILL.md檔案是什麼？
SKILL.md 包含主要說明，是每個 Claude Code skill 的必備檔案。它採用兩段式結構：YAML frontmatter 用來告訴 Claude 何時該使用這個 skill，markdown 內容則是 skill 被呼叫時 Claude 要遵循的說明。你可以把它想成一份 onboarding 文件，只是 Agent 不會忘記它。
- 我要怎麼撰寫 Claude Code skill？
先從 frontmatter 開始：name（全小寫，只能使用連字號）和 description（使用第三人稱，明確寫出何時應該呼叫）。接著在 markdown 主體裡寫下清楚、直接的操作說明。只有在它們真的能改善行為時，再加入輔助檔案，例如 examples、scripts 或 reference files。最佳測試方式，是比較同一個任務在有無 skill 時的輸出差異。更詳細的指引，可以參考 Anthropic's skill authoring best practices。
- Claude Code skills 可以在團隊成員之間共享嗎？
組織管理員現在可以把 skills 部署到整個工作區，並支援自動更新與集中管理，這項能力已於 2025 年 12 月推出。對開源共享來說，GitHub 仍然是目前主要的分發渠道。Agent Skills 開放標準意味著為 Claude Code 建立的 skills 也可以在其他相容工具中運作。互通性已經存在；至於帶有執行歷史的集中重用網路，仍然是一個開放問題。
我會繼續觀察這件事怎麼發展。這裡確實有些東西正在發生，我只是還沒有完全看清，它最後會走到哪裡。
