Agent Skills 完整指南：如何让 AI Agent 掌握可复用的专业知识与工作流程

截至 2026 年 8 月 17 日，Agent Skills 規範要求每個 Skill 至少包含一個 SKILL.md，而官方規範建議採用「先載入中繼資料、觸發後載入指令、需要時再讀取資源」的漸進式揭露方式。這代表本週最可執行的做法不是把所有知識繼續堆進 Prompt，而是先建立一個最小 Skill，測試觸發條件，再逐步加入參考資料與受控腳本。Agent Skills 官方規範

最後更新於 2026 年 8 月 17 日；資料核實自 Agent Skills 規範、Claude Code 官方文件及官方 Skills Repository。

這篇適合三類讀者：第一次接觸 SKILL.md 和 Agent Skills 的開發者、希望複用團隊標準流程的 Claude Code 使用者，以及準備建立內部 Skill 倉庫並關注安全治理的技術負責人。

先把 Skill 放在正確的位置

Agent Skill 可以理解為一個可被 AI Agent 發現、載入和執行的能力包，通常由觸發描述、操作指令，以及可選的參考資料、腳本和範本組成。它適合保存穩定的領域規則與重複工作流程，但不等於一個擁有獨立權限的伺服器，也不會自動取得檔案、終端機或外部服務的完整存取能力。

最容易出現的設計錯誤，是把所有內容都放入同一層：

把長篇 API 文件、公司規範和操作步驟全部貼進系統提示詞，導致每次工作都消耗相同的上下文。
把每天變動的價格、版本、部署狀態或專案資料硬編進 Skill，資料過期後，Agent 仍可能依照舊內容作答。
把「應該怎樣做」和「可以對外部系統做什麼」混在一起，讓使用者誤以為 Skill 本身具有執行權限。
沒有清楚描述啟用時機，使多個相鄰 Skill 同時被觸發，增加輸出衝突和工具誤用的機會。

因此，Skill 的核心價值不是「讓 Agent 知道更多」，而是把一項能力切成可發現、可維護、可測試的獨立單元。

與普通 Prompt 的差別也在這裡：Prompt 多半是對話層面的臨時指示；Skill 則是檔案化、可版本管理、可按需載入的工作規格。Claude Code 官方文件也將 Skill 定位為按需載入的知識或可重複工作流程，而不是每次工作都強制加入的固定上下文。Claude Code Skills 文件

按照四個目錄層次拆分能力

一個最小 Skill 不需要一開始就包含大量檔案。根目錄和 SKILL.md 先能說清楚「何時使用、如何執行、如何驗收」，再按實際需求增加其他內容。

元件	主要責任	適合放入的內容	不適合放入的內容
`name` 與 `description`	讓 Agent 識別 Skill 及觸發時機	能力範圍、使用情境、關鍵任務詞	空泛的「提升效率」「處理各種工作」
`SKILL.md`	提供啟用後的操作指令	步驟、限制、輸入輸出、例外處理、驗收標準	大型 API 手冊、頻繁變動的即時資料
`references/`	保存需要時才讀取的知識	詳細規格、公司標準、案例、欄位說明	未經整理的資料傾倒
`scripts/` 與 `assets/`	執行可重複的輔助動作或提供範本	驗證程式、轉換工具、範本、固定資料表	未審核的下載器、廣泛檔案寫入程式

官方規範目前要求 name 和 description，其中 name 最長為 64 個字元，description 最長為 1024 個字元；規範也建議主要 SKILL.md 控制在 500 行以內，將詳細內容移到參考檔案。這些限制的實際意義，是讓 Agent 在發現階段只接收短描述，在真正需要時才取得完整內容。Agent Skills Specification 欄位說明

一個適合作為起點的結構如下：

review-api/
├── SKILL.md
├── references/
│   ├── api-style.md
│   └── error-codes.md
├── scripts/
│   └── validate-response.py
└── assets/
    └── review-report-template.md

SKILL.md 應該像目錄和作業流程，而不是百科全書。它可以先說明輸入需要哪些檔案、第一步執行什麼檢查、何時讀取 references/api-style.md，以及最後要用哪些條件驗收。若某段內容每次任務都不會用到，就不應放在主檔案中。

用觸發描述解決誤調用問題

description 不只是摘要，而是 Agent 判斷「現在是否適合使用這個 Skill」的重要訊號。好的描述同時回答兩件事：

這個 Skill 能完成什麼具體工作；
哪些使用者意圖、檔案類型或任務條件出現時才應啟用。

例如，以下描述過於寬泛：

description: 協助處理 API 開發工作

它可能與程式碼審查、測試、部署、文件產生等多個 Skill 重疊。較清楚的版本是：

