Agent skill 是什麼？與 MCP、提示詞的差異

Agent skill 的實際定義

Agent skill 是磁碟上的資料夾，其中包含名為 SKILL.md 的檔案。該檔案以純 Markdown 撰寫，包含名稱、簡短說明及操作指示。Agent 會在啟動時載入說明，只有在使用者的請求符合該說明時，才會讀取操作指示。Skill 的其他特性幾乎都源自這兩點。

資料夾可以包含不只一個檔案。Agent Skills 規格定義了 3 個選用目錄：scripts/ 用於存放 Agent 會執行的程式碼、references/ 用於存放 Agent 需要時才讀取的文件，以及 assets/ 用於存放範本與資料。這些目錄都不是必要項目。只包含 SKILL.md 的資料夾，就是完整的 skill。

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

說明是最容易被低估的部分。在 Agent 決定是否開啟 skill 之前，它唯一能看到的文字就是說明。因此，說明必須使用人們實際會輸入的用語，清楚表達 skill 的功能及適用時機。

為何技能在使用前幾乎不會產生成本

這是值得理解這種格式的主要理由，重點在於內容載入方式，而不是功能。載入會分階段進行，規格將其稱為漸進式揭露。

啟動時，代理程式只會載入每個已安裝技能的 name 和 description，不會載入其他內容。Agent Skills specification 的公開指引指出，截至 August 2026，每個技能約需 100 tokens。安裝十幾個技能，所耗用的內容大約只相當於一個長段落。

當請求符合某個描述時，代理程式會讀取該 SKILL.md 的本文。規格建議本文少於 5,000 tokens，檔案少於 500 行。此時，references/ 和 scripts/ 中的檔案仍不會產生成本。只有當指示要求代理程式讀取參考檔案時，該檔案才會載入。隨附的指令碼則不同：代理程式會透過 shell 執行它，因此指令碼原始碼不會進入內容視窗，只有輸出結果會進入。

現在將它與人們通常首先採用的做法比較，也就是一個龐大的提示。系統提示或永久啟用的指示檔案中的每一行，在每個請求、每個工作階段都會產生成本，不論工作是否需要這些內容，而且還會與實際問題爭用注意力。10,000 tokens 的常駐指示，即使只是詢問現在幾點，也必須支付這筆成本。十幾個技能在閒置時約需 1,200 tokens，只有執行需要該技能的工作時才會擴大。這就是採用技能的完整理由，也是小型技能庫勝過更長提示的原因。

有一點容易被忽略。技能載入後，其本文會在工作階段的剩餘時間內持續保留於內容中，因此較長的 SKILL.md 會反覆產生成本，而不是只產生一次。將詳細內容移至 references/ 並不是為了整潔，而是讓機制依設計運作。

代理技能不是工具呼叫

工具也稱為函式呼叫，是模型可以叫用的項目。harness 會傳送 schema，其中包含名稱、說明和引數的結構。模型發出呼叫後，程式會執行該呼叫，並將結果以訊息傳回。工具會執行工作。

代理技能本身不會執行任何動作。代理會讀取技能內容，再使用既有工具採取行動。模型無法像傳遞引數給工具一樣，將引數傳給技能。技能能做的是告訴模型應使用哪些工具、使用順序，以及之後要檢查哪些項目。

簡單來說，工具會賦予代理新的能力；技能則會讓代理對既有能力具備判斷力。如果某個步驟每次都必須產生精確且經過驗證的結果，應使用工具或 script。如果某個步驟需要一致地套用相同的思考方式，則應使用技能。技能可以只包含判斷邏輯，但仍可能是你最常使用的技能。Ponytail 會促使 coding agent 採用能正常運作的最小變更就是一個例子：它不會增加任何新能力，只會改變代理使用既有能力的方式。

代理程式技能不是 MCP server

MCP (model context protocol) 是用來將代理程式連接至外部系統的協定。MCP server 是執行該協定並向代理程式提供工具的程序。通常需要設定、認證資訊，以及本機命令或網路端點。技能則是一個包含 markdown 檔案的資料夾。它不包含程序、埠或協定。

兩者的 context 成本也不同。MCP server 提供的每個工具都包含名稱、說明與引數 schema。預設情況下，這些內容會在整個工作階段的請求中，即使未使用也會保留。有些 client 已開始按需擷取工具 schema，但預先載入仍是常見做法。技能在靜態狀態下只是一行文字。

