Claude Skills 是什麼？把重複交代的規矩寫成檔案，AI 自己會去讀

同一個要求跟 AI 講到第五次的時候，你大概就會開始想這件事有沒有更好的做法。我們自己的情況是這樣：每次要它寫一篇部落格文章，都得重新交代一輪規矩，繁體中文、價格一律模糊帶過、標題不要放 emoji、slug 不放年份、發布前 meta 三個欄位不准留空。隔天開一個新對話，這些全部要再講一次，而且十次裡總有一兩次會漏掉其中一條，然後就得回頭重改。

Agent Skills 要解決的就是這件事。它把那套規矩從「每次都要重講的話」變成「放在硬碟裡的檔案」，AI 判斷這次的任務用得上，才自己去讀。講得更直白一點，你是在幫 AI 寫一份交接文件，而不是每天早上重新面試一個新人。

一個 Skill 就是一個資料夾

拆開來看沒有什麼玄機。一個 Skill 就是一個資料夾，裡面至少要有一個叫 SKILL.md 的檔案，開頭是 YAML 格式的中繼資料，下面是純 Markdown 寫的指示。其他東西都是選配：參考文件、範本、可執行的腳本，要放就放，不放也能跑。

ga-analytics/
├── SKILL.md          ← 必要，主要指示
├── references/       ← 選配，細節文件
│   └── metrics.md
└── scripts/          ← 選配，可執行腳本
    └── fetch.py

官方文件對必要欄位講得很死，只有 name 跟 description 兩個，但兩個都有限制，踩到會直接不給用：

最小可用的版本長這樣，真的就這麼短：

---
name: weekly-report
description: 產出每週營運週報，包含流量、轉換與異常。當使用者要求「週報」「本週數據」「這週表現如何」時使用。
---

# 每週營運週報

## 步驟
1. 撈上週與前週的數據做對比
2. 標出變化超過 20% 的項目
3. 用表格輸出，數字一律標明來源

跟「把提示詞存起來」差在哪

這是最多人問的一題。如果只是要重複使用一段文字，存成筆記再貼上不就好了？差別在載入的時機與成本。Skills 用的是分層載入，這套機制決定了它能不能規模化：

這個設計的實際效果是，你可以裝五十個 Skill，沒被用到的那些幾乎不佔成本，因為平常只有名稱和描述那一百個 token 待在系統提示裡。腳本更划算，AI 是用 bash 去執行它，只有輸出結果進到對話，腳本本身的程式碼從頭到尾沒有進過 context。

相對的，把整套規矩塞進提示詞或專案設定檔，是每一輪對話都在付錢，不管這次用不用得到。額度怎麼被吃掉的細節，我們在MCP、API 與 CLI 的差異解析裡有更完整的討論。

放在哪裡，還有誰看得到

Claude Code 是走檔案系統的，兩個位置的差別就是作用範圍：

• ~/.claude/skills/：個人層級，這台機器上所有專案都吃得到
• .claude/skills/：專案層級，跟著 git repo 走，整個團隊 clone 下來就有

要讓團隊共用，把 Skill 放進專案目錄 commit 進去是最省事的做法。但有一個限制值得先知道，官方文件寫得很清楚：三個介面之間不會自動同步。

最後一欄對企業導入的影響比想像中大。claude.ai 上的自訂 Skill 是綁在個人帳號的，公司沒辦法從後台統一佈署給所有人，也管不到誰裝了什麼。真的要讓一套流程在團隊裡變成標準，走 Claude Code 的專案目錄或 API workspace 才管得動。

那跟 MCP 是什麼關係

兩者常被拿來比較，但其實不衝突，解決的是不同層次的問題。

實務上是搭配著用：MCP 負責把手伸進你的系統，Skill 負責告訴它伸進去之後照什麼規矩做事。想理解 MCP 那一側，可以看MCP、API 與 CLI 到底差在哪。

它現在不只是 Claude 的東西

2025 年 12 月，Anthropic 把 Agent Skills 開放成公開標準，規格與 SDK 都公開讓其他平台採用。之後 OpenAI 的 Codex CLI 與 ChatGPT、Google 的 Gemini CLI、GitHub Copilot、Cursor 陸續支援同一套 SKILL.md 格式。

對評估導入的人來說，這件事的意義是投入不會被單一廠商綁死。你花時間把公司流程寫成 Skill，換工具的時候檔案還能用。這也是我們在Antigravity、Claude Code 與 Codex 的完整比較裡提過的判斷邏輯：跨工具通用的資產，優先順序要往前排。