description: 檢查 REST API 回應格式、錯誤碼與欄位命名。當使用者要求審查 API response、驗證 JSON schema，或比較實作與團隊 API 規範時使用。

描述不應只堆疊「分析、最佳化、生成、專業、智慧」等能力詞，而應加入可觀察的任務訊號。建立後至少應使用三組測試：

正例：明確提到該 Skill 應處理的任務，確認能被啟用。
反例：只在表面上相似、實際應由其他流程處理的任務，確認不會誤用。
相鄰 Skill 測試：把兩個容易混淆的任務交替輸入，觀察觸發是否穩定。

若一個 Skill 只能靠使用者輸入特定斜線指令才能可靠運作，這不一定是缺陷；對部署、刪除、發佈等高風險操作，明確手動呼叫往往比自動觸發更安全。Claude Code 官方文件也提供 disable-model-invocation 等擴充欄位，讓作者限制由模型自動啟用的情況，但這些行為屬於特定客戶端的擴充，不能直接當成所有 Agent 都支援的通用標準。Claude Code Frontmatter 及呼叫控制說明

把知識、流程與工具分開管理

Agent Skills 和 Prompt 有什麼區別，不能只用「Skill 比 Prompt 強」來回答。比較準確的分工如下：

普通 Prompt：處理單次任務、臨時格式要求或即時補充背景。
Skill：保存穩定方法、固定步驟、領域規則及驗收條件。
Knowledge Base：保存可更新、可搜尋、可能隨時間改變的文件和事實。
MCP：把 Agent 連接到外部服務或工具，例如檔案系統、工單系統、資料庫或 API。
Hook 或受控腳本：在明確事件或批准條件下執行動作。

這種分工可以避免兩類錯誤。第一類是把即時資料當成固定知識：例如部署環境的目前版本，應從可更新來源取得，而不是永久寫在 SKILL.md。第二類是把工具權限當成 Skill 能力：Skill 可以要求 Agent 使用某個工具，卻不能單獨繞過該工具的權限、隔離或確認流程。

Claude Code 官方功能比較也將 Skills、MCP、Hooks 和 Plugins 分開處理：Skills 提供可複用知識與工作流程，MCP 連接外部服務，Hooks 在生命週期事件觸發動作，Plugins 則負責打包與分發。Claude Code 功能總覽

因此，Agent Skills 與 MCP 的合理配合方式是：

Skill 描述任務目標、判斷條件和操作順序；
MCP 提供查詢或操作外部系統的受控介面；
Agent 按 Skill 的驗收規則檢查工具回傳結果；
高風險動作在工具層保留確認、權限和審計。

Skill 可以呼叫腳本嗎？可以，但「可以呼叫」不等於「可以無限制執行」。官方規範允許 scripts/ 放入可執行程式，Claude Code 也支援在 Skill 中引用腳本；實際可用的語言、工具清單和權限，仍由 Agent 實作和執行環境決定。Agent Skills Optional Directories

用安全驗收阻止腳本型 Skill 失控

第三方 Skill 的風險不只在指令內容，也在它附帶的腳本、外部連線和檔案操作。尤其是能執行 Shell、Python 或 JavaScript 的 Skill，安裝前應把它當成一段尚未信任的程式碼，而不是普通文件。

提醒： skills 設定通常只控制哪些 Skill 能被 Agent 發現或呼叫，並不等於沙盒。以 Claude Agent SDK 文件為例，未列入的 Skill 檔案仍可能存在於磁碟上，並且可被其他檔案讀取工具接觸；真正的隔離仍需依靠作業系統權限、容器、伺服器帳戶和工具白名單。Claude Agent SDK Skills 文件

安裝前可逐項完成以下檢查：

[ ] 確認 Skill 的來源倉庫、維護者、提交紀錄及最近一次變更。
[ ] 閱讀授權條款，確認可否在公司專案、內部倉庫或商業環境使用。
[ ] 搜尋 SKILL.md 是否要求讀取密鑰、環境變數、SSH 設定或個人資料。
[ ] 逐一檢查 scripts/，確認是否存在下載、上傳、刪除、權限修改或遠端命令。
[ ] 檢查腳本的網路目的地、檔案寫入範圍及是否使用不必要的系統指令。
[ ] 在隔離環境中測試，先使用沒有敏感資料的專案目錄。
[ ] 將工具權限縮到任務真正需要的最小集合。
[ ] 為輸出建立可驗收結果，例如檔案差異、測試報告或固定格式的紀錄。
[ ] 記錄版本、雜湊值、批准人及撤回方式。
[ ] 對高風險操作保留人工確認，不讓模型單獨完成不可逆動作。