兩者互補，最完整的配置會同時使用。MCP server 提供存取能力。技能提供操作流程：針對團隊的實際工作流程，指出應呼叫哪些工具、依何種順序呼叫，以及良好結果應具備哪些條件。如果由你自行代管，在 VPS 上執行 MCP server涵蓋這一部分。

Agent skill 不是 system prompt，也不是 AGENTS.md

兩者都是以 Markdown 撰寫的指示，因此容易混淆。差異在於它們載入的時機。AGENTS.md、CLAUDE.md 和 system prompt 一律啟用。skill 則依需求啟用。

判斷方式只有一個問題：如果任務與這段內容完全無關，忽略這段內容是否會造成錯誤？團隊文件格式、建置命令與分支命名規則適用於所有任務，因此應放在一律載入的檔案中；每次都載入正是其用途。每月執行兩次的版本發布檢查清單不適用於所有任務，因此應放在 skill 中。當一律載入的檔案中有一節逐漸擴充成編號程序時，這就是應該移出的訊號。

這些檔案本身也有值得正確遵循的慣例。請參閱 AGENTS.md 與人員檔案各自應包含的內容，以及 說明程式碼庫結構的 design.md，這是我們採用的兩種檔案。

最小技能的形式

在 Claude Code 中，個人技能放在 ~/.claude/skills/<name>/SKILL.md，並套用至所有專案。專案技能放在 .claude/skills/<name>/SKILL.md，並提交至 git，因此該儲存庫中的每位人員與每個 agent 都能使用。GitHub Copilot 和 VS Code 則從 .github/skills/ 讀取 workspace 技能。其中的檔案內容相同。

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

這就是一個完整的技能。目錄名稱會成為你輸入的命令，因此此技能的命令是 /restore-drill。在 Claude Code 中，/skills 選單會列出已安裝的技能，這是確認檔案已載入的最快方式。如果技能未出現在該選單中，表示名稱有誤：檔案必須命名為 SKILL.md，目錄名稱則只能包含小寫字母、數字及單一連字號。將相同步驟寫成 agent 可以重複執行的程序，是 在 VPS 上排程 restic 備份 的自然搭配；備份正在執行，不代表備份可以還原。

何時應將 skill 改寫為 script

每次都只有一個正確答案的步驟，都應該寫成 script，並將 skill 縮減為幾行文字，說明何時執行，以及如何解讀輸出。這有兩個原因，而且都很實際。

第一，script 的原始碼不會佔用 context window。300 行的剖析器只會耗用輸出所需的內容；相同邏輯若寫成 markdown 指示，則每次 skill 載入時都會佔用完整長度。

第二，script 會在不同執行中產生相同答案。若要求模型每次執行時重新推導相同的日誌剖析規則，在狀態不佳時，結果可能略有不同；而你通常要到兩個數字不一致時才會發現。

因此，請依工作類型拆分。「剖析 CSV，並列印總額與明細項目不一致的每一列」是 script。「檢視 script 列出的資料列，並說明哪些看起來像是資料輸入錯誤」則是 skill 指示。將判斷保留在 markdown，將確定性邏輯放入程式碼，這與建立代理程式可在無人監看時執行的迴圈是相同的原則。

為什麼我的 skill 永遠不會觸發？

因為它的 description 只說明 skill 的功能，卻沒有說明何時使用。代理程式只能根據這一行比對你的請求。「協助處理資料庫工作」沒有明確的比對對象。「對 staging database 執行 schema migration。使用時機：使用者要求遷移資料表、新增欄位或變更 schema」則包含使用者實際會輸入的詞彙，因此能觸發。

相反的問題是 skill 持續觸發。像「對此 repository 的任何程式碼變更都使用」這類描述會符合所有請求，因此每個工作都會載入內容，之後一直留在工作階段的 context 中。請將描述限縮到實際需要的情境。在 Claude Code 中，也可以在 frontmatter 設定 disable-model-invocation: true，停用自動載入，並在輸入 skill 名稱時保留使用功能。

第三種問題是 skill 重複了某個 tool。若指示代理程式 curl 某個 MCP server 已經提供的 API，或在 harness 已有搜尋 tool 的情況下要求代理程式使用 grep 搜尋檔案，就會產生較慢的處理路徑，以及兩組可能互相衝突的指示。請刪除重複內容，改為描述目的。

