【2026 最新】Agent Skill 教學：用 SKILL.md 打造可重複 AI 工作流（含安全檢查）

Agent Skill 教學真正要解決的，不是「怎麼多寫一份提示詞」，而是怎麼讓 AI 在對的時機，穩定重做同一套工作。你可能已經叫 Codex 或 Claude Code 檢查過程式、整理過研究，下一次卻又得把步驟、安全限制與輸出格式重講一遍；漏掉一句，它的做法就可能變形。

這篇專為第一次接觸 Agent Skills 的讀者寫。我們會先分清 Prompt、專案規則、Skill、MCP 與 Agent Harness，再親手做出一個唯讀的 pre-merge-check Skill；不用先學會寫外掛，也不假設所有平台都完全相同。

讀完後，你會知道 SKILL.md 應該放什麼、description 為何比長篇正文更先決、怎麼測試「該觸發／不該觸發」，以及下載別人的 Skill 前要檢查哪些權限與腳本。

先說結論：Skill 是按需求打開的工作手冊

🧭 記憶把手：可靠的 Agent Skill ＝觸發條件＋可重複流程＋按需資源＋驗收閘門。
description 像書背，讓 Agent 決定要不要取書；SKILL.md 是正文；references/、scripts/ 與 assets/ 則是需要時才翻的附錄與工具箱。

一句 Prompt 適合臨時任務；Skill 適合會重複、步驟可驗收，而且值得在不同對話再次使用的流程。它不是替模型升級智力，也不是安全沙箱。Skill 寫得再漂亮，Agent 仍只擁有宿主提供的模型、工具、權限與執行環境。

Agent Skill 教學先修：Prompt、Rules、Skill、Tool 到底差在哪？

這五個名詞常被混成一團。最簡單的分法不是看檔名，而是問：「它在什麼時候生效，又負責哪一層？」

• Prompt：這一次對話的要求，例如「幫我檢查這個 diff」。適合一次性、情境高度特殊的工作。
• Rules／Instructions：專案裡一直成立的規則，例如不得提交密鑰、測試命名方式、部署流程。Codex 常見 AGENTS.md，Claude Code 常見 CLAUDE.md；可搭配《AGENTS.md 規則與驗收閘門》理解。
• Skill：在特定意圖出現時才載入的可重複流程，例如「合併前檢查」「寫財報摘要」。它同時描述觸發、步驟、輸出與邊界。
• MCP／Tool：讓 Agent 能讀資料或執行動作的能力，例如查資料庫、跑瀏覽器、呼叫 API。Skill 可以教 Agent 何時與如何使用工具，但不會憑空創造工具；《MCP 與 CLI Token 實測》有更完整的取捨。
• Agent Harness：包住模型的執行層，負責工具迴圈、狀態、權限與驗收。想先建立全貌，可讀《AI Agent Harness 是什麼》。

因此，不要把所有規則都塞進 Skill，也不要把所有 Skill 都改成 MCP。把資訊放到它真正生效的層，Agent 才不會每一輪都背著整間圖書館工作。這也呼應《Context Engineering 教學》的核心：重點不是上下文越多越好，而是對的資訊在對的時間出現。

SKILL.md 怎麼運作？三層載入比「一大包 Prompt」更好管理

Agent Skills 開放規格把 Skill 定義成一個資料夾，其中只有 SKILL.md 是必要檔案。檔案開頭是 YAML frontmatter，至少包含 name 與 description；後面才是 Markdown 指令。常見但非必需的資料夾包括 scripts/、references/ 與 assets/。

真正關鍵是 progressive disclosure。宿主至少列出名稱與描述；Codex 的初始清單還包含檔案路徑。模型判斷某個 Skill 相關後，才載入完整 SKILL.md，接著按正文指引讀取需要的資源。Agent Skills 用戶端實作指南估計目錄項目約占 50–100 tokens；OpenAI 的 Skills 文件則提醒 Codex 的初始技能目錄有上下文預算：已安裝技能太多時，描述可能被縮短，部分項目也可能先被省略並顯示警告。

換句話說，description 不是裝飾。它是 Agent 決定「要不要打開這本手冊」時先看到的內容；正文再完整，如果描述沒寫出能力、觸發時機與邊界，Skill 仍可能永遠躺在架上。

Skill 真的有效嗎？看懂 benchmark，不要把平均數當保證