官方 Skills Repository 目前包含文件處理、開發和其他範例能力，可用來研究目錄結構和打包方式，但官方範例不代表所有第三方 Skill 都經過相同程度的安全審查。閱讀官方 Skills Repository 的 README 可了解其範例 Skill、Plugin 分組及安裝方式；實際導入前仍應按上述清單自行驗收。

從一個 Skill 建立團隊能力庫

當 Skill 從個人實驗進入團隊環境，真正的難題會由「能不能觸發」轉成「能不能長期維護」。團隊不應只統計 Skill 數量，而應優先沉澱高頻、輸出可驗收、錯誤成本明確的流程，例如程式碼審查、發佈前檢查、格式轉換和固定報告產生。

每個團隊 Skill 至少需要補足以下治理欄位：

負責人：誰可以批准規則變更，誰負責處理失效回報。
版本：變更是否影響輸入格式、工具權限或輸出結果。
測試任務：固定保留正例、反例和邊界案例。
變更紀錄：說明修改原因、受影響專案及回退方式。
相容性：標明所需的 Agent、作業系統、套件、網路或工具。
廢棄機制：當 Skill 被新版本取代時，如何停止觸發並通知使用者。

Claude Code 可在個人、專案、Plugin 等不同位置發現 Skill；專案 Skill 可隨程式碼一同進入版本控制，適合團隊共享，但不同產品的目錄、命名空間和支援欄位可能不同，不能因為某個客戶端能自動發現，就假定其他 Agent 也會採用相同機制。Claude Code Skill 位置與發現規則

若要把 Skill 部署到遠端開發環境，應先確認檔案來源、工作目錄、工具權限與驗收輸出，再考慮長期維護。涉及雲端工作站、遠端連線或臨時測試環境時，應先查閱服務提供方的環境說明與使用責任，了解連線、權限和資料保存方式；這些設定屬於執行環境層，不應直接寫成 Skill 的固定權限。若需要了解服務背景與團隊責任分工，可參考 Vuncloud 的服務介紹。

若團隊需要比較本地設備與按需使用的遠端 Mac 環境，應先檢查專案是否需要固定硬體、實體介面、長期重負載和持續儲存，再按實際工作週期評估遠端 Mac 租用與本地設備的差異；這類選擇屬於基礎設施決策，不應與 Skill 的觸發規則混為一談。涉及環境交付、連線問題或權限疑問時，應透過 Vuncloud 的聯絡方式確認責任邊界，而不要把基礎設施條件混寫進 Skill 的觸發規則。

在本週完成最小可用 Skill

對第一次建立 Agent Skills 的開發者，建議依照以下順序落地，而不是同時建立大量功能：

選一個高頻且結果可檢查的流程，例如「依團隊規範審查 API 回應」。
建立目錄及 SKILL.md，只先加入 name、description、輸入條件、操作步驟和驗收標準。
為 description 寫一個正例、一個反例，並與最接近的 Skill 做觸發重疊測試。
將不常用的詳細規格移到 references/，不要讓主檔案承擔整個知識庫。
若流程需要腳本，先以唯讀、單一目錄和固定輸入測試，確認錯誤訊息足夠清楚。
在隔離的專案或遠端工作環境中執行，記錄觸發結果、工具呼叫和最終輸出。
讓另一名開發者只看 Skill 文件完成同一任務，檢查流程是否依賴作者口頭補充。
補上版本、負責人、相容性與回退方式，再提交到團隊倉庫。
每次更新後重新執行正例、反例和安全測試，確認描述沒有擴大到不應處理的任務。
當 Skill 長期沒有命中、輸出無法驗收或權限需求持續增加時，考慮拆分、降級或廢棄，而不是繼續加內容。

對需要 Claude Code 遠端開發工作流的團隊而言，Skill 本身只解決「如何描述和重用流程」；伺服器規格、連線穩定性、檔案權限和隔離方式仍需另行設計。若目前只是短期測試第三方 Skill，應先選擇可回退、權限範圍清楚的測試環境，而不是立即把未驗證的腳本放入長期使用的主機。

對這類工作來說，直接把全部內容放進 Prompt 的方案有三個明顯缺點：每次對話都要重複提供背景、長流程容易因上下文膨脹而失去重點，而且團隊難以對版本、權限與驗收結果負責。把穩定流程封裝成 Skill，再把動態資料交給知識源、把外部操作交給受控工具，才是較容易測試和治理的長期做法；若只是需要臨時算力、隔離測試環境或短期 Claude Code 工作站，租用 Vuncloud 的 Mac 環境會比先購置一台長期閒置的設備更容易按專案週期調整。