本文介紹了代理技能（Agent Skills）作為教導 AI 程式碼代理執行重複性工作的標準方式，並說明如何透過編寫一個 SKILL.md 檔案，使其能在 Claude Code、Cursor、OpenAI Codex 等多個平台通用。指南中詳細闡述了 SKILL.md 的格式、如何建立與驗證技能，並透過實例展示了為 Next.js 應用程式進行安全檢查的具體步驟。
代理技能（Agent Skills）現已成為教導 AI 程式碼代理執行重複性工作的標準方式。只需編寫一個 SKILL.md 檔案，Claude Code、Cursor、OpenAI Codex、GitHub Copilot 和 VS Code 都能載入它。甚至 Next.js 16.4 也內建了可透過 npx skills add 安裝的技能。
本指南將建立一個真實的技能 next-security-check，用於檢查 Next.js 應用程式是否符合 2026 年 10 月的安全建議。我將使用官方 skills-ref 驗證器進行驗證，並透過 skills CLI 安裝它。
過程中會涵蓋 SKILL.md 格式、每個代理實際讀取的資料夾，以及導致技能無法觸發的常見錯誤。以下每條規則都引用自 Agent Skills 規範或各代理的官方文件。
什麼是代理技能？代理技能是包含指令、腳本和參考檔案的資料夾，AI 代理會根據需求載入它們來執行特定任務。每個技能都是一個目錄，其中必須包含一個 SKILL.md 檔案：它由帶有 name 和 description 的 YAML 前置資料（frontmatter），以及 Markdown 指令組成。
代理在啟動時只會讀取 name 和 description，並在任務匹配時載入其餘內容。根據 Agent Skills 概述，此格式「最初由 Anthropic 開發，作為開放標準發布，並已被越來越多的代理產品採用」。客戶展示頁面列出了支援此格式的工具，包括 Claude Code、Cursor、OpenAI Codex、GitHub Copilot、VS Code、Gemini CLI、OpenCode、Goose 和 JetBrains Junie。
| 術語 | 意義 |
|---|---|
| 技能 (Skill) | 包含 SKILL.md 以及可選的 scripts/、references/、assets/ 的目錄。 |
| SKILL.md | 前置資料（name、description、可選欄位）後接 Markdown 指令。 |
| 啟用 (Activation) | 代理判斷技能相關，或您透過 /skill-name 或 $skill-name 呼叫它。 |
| 漸進式揭露 (Progressive disclosure) | 先載入中繼資料，啟用時載入主體，僅在需要時載入資源。 |
| skills-ref | Agent Skills 專案的參考驗證器。 |
| skills CLI | Vercel Labs 的安裝器（npx skills add），用於將技能複製或連結到每個代理的資料夾中。 |
為何代理技能現在如此重要？技能之所以重要，是因為它們是第一個跨供應商運作的代理客製化格式。同一個資料夾可以在 Claude Code、Cursor、Codex 和 Copilot 中執行。框架團隊現在也開始發布它們：Next.js 16.4 版本指示您執行 npx skills add vercel/next.js --skill next-bundle-optimizer，然後在「您選擇的 AI 代理中」執行 /next-bundle-optimizer。
在 2026 年 10 月 17 日執行 npx skills add vercel/next.js --list 顯示了官方的 Next.js 技能，包括：next-bundle-optimizer（審核並減少瀏覽器初始載入工作）、next-cache-components-adoption（啟用快取元件並修復其顯示的阻塞路由）、next-cache-components-optimizer（擴展靜態外殼，由 instant() 測試保護）、next-partial-prefetching-adoption 和 next-partial-prefetching-optimizer，以及 next-dev-loop（針對正在運行的 next dev 驗證運行時行為）。
如果您已經遵循我的 Next.js 快取使用指南，next-cache-components-adoption 就是自動化該遷移的技能。
技能與 AGENTS.md、規則和 MCP 有何不同？技能是一種按需執行的程序。AGENTS.md 和規則檔案是始終啟用的上下文，而 MCP 伺服器則是一種即時工具連線。
對於每個任務都需要的事實，請使用 AGENTS.md；對於只有部分任務需要的多步驟工作，請使用技能；當代理必須呼叫外部系統（例如資料庫或 API）時，則使用 MCP。
| | AGENTS.md / CLAUDE.md / 規則 | 代理技能 (SKILL.md) | MCP 伺服器 |
|---|---|---|---|
| 載入時機 | 每個會話 | 啟動時載入名稱和描述；啟用時載入主體 | 啟動時載入工具列表；運行時進行呼叫 |
| 最佳用途 | 慣例、指令、專案事實 | 可重複的程序、清單、腳本 | 其他系統中的即時資料和動作 |
| 包含內容 | Markdown | Markdown + 腳本 + 參考資料 + 資產 | 運行中的程式碼 (stdio 或 HTTP) |
| 上下文成本 | 始終支付 | 使用前約 100 個 token | 工具綱要，按伺服器付費 |
| 可攜性 | 大部分可攜，檔案名稱不同 | 是，一個開放規範 | 是，一個開放協定 |
Claude Code 的文件說得很好：當您「不斷將相同的指令、清單或多步驟程序貼到聊天中，或者當 CLAUDE.md 的某個部分已發展成一個程序時」，就應該建立一個技能（Claude Code skills）。對於始終啟用的部分，請參閱 AGENTS.md vs CLAUDE.md vs Cursor rules。對於即時工具，請參閱如何在 Next.js 中建立 MCP 伺服器。
SKILL.md 格式是怎樣的？一個 SKILL.md 檔案以 --- 行之間的 YAML 前置資料開始，然後是自由格式的 Markdown。規範只要求兩個欄位：name 和 description。license、compatibility、metadata 和實驗性的 allowed-tools 則是可選的。
主體沒有強制結構，只需寫下代理應遵循的步驟即可。本指南中技能的資料夾佈局如下：
.agents/skills/next-security-check/
├，SKILL.md # 必填：前置資料 + 指令
├，scripts/
│ └，check-next-security.mjs # 代理執行的程式碼
└，references/
└，advisories.md # 僅當 SKILL.md 指向它時才載入
| 欄位 | 必填 | 規範規則 |
|---|---|---|
| name | 是 | 1-64 個字元；小寫字母、數字和連字號；無開頭、結尾或連續連字號；必須與資料夾名稱匹配。 |
| description | 是 | 1-1024 個字元；說明技能功能及使用時機。 |
| license | 否 | 授權名稱或捆綁的授權檔案。 |
| compatibility | 否 | 最多 500 個字元；所需的工具、網路存取、目標產品。 |
| metadata | 否 | 字串到字串的映射，例如 author、version。 |
| allowed-tools | 否 | 以空格分隔的預先核准工具，例如 Bash(git:*)；實驗性功能，支援程度各異。 |
代理會在這些基礎上添加自己的可選欄位。Claude Code、Cursor 和 VS Code 都支援 disable-model-invocation: true，這會讓技能只在您輸入 /skill-name 時執行。Claude Code 和 VS Code 也支援 user-invocable: false，以從 / 選單中隱藏背景技能（VS Code agent skills, Cursor skills）。
其他代理會忽略它們不認識的欄位。Claude Code 表示它「會忽略不認識的欄位而不會報告錯誤」。
如何逐步建立代理技能？要建立代理技能，請在 .agents/skills/ 內建立一個以技能命名的資料夾，然後添加一個 SKILL.md 檔案，其 name 必須與資料夾名稱匹配，description 說明使用時機，接著在主體中編寫編號步驟。將較長的材料放入 references/，程式碼放入 scripts/，並使用 skills-ref validate 進行驗證。
步驟一：建立資料夾
mkdir -p .agents/skills/next-security-check/ { scripts,references }
步驟二：編寫 SKILL.md
這是我驗證並安裝的確切檔案：
```
---
name: next-security-check
description: 檢查 Next.js 應用程式是否符合已知的 Next.js 安全建議並進行修補。當使用者詢問其 Next.js 應用程式是否存在漏洞、提及 Next.js CVE 或 GHSA、要求升級 Next.js 以確保安全，或在部署 Next.js 應用程式之前使用。
license: MIT
compatibility: 需要 Node.js 18+ 以及 Next.js 專案中的 npm、pnpm 或 yarn。
metadata:
author: fabwaseem
version: "1.0"
---
1. 從專案根目錄執行檢查器：node .agents/skills/next-security-check/scripts/check-next-security.mjs .。結束代碼 0 表示已修補，1 表示至少有一個建議尚未解決。
2. 如果報告為 VULNERABLE（有漏洞），請閱讀 references/advisories.md 以了解修復版本，然後升級：
3. 再次執行檢查器。在結束代碼為 0 之前，不要報告成功。
4. 執行專案自己的檢查（npm run lint、npm run build），並報告任何失敗，而不是隱藏它們。
5. 告知使用者提交鎖定檔案、重建不帶快取的 Docker 映像並重新部署。修補過的筆記型電腦無法修補生產環境。
報告一個簡短的表格：建議、修補前狀態、修補後狀態、採取的行動。
```
「注意事項」部分包含了我在編寫 Next.js 安全更新指南時，透過艱難方式學到的內容。最佳實踐指南指出，「許多技能中價值最高的內容是注意事項列表」，因為它們是代理無法猜測的事實（Agent Skills best practices）。
步驟三：捆綁腳本和參考資料
將安全文章中無依賴的檢查器複製到 scripts/check-next-security.mjs，並將建議表格保留在 references/advisories.md 中：
```
| 建議 | 嚴重性 | 受影響的 Next.js 版本 | 修復版本 | 解決方法 |
|---|---|---|---|---|
| GHSA-673q-mjm6-r5xr: use cache 返回型別陣列中的 RCE | 嚴重 9.5 | 16.0.0 至 16.4.0 | 16.4.1 | 無 |
| CVE-2026-96889 / GHSA-2464-fhr4-w9xw: 透過影像優化中的 SVG 進行 RCE (sharp, glibc) | 嚴重 9.5 | 10.0.0 至 15.5.27, 16.0.0 至 16.4.0 | 15.5.28, 16.4.1 (sharp 0.35.5+) | sharp 0.35.5+ |
| GHSA-p3m5-59mp-jv5r: 透過 Server Actions 進行 DoS | 高 8.2 | 13.0.0 至 15.5.27, 16.0.0 至 16.4.0 | 15.5.28, 16.4.1 | 無 |
來源：https://nextjs.org/blog/nextjs-security-update-october-14-2026
```
代理只會在步驟二將其發送到此處時讀取此檔案。這就是漸進式揭露（progressive disclosure）按設計運作的方式。
步驟四：單獨測試腳本
一個技能的好壞取決於其腳本，因此請先在代理外部運行它。在一個使用 next@16.4.0 的專案上，它會以結束代碼 1 退出，並顯示：
VULNERABLE GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions
fix: upgrade next to 16.4.1+
2 issue(s) found. Patch, rebuild and redeploy.
在將同一專案升級到 next@16.4.2 後，它會以結束代碼 0 退出，並顯示「所有三個 2026 年 10 月 14 日的建議都已修補」。
如何驗證 SKILL.md 檔案？
使用 skills-ref validate <folder> 來驗證技能，這是 Agent Skills 專案的參考驗證器。它會根據規範檢查前置資料：必填欄位、名稱格式、名稱是否與目錄匹配，以及欄位長度。當技能有效時，它會以結束代碼 0 退出；否則，它會以結束代碼 1 和錯誤列表退出，因此它可以在 CI 中使用。
從官方儲存庫安裝它（該專案稱其為「僅用於演示目的」的參考函式庫，因此請將其視為一個 linter，而非運行時）：
python3 -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
skills-ref validate .agents/skills/next-security-check
我運行時的實際輸出：
Valid skill: .agents/skills/next-security-check
以及我故意測試的三個錯誤：
$ skills-ref validate bad/Next_Security
Validation failed for bad/Next_Security:
- Skill name 'Next_Security' must be lowercase
- Skill name 'Next_Security' contains invalid characters. Only letters, digits, and hyphens are allowed.
$ skills-ref validate bad/next-check
Validation failed for bad/next-check:
- Directory name 'next-check' must match skill name 'next-security-check'
$ skills-ref validate bad/nodesc
Validation failed for bad/nodesc:
- Missing required field in frontmatter: description
skills-ref to-prompt <folder> 會印出代理會注入的 <available_skills> XML 區塊：名稱、描述和位置。閱讀它以了解模型在啟用前如何看待您的技能。
每個代理在哪裡尋找技能？
每個代理都會掃描自己的資料夾，但它們之間存在重疊。.agents/skills/ 由 Codex、Cursor、VS Code 和 GitHub Copilot 讀取。.claude/skills/ 由 Claude Code、Cursor、VS Code 和 Copilot 讀取。
Claude Code 沒有列出 .agents/skills/，因此請將實際資料夾保留在 .agents/skills/ 中，並將其符號連結到 .claude/skills/。
| 代理 | 專案資料夾 | 個人資料夾 | 手動呼叫 | 來源 |
|---|---|---|---|---|
| Claude Code | .claude/skills/ (也可巢狀於 <subdir>/.claude/skills/) | ~/.claude/skills/ | /skill-name | 文件 |
| Cursor | .agents/skills/、.cursor/skills/，以及用於相容性的 .claude/skills/ 和 .codex/skills/ | ~/.agents/skills/、~/.cursor/skills/、~/.claude/s | | |
覺得值得一看？分享給朋友。
以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有， 建議透過「閱讀原文」前往原始網站，以取得最完整資訊並支持原作者。
43 個來源、每 2 小時更新，太多看不完。電子報每週挑最值得看的幾則，附上 Max 的看法。