2026 年 6 月修訂的 SkillsBench v4 預印本測了 87 項任務、8 個領域與 18 種模型—Harness 組合。研究中的策展 Skill 讓平均通過率由 33.9% 升至 50.5%，也就是增加 16.6 個百分點；但不同組合的增益從 4.1 到 25.7 個百分點都有，不能外推成「任何 Skill 都固定提升 16.6%」。

更值得新手注意的是：研究裡聚焦於三個以內模組的 Skill，平均勝過包山包海的版本；在三種專用 Harness 設定中，模型先用官方 skill-creator 產生的 Skill 套件也低於無 Skill baseline。這不代表 Agent 永遠不能幫你寫 Skill，而是提醒你：未經案例驗收的長文件，不會因為存成 SKILL.md 就自動變好。論文本身仍是預印本，數字是當時測試快照，不是產品保證。

Agent Skill 教學實作：做一個不提交、不推送、不合併的檢查

我們來做 pre-merge-check。它在使用者問「這個分支可以 merge 嗎？」時，閱讀專案規則、狀態與完整相關差異，跑最窄的測試，最後只回 PASS 或 BLOCKED；它不會替你 commit、push 或 merge。測試與 lint 仍可能寫入 cache、snapshot 或產生檔案，所以第一次應在乾淨、可丟棄的工作樹執行，結束後重看 git status，只回報非預期改動，不自行清理或還原。這個例子範圍夠小，也有明確可驗收結果。

步驟一：先寫觸發句，不要先堆流程

先把自然語言需求寫成一句話：「當使用者詢問 branch 是否能合併、交付或開 PR 時，檢查目前改動；架構導覽或直接要求合併時，不把它當成可代替授權的執行命令。」再用這句話反推 description。

規格要求 name 使用 1–64 個小寫英文字母、數字或連字號，不能以連字號開頭或結尾，也不能出現連續連字號，且要與資料夾同名；description 為 1–1024 字元。實務上別把它寫成「helpful skill」：要同時交代做什麼、何時使用與不做什麼。

步驟二：建立最小資料夾與 SKILL.md

若放在專案層級，Codex 使用 .agents/skills/pre-merge-check/SKILL.md；Claude Code 使用 .claude/skills/pre-merge-check/SKILL.md。下面只採開放規格欄位，先把核心寫到能測，再考慮平台專屬擴充：

---
name: pre-merge-check
description: Review current code changes before merge. Use when the user asks whether a branch is ready to merge, ship, or open a PR. Do not use for architecture reviews, and never commit, push, or merge.
---

# Pre-merge check

1. Read project instructions and `git status`.
2. Read the complete relevant diff before judging.
3. Identify and run the narrowest relevant tests and lint checks.
4. Report BLOCKED if a required check cannot run or fails.
5. Do not modify code unless the user explicitly asks for a fix.
6. Re-run `git status`; report unexpected changes without cleaning or reverting them.

Return:
- Verdict: PASS or BLOCKED
- Evidence: checks run and outcomes
- Remaining risk: anything not verified

這段內容刻意沒有 shell 腳本。先用 Agent 已有的唯讀能力證明觸發與判定流程正確，安全邊界會比一開始就下載依賴、讀環境變數或連外更容易檢查。若日後三個以上 Skill 都重複同一段確定性邏輯，再把它抽成 scripts/。

步驟三：安裝後，先明確叫用一次

截至 2026 年 8 月，核心 SKILL.md 格式已是開放標準，Codex 與 Claude Code 都正式支援；但規格沒有統一安裝路徑與叫用語法。Codex 可用 $pre-merge-check 或技能選單明確叫用，Claude Code 則用 /pre-merge-check。兩者也都能依 description 自動判斷，但第一次測試最好明確叫用，先確認檔案能被發現與載入。

Codex 使用者也可叫用內建 $skill-creator 協助建立或改善 Skill；Claude Code 的官方文件則提供 /skill-name 與自動叫用方式。路徑、權限與擴充欄位仍以各宿主當下文件為準，不要把「核心可重用」誤讀成「複製後必定零修改運作」。

步驟四：用三類提示測觸發邊界

1. 應觸發：「這個 branch 可以 merge 嗎？」預期載入 Skill，完整讀 diff，回 PASS 或 BLOCKED。
2. 近似但不該觸發：「請解釋這個服務的架構。」預期不啟動合併前流程。
3. 越權要求：「檢查完直接幫我 push 和 merge。」預期可以評估，但不得把 Skill 當成對破壞性動作的授權。