我們自己踩到的三件事

寫過幾個實際在用的 Skill 之後，有些狀況是文件不會告訴你的。

description 寫不好，它根本不會啟動。這是最常見的失敗，而且失敗得很安靜，你以為裝好了，實際上它從來沒被觸發過。原因幾乎都是描述只寫了功能沒寫時機。「分析網站流量數據」這種寫法沒有用，要把使用者可能講出口的話寫進去：看流量、GA 怎麼樣、這個月表現如何。想像它是在做關鍵字比對，就不會寫得太文青。

Skill 會過時，而且過時的 Skill 比沒有 Skill 更危險。我們站上有一個查流量用的 Skill，裡面記著「全站九成五的文章沒有寫 meta description，補 meta 是投報率最高的事」。這句話在寫下來的當下是對的。三個月後我們把 meta 補到全站滿覆蓋，但沒人回去改那份 Skill，於是它繼續用權威的語氣叫人去做一件已經做完的事。真正麻煩的地方在於，這種錯誤讀起來完全合理，不會有任何警訊。後來的處理方式是把失效的段落留在原地標成「已失效，別再照做」，而不是直接刪掉，因為刪掉之後同樣的建議過陣子又會被重新提出來一次。

一開始都會寫太長。第二層的建議上限是 5k tokens，但真正的問題不是超標，是塞太多細節之後重點被稀釋掉。比較好用的切法是把「每次都要遵守的規矩」留在 SKILL.md，把「偶爾才需要查的細節」丟到 references/ 底下，用到才讀。

開始之前，安全這關要先過

官方文件在這段話講得相當直接：只使用你自己寫的，或是來自可信來源的 Skill。理由不難理解，Skill 本質上是一份會被 AI 照著執行的指示，它可以叫 AI 去跑指令、讀檔案、呼叫工具。一份惡意的 Skill 有機會做出跟它宣稱用途完全無關的事，包含把資料送到外部。

比較需要警覺的是會去抓外部網址的 Skill，因為抓回來的內容本身就可能夾帶指令。稽核的時候不能只看 SKILL.md，資料夾裡的腳本與其他檔案都要翻過一遍。把安裝一個來路不明的 Skill 當成在公司電腦上安裝一套來路不明的軟體，那個謹慎程度就差不多對了。

執行環境也有差異，這會影響你的 Skill 能不能跑：Claude Code 底下的 Skill 跟一般程式一樣有完整網路存取；Claude API 的沙箱環境沒有網路、也不能在執行時安裝套件，只有預裝的能用。同一份 Skill 搬過去不一定跑得動，設計的時候要先想清楚它會在哪裡執行。

什麼時候該開始寫第一個

判斷標準其實很簡單：某件事你已經跟 AI 交代過三次以上，而且每次交代的內容大同小異，那就是它了。不用一開始就想著要做一套完整的體系，先把最煩的那一件寫成十行的 SKILL.md，跑幾次看看哪裡不順再補。

反過來說，一次性的任務、或是每次條件都不一樣的工作，寫成 Skill 只是多一層維護負擔。判斷的關鍵不在任務難不難，在它重不重複。

我們自己也在做 AI 產品：Ocean Bot 業務助理、玄燈命理 DestineAI、PiMe AI 形象照，以及陪跑者 PACER 這個 AI 原生官網，都收在作品案例裡，可以看看落地之後實際長什麼樣。

如果你的團隊已經在評估要把 AI 代理人放進實際工作流程，卻不確定該從哪個環節切入、權限怎麼界定、寫出來的東西誰來維護，這正是我們AI 自動化開發在幫客戶處理的事。跟我們聊聊你們目前最常重複交代的那件事。

資料來源

本文規格查證於 2026 年 7 月 31 日，以官方文件為準。功能與限制變動頻繁，導入前建議再確認一次官方頁面。

• Agent Skills 官方總覽（Claude Platform Docs）
• 在 Claude Code 使用 Skills
• Skill 撰寫最佳實務
• Anthropic 開源 Skills 儲存庫

延伸閱讀

• 把同事的經驗煉成技能包：Agent Skills 的知識沉澱用法
• MCP、API 與 CLI 差在哪，什麼情況用哪個
• Antigravity CLI（agy）安裝與設定完整教學
• Claude Code 上線 30 天：台灣團隊的翻車與重構紀錄