不要猜測自己遇到的是哪一種問題。在新的工作階段中執行兩次相同的 prompt：一次提供 skill，另一次關閉 skill，然後比較回答。新的工作階段很重要，因為你撰寫 skill 的工作階段已經包含 skill 所說明的所有內容，會掩蓋書面版本中的缺漏。Anthropic 的 skill-creator plugin 可在 Claude Code 中自動完成這項比較，包括產生應該觸發與不應觸發 skill 的 prompts，並測量各自的觸發頻率。

這是某一家廠商的格式，還是標準格式？

Anthropic 在 2025 年底發布這項格式，之後將其作為開放標準，託管於 agentskills.io。截至 2026 年 8 月，該規格定義必要的 name 和 description 欄位、選用的 license、compatibility、metadata 和 allowed-tools 欄位、3 個選用目錄，以及分階段載入行為。該專案也提供參考驗證器，因此 skills-ref validate ./my-skill 能在分享資料夾前，依規格檢查該資料夾。

真正有參考價值的是支援的客戶端清單。同一個資料夾可由 Claude Code、Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands 和 opencode 等工具讀取。Microsoft 也以這種格式在 github.com/microsoft/skills 發布自己的 skills，並提供名為 Skill Recorder 的桌面工具。該工具會監控你完成一次工作，將其重建為意圖和依序排列的步驟，然後輸出為 skill。廠商開發的錄製工具，其輸出格式卻採用其他廠商制定的規格，這表示該格式已不再只是單一產品的功能。

先寫什麼

不要先規劃技能庫。等到你發現自己第3次在聊天中貼上相同指示時，再將該文字移到 SKILL.md，並刪除貼上的內容。只有你實際感受到的重複，才是值得保留某項技能的可靠觸發條件。搜尋程序適合作為第1個技能，而以你自己的 SearXNG 執行個體為基礎的搜尋技能可呈現其形式。

有2個習慣能維持技能庫的健康。安裝任何不是由你撰寫的技能前，都要閱讀完整內容，包括指令碼，因為技能包含代理程式會遵循的指示，以及代理程式可能執行的程式碼：請將其視為從陌生人處安裝軟體。不要將憑證放在資料夾中，因為技能是會被提交及分享的文字檔案。讓機密資訊遠離代理程式說明這些值應改放在哪裡，今年學習代理程式的路線圖則將技能與其餘設定依序排列。

FAQ

agent skill 與 MCP server 有什麼不同？

MCP（model context protocol）server 是透過協定向 agent 提供工具的執行中程序，因此需要設定與認證資料。其工具定義通常會在整個工作階段中佔用 context，無論是否實際使用。agent skill 則是包含 SKILL.md 檔案的資料夾，不涉及程序或協定；在 agent 決定讀取前，約佔用 100 tokens。若要讓 agent 存取系統，請使用 MCP server。若要告訴 agent 如何妥善使用該存取權限，請使用 skill。許多設定會同時使用兩者。

agent skill 只能搭配 Claude Code 使用嗎？

不能。Anthropic 開發此格式後，將其以開放標準發布於 agentskills.io。同一個資料夾也能由 Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands 及其他 client 讀取。不同之處在於各 client 查找的位置，以及支援哪些額外的 frontmatter 欄位。Claude Code 會讀取 ~/.claude/skills/ 與 .claude/skills/，GitHub Copilot 和 VS Code 則會讀取 repository 中的 .github/skills/。SKILL.md 檔案本身可在這些 client 之間原樣移動。

安裝多少個 skill 後會開始拖慢速度？

限制在於啟動預算，而不是 skill 數量。每個已安裝的 skill 都會依規格發布的指引，加入名稱與描述，約佔用 100 tokens。因此，30 個 skill 在尚未使用任何一個前，約會佔用 3,000 tokens。最先受到影響的是配對，而不是速度：描述相互重疊的 skill 過多時，model 會更難選出正確的 skill。請撰寫彼此不重疊的描述，並刪除已停止使用的 skill。

這項指示應放在 skill 還是 AGENTS.md？

請確認它是否適用於 repository 中的每項工作。建置命令、團隊格式與命名規則適用於所有工作，因此應放在 always-on 檔案中；該檔案每次都載入，正是其用途。偶爾才執行的程序，例如 release checklist 或 restore drill，應放在 skill 中，這樣不需要該程序的工作就不會產生成本。AGENTS.md 中若有一個區段已經擴充成編號步驟，通常表示它應該移至 skill。