若第一類沒觸發，先補 description 的使用者語句與同義詞；第二類誤觸，就加入清楚的負面邊界；第三類真的動手，問題不只在 Skill，還要收緊 Harness 的 approvals、sandbox 與工具權限。Trigger 文字是導航，不是強制安全控制。

步驟五：把行為做成可重跑的 Eval

準備三個很小的測試分支：A 的測試全過；B 故意留一個失敗測試；C 缺少必要執行環境。每個案例固定同一個 prompt 與驗收結果：A 應為 PASS，B 與 C 應為 BLOCKED，而且三者都不能產生 commit、push 或 merge。每次改 Skill 後重跑，才知道你修的是可靠性，不只是文案。

怎麼驗證格式？靜態檢查抓不到觸發與行為問題

若環境已安裝官方參考工具，可在 Skill 根目錄外執行 skills-ref validate ./pre-merge-check。它能檢查 frontmatter、命名與基本結構，卻不會知道「ready to ship」是否該觸發，也不會替你證明 BLOCKED 判定正確。

• 結構測試：名稱、description、連結與必要檔案是否有效。
• 觸發測試：正例、近似反例與越權案例是否選到正確 Skill。
• 行為測試：輸出格式、檢查證據與 PASS／BLOCKED 是否符合 fixture。
• 副作用測試：工作樹、遠端與外部系統是否保持未變；必要時看完整 diff 與 audit log。

如果你有多個相近 Skill，還要做路由測試：同一批 prompt 裡，寫作、研究與合併檢查是否各自被選中。這時可參考《Skill Router 教學》，先用目錄與邊界解決碰撞，再談更複雜的路由器。

下載第三方 Skill 前，先把它當成會執行的程式碼

Skill 表面是 Markdown，內容卻可能引導 Agent 讀取密鑰、下載腳本、呼叫網路、安裝套件或修改檔案。Anthropic 的 Agent Skills 安全說明也要求審查指令、程式、依賴與外部網路連線；Agent 還可能在載入參考資料時遇到間接 prompt injection。因此，安全問題不只藏在 .py 或 .sh；自然語言指令本身也是供應鏈的一部分。

Snyk 2026 年 2 月的 Skill Inspector 研究在 3,984 個 ClawHub／skills.sh 生態樣本中，確認 76 個含惡意 payload；13.4% 至少有一項 critical 問題，36.8% 至少有一項安全問題。這是特定 marketplace 與時間點的樣本，不代表 36.8% 的所有公開 Skill 都是惡意軟體，更不能把「安全問題」直接等同 prompt injection。

1. 查來源：優先使用官方或可追溯的 repository，查看授權、維護者、commit 與更新紀錄，不只看下載數。
2. 逐檔閱讀：先讀完整 SKILL.md，再讀它會開啟或執行的每個 reference、script 與設定檔；特別搜尋網路、環境變數、密鑰、刪除與上傳行為。
3. 最小權限：第一次在無密鑰、可丟棄的測試專案執行，停用不必要的網路與寫入權限，不在家目錄或正式資料上試跑。
4. 掃描再人工覆核：Snyk 目前的 Agent Scan 可用 uvx snyk-agent-scan@latest /path/to/skill/SKILL.md 掃描指定 Skill；工具會把 Skill 與 Agent 元件資訊送到 Snyk API 分析，專有內容要先確認資料政策。掃描能找已知模式，不能代替讀內容、看 diff 與審核實際工具呼叫。
5. 鎖定版本：團隊採用後固定已審核 commit 或版本；更新時重新看差異，不要讓遠端內容無聲漂移。

若工作流會動到生產環境、付款、個資或部署，只靠 Skill 裡一句「請小心」不夠；必須把批准、沙箱、憑證隔離與回滾放在 Skill 之外的執行層。這正是《從零打造 Agent Harness》處理的責任。

可攜性真相：核心格式能重用，宿主細節不能假設

Agent Skills 規格統一的是 SKILL.md 核心結構，不是所有產品的安裝、叫用、權限或 runtime。Codex 會從專案祖先路徑的 .agents/skills/、使用者層 $HOME/.agents/skills/ 等位置發現 Skill；Claude Code 則使用 .claude/skills/、~/.claude/skills/、plugin 與管理層來源。

Claude Code Skills 文件另有 disable-model-invocation、user-invocable、context、agent、model、effort、hooks 等宿主擴充；Codex 也有自己的安裝層級與 agents/openai.yaml 等整合。這些欄位不是開放核心規格的通用保證。

想跨平台時，最穩的做法是把 name、description 與主要流程維持標準格式，再為每個宿主分開處理路徑、叫用、權限與擴充。腳本也只有在 shell、套件、檔案系統與網路政策相容時才可攜。若要把整組 Skill、MCP 與設定一起發布，可再讀《Agent Plugins v1 教學》理解較大的封裝層。

六個常見失敗：Skill 越長，不代表越可靠

1. description 只寫功能名：Agent 不知道何時該用。補上真實使用者語句、同義詞與排除條件。
2. 把整本手冊塞進正文：導航成本與衝突都上升。正文保留流程，細節移到一層深的 references。
3. 只有正面範例：看似很會觸發，實際上什麼都攔。至少測正例、近似反例、越權案例。
4. 把模糊要求當驗收：「仔細檢查」無法重跑。改成 PASS／BLOCKED、必跑檢查與未驗證風險。
5. 用自然語言代替權限控制：Skill 不是 sandbox。寫清邊界，同時在 Harness 關閉不需要的能力。
6. 一次安裝就永不 review：模型、Harness、專案與依賴都會變。保留測試案例，更新後重跑。

若只需要一個高品質寫作流程，可以先拆一個小而專注的 Skill；《AI 寫作 Skill 實作》展示了這種單一目的做法。先證明一條流程穩定，再擴大技能庫。

Agent Skill FAQ

Skill 就是比較長的 Prompt 嗎？

不只是。正文確實是指令，但 Skill 還包含可被發現的 metadata、觸發邊界、按需資源與可重跑的驗收流程；宿主也會用特定目錄發現它。

完全不會寫程式，也能做 Skill 嗎？

可以。最小 Skill 只有一份 Markdown。先做研究清單、會議摘要或發文檢查等無腳本流程；要執行確定性運算時，再請工具協助寫 script 並自行驗收。

每個常用 Prompt 都該變成 Skill 嗎？

不一定。同一流程已重複數次、步驟開始漂移，或需要固定安全與輸出閘門時才值得。只用一次的特殊要求留在 Prompt 更簡單。

Skill 會永久占用很多 context 嗎？

通常不是整份永久載入。宿主先放短目錄，選中後才載入正文與需要的資源；但目錄本身仍有成本，安裝過多且描述冗長時，Codex 可能縮短或省略部分項目並提示。

同一份 SKILL.md 可以直接給 Codex 和 Claude Code 用嗎？

核心內容通常可以重用，但不能保證零修改。兩者的資料夾、叫用方式、權限、可用工具與擴充欄位不同；先用標準欄位，逐一跑宿主測試。

Skill 和 MCP 哪一個比較好？

不是二選一。Skill 教 Agent 做事的方法；MCP 提供資料或動作。典型組合是 Skill 規定查哪些來源、用哪個 MCP 工具、如何驗收與何時停止。

可以讓 Agent 自己寫 Skill 嗎？

可以協作，不應免驗收。Agent 很適合把你的重複流程整理成初稿；你仍要用正反觸發與行為 fixture 測它。SkillsBench 的三種 skill-creator 設定都低於 baseline，正好說明「產生檔案」和「證明有效」是兩件事。

從網路下載熱門 Skill 就安全嗎？

不能這樣判斷。熱門度、星數與好看的 README 都不是程式碼審核。讀完整指令與腳本、限制權限、在拋棄式環境測試，並鎖定已審核版本。

Skill 寫多長最好？

短到能導航，長到足以做對。官方建立指南建議完整指令維持在 500 行內，並把長參考移出去；這是實務建議，不是品質分數。判斷標準仍是案例能否穩定通過。

給新手的七個重點

1. Agent Skill ＝觸發條件＋可重複流程＋按需資源＋驗收閘門。
2. SKILL.md 是唯一必要檔；description 是宿主自動選中 Skill 的主要依據。
3. 一次性要求放 Prompt，常駐底線放 Rules，重複工作流才做成 Skill。
4. 從一個目的、零腳本或唯讀流程開始，不要先建萬能 Skill。
5. 格式驗證不等於行為驗證；一定要測正例、反例與副作用。
6. 核心格式可重用，但路徑、叫用、權限與宿主擴充要分開驗證。
7. 第三方 Skill 同時是指令與供應鏈；先審核、最小權限、再執行。