Agent skill 到底是什麼?與 MCP 有何不同
了解 Agent skill 的實際結構:資料夾內含 SKILL.md,僅在需要時載入指示。本文比較漸進式揭露、龐大提示與 MCP 的差異,並說明 12 個技能約占 1,200 tokens。
Agent skill 實際上是什麼
Agent skill 是磁碟上的資料夾,其中包含名為 SKILL.md 的檔案。該檔案包含名稱、簡短說明,以及以純 Markdown 撰寫的指示。Agent 會在啟動時載入說明,只有在你的要求符合該說明,或你依名稱叫用該 skill 時,才會讀取指示。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 的發布指南指出,截至 October 2026,每個技能約需 100 tokens。安裝 12 個技能所耗用的內容,大約只相當於一個長段落。
當請求符合某個描述時,代理程式會讀取該 SKILL.md 的本文。規格建議本文少於 5,000 tokens,檔案少於 500 行。此時,references/ 和 scripts/ 中的檔案仍不會產生任何成本。只有當指示要求代理程式讀取參考檔案時,該檔案才會載入。隨附的 script 又有所不同:代理程式會透過 shell 執行它,因此 script 原始碼不會進入內容視窗,只有輸出結果會進入。
現在比較人們通常最先採用的方法,也就是一個極其龐大的 prompt。system prompt 或持續啟用的指示檔案中的每一行,在每次請求、每個工作階段都會產生成本,無論工作是否需要這些內容,而且會與實際問題爭用注意力。即使只是詢問現在幾點,10,000 tokens 的常駐指示仍然照樣計費。12 個技能在啟用前約需 1,200 tokens,但載入的指示可以在同一段對話的後續工作中持續留在內容中。這就是採用技能的完整理由,也是小型技能庫勝過更長 prompt 的原因。
有一點容易被忽略。在 Claude Code 中,技能載入後,其本文會持續保留在後續回合的對話中,因此較長的 SKILL.md 會反覆產生成本,而不是只產生一次成本。內容壓縮可能刪減或移除已載入的技能內容。將詳細資訊移至 references/ 並不是為了整潔,而是讓機制依設計運作。
Agent skill 不是工具呼叫
工具(也稱為 function call)是模型可以呼叫的項目。執行框架會提供一個結構描述,其中包含名稱、說明與引數格式。模型發出呼叫後,您的程式會執行該工具,結果再以訊息形式傳回。工具會執行工作。這次交換的兩端都屬於執行框架,也就是負責在模型周圍執行迴圈的程式;該程式也會在啟動時讀取 skill 說明,並決定何時開啟 skill。
Skill 不會自行執行任何工作。Agent 會先讀取 skill,再使用原本已有的工具採取行動。Claude Code 在呼叫 skill 時接受引數,並透過 $ARGUMENTS 等 placeholder 將引數插入指示中。Skill 能做的是告訴模型要使用哪些工具、依照什麼順序使用,以及之後要檢查哪些項目。將工作交給第二個 agent 是最清楚的例子:單一 Claude Code 工作階段已能與另一個工作階段傳送訊息,而 skill 就是用來記錄何時值得這麼做,以及要傳送哪些內容。
簡單來說,工具會為 agent 提供新的能力,而 skill 主要是讓 agent 對既有能力具備判斷力。Skill 若確實增加能力,也是透過內含的 script,由 agent 使用原本已有的 shell 執行。如果某個步驟每次都必須產生精確且經過驗證的結果,應使用工具或 script。如果某個步驟需要一致地套用相同的思考方式,應使用 skill。Skill 可以只包含判斷力,卻仍可能是您最常使用的 skill;Ponytail 會促使 coding agent 採取能運作的最小變更便是如此:它不增加任何新能力,只改變 agent 使用既有能力的方式。這項判斷也可以朝相反方向運作;unlazy skill 會逐步檢查 Depth Tree,以阻止 agent 過早宣告工作完成,就是將相同技巧用於徹底性,而非限制變更。
Agent skill 不是 MCP server
MCP(model context protocol)是一種將 agent 連接至外部系統的通訊協定。MCP server 是執行該協定並向 agent 提供工具的處理程序。它通常需要設定、認證資訊,以及本機命令或網路端點。skill 則是一個包含 markdown 檔案的資料夾。它不會啟動處理程序、不使用埠,也沒有通訊協定。
兩者的 context 成本也不同。MCP server 提供的每個工具都包含名稱、說明與引數 schema。對於預先載入這些工具的 client,這些內容會在整個工作階段中放入 request,無論是否實際使用。Claude Code 預設已不再採用這種方式:截至 October 2026,內建已啟用 tool search,因此工作階段開始時只會載入工具名稱與 server 指示,完整定義則會在 Claude 搜尋工具時載入。skill 靜態存在時只是一行文字。
兩者可以互補,最完整的設定會同時使用兩者。MCP server 提供存取能力。skill 提供操作程序:針對團隊的實際工作流程,應呼叫哪些工具、依何種順序呼叫,以及何種結果才算理想。如果自行代管,在 VPS 上執行 MCP server 會說明這一部分。
Agent skill 不是 system prompt,也不是 AGENTS.md
兩者都是以 Markdown 撰寫的指示,因此容易混淆。差異在於載入時機。系統提示與啟動時載入的專案指示會持續生效;agent 在其目錄中工作時,才會載入巢狀的 AGENTS.md 與 CLAUDE.md 檔案。skill 則是依需求載入。Claude Code 的 輸出樣式位於持續生效的一端,因為選取樣式會直接編輯 system prompt,因此會影響工作階段中的每則回覆,包括完全不會使用任何 skill 的回覆。
判斷方式只有一個問題:如果任務與這段內容完全無關,忽略這段內容是否會造成錯誤?團隊撰寫規範、建置命令與分支命名規則適用於所有任務,因此應放在持續生效的檔案中;每次都載入正是其用途。每月執行兩次的發布檢查清單不適用於所有任務,因此應放在 skill 中。當持續生效檔案的某個區段已經發展成編號程序時,就表示應該將它移出。
這些檔案本身也有值得遵循的慣例。請參閱 AGENTS.md 應包含哪些內容,以及哪些內容應放在供人員閱讀的檔案中,以及 說明程式碼庫結構的 design.md,了解我們使用的這兩種檔案。
最小技能的樣貌
在 Claude Code 中,個人技能存放於 ~/.claude/skills/<name>/SKILL.md,適用於該電腦上的所有專案,但不適用於 Cowork 或雲端工作階段。專案技能存放於 .claude/skills/<name>/SKILL.md,並會提交至 git,因此團隊成員也能取得;Claude 專案中的雲端對話串不會載入這些技能。GitHub Copilot 和 VS Code 也會從 .github/skills/、.agents/skills/ 以及 .claude/skills/ 讀取專案技能。這些位置中的檔案內容相同。
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` reports that it cannot open the config file, stop and report the full error instead of guessing the cause.這樣就是完整的技能。目錄名稱會成為你輸入的命令,因此這個技能的命令是 /restore-drill。在 Claude Code 中,/skills 選單會列出已安裝的項目,是確認檔案是否已載入的最快方式。如果選單中沒有顯示,請先檢查名稱:檔案必須命名為 SKILL.md;Agent Skills 規格要求名稱只能使用小寫字母、數字和單一連字號,且必須與目錄名稱相符。將相同步驟寫成代理程式可重新執行的程序,是 VPS 上排程的 restic 備份 的自然搭配;備份正在執行,不代表備份還原也能正常運作。
何時應將 skill 改寫為 script
每次都只有一個正確答案的步驟,都應該寫成 script,並將 skill 縮減為幾行文字,說明何時執行,以及如何解讀輸出。這有兩個原因,而且都很實際。
第一,script 的原始碼不會佔用 context window。300 行的剖析器只會耗用輸出所需的內容;相同邏輯若寫成 markdown 指示,則每次 skill 載入時都會佔用完整長度。
第二,script 會在不同執行中產生相同答案。若要求模型每次執行時重新推導相同的日誌剖析規則,在狀態不佳時,結果可能略有不同;而你通常要到兩個數字不一致時才會發現。
因此,請依工作類型拆分。「剖析 CSV,並列印總額與明細項目不一致的每一列」是 script。「檢視 script 列出的資料列,並說明哪些看起來像是資料輸入錯誤」則是 skill 指示。將判斷保留在 markdown,將確定性邏輯放入程式碼,這與建立代理程式可在無人監看時執行的迴圈是相同的原則。
為什麼我的 skill 從未觸發?
因為其中的 description 只說明 skill 的功能,卻沒有說明何時使用。這一行是 agent 用來比對請求的唯一依據。「協助處理資料庫工作」沒有明確對應任何請求。「對 staging database 執行 schema migration。使用者要求遷移資料表、新增欄位或變更 schema 時使用」則包含使用者實際會輸入的詞,因此能夠觸發。
相反的問題是 skill 持續觸發。例如「此 repository 中的任何程式碼變更都使用」會比對到所有內容,因此每項工作都會載入本文,之後還會持續留在對話中。請將描述限制在預期的使用情境。在 Claude Code 中,也可以在 frontmatter 設定 disable-model-invocation: true,停止自動載入,並保留透過名稱手動使用 skill 的能力。
第三種問題是 skill 重複了某項工具。若指示 agent 對 MCP server 已提供的 API 執行 curl,或在 harness 已提供搜尋工具時要求 grep 檔案,就會產生較慢的處理路徑,以及兩組可能互相衝突的指示。請刪除重複內容,改為描述目標。
不要猜測自己遇到的是哪一種問題。在全新的 session 中執行相同 prompt 2 次:1 次啟用 skill,另 1 次關閉 skill,然後比較回答。使用全新 session 很重要,因為撰寫 skill 的 session 已經包含 skill 中的所有內容,會掩蓋書面版本的缺漏。Anthropic 的 skill-creator plugin 可在 Claude Code 中自動完成這項比較,包括產生應該觸發與不應觸發 skill 的 prompt,並測量各自的觸發頻率。如果 skill 確實載入,而 agent 仍未依照其內容執行,問題就不在描述,接著應查看agent 已讀取指示卻仍未依照執行的原因。
這是某一家廠商的格式,還是標準?
Anthropic 在 2025 年底發布這套格式,之後將其作為開放標準,託管於 agentskills.io。2026 年 10 月 22 日,Anthropic 宣布將 Agent Skills 捐贈給 Linux Foundation 旗下的 Agentic AI Foundation。截至 2026 年 10 月,該規格定義了必要的 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 提供工具的執行中程序,因此需要設定與憑證。除非 client 延後載入工具定義(Claude Code 現在預設會這樣做),否則完整的工具定義會在整個工作階段中占用 context。Agent skill 則是包含 SKILL.md 檔案的資料夾,不涉及程序或通訊協定;在 agent 決定讀取之前,約占用 100 tokens。使用 MCP server 可讓 agent 存取某個系統。使用 skill 可告訴 agent 如何妥善使用該存取權限。許多環境會同時使用兩者。
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/、.claude/skills/ 或 .agents/skills/。SKILL.md 檔案本身可在這些 client 之間直接移動,內容不需變更。
安裝多少個 skill 後,效能才會變慢?
限制在於啟動預算,而不是 skill 的數量。每個已安裝的 skill 都會依規格發布的指引,加入名稱與說明,約占用 100 tokens。因此,安裝 30 個 skill,在使用任何一個之前約會占用 3,000 tokens。最先受到影響的是匹配,而不是速度:說明內容相互重疊的 skill 越多,模型越難選出正確的 skill。請撰寫彼此不重疊的說明,並刪除已停止使用的 skill。
這項指示應放在 skill 還是 AGENTS.md?
請先判斷它是否適用於 repository 中的每項工作。建置命令、團隊格式與命名規則適用於所有工作,因此應放在每次都會載入的檔案中;該檔案的用途就是持續啟用這些規則。偶爾才會執行的程序,例如 release checklist 或 restore drill,則應製作成 skill,這樣在啟用前只需支付一行說明的成本。在 Claude Code 中載入後,其中的指示會在後續回合持續保留於對話中,即使後續執行的是無關工作。AGENTS.md 中已經擴充為編號步驟的區段,通常就是等待移出的 skill。