SKILL.md 開放標準 · 三級漸進載入 · Cursor / Claude Code 通用 · 遠端 Mac 驗收
誰會遇到這個問題？你已在 Cursor、Claude Code 或 Gemini CLI 裡用 Agent 寫程式，卻每次都要重複貼上「怎麼部署、怎麼開 PR、怎麼跑稽核」——上下文被占滿，Token 帳單卻不見少。結論：把流程封裝成 Agent Skill（一個帶 YAML 標頭的 SKILL.md 資料夾），Agent 按需載入，跨對話複用；涉及 macOS 腳本或 Xcode 步驟時，可在租用 VNC 遠端 Mac上驗收 scripts/ 輸出。本文結構：Skill vs Rule → 檔案規範 → 三級載入 → 建立遷移 → 最佳實務 → 2026 生態 → 實戰案例 → FAQ。
AI Agent 的進化路徑很清晰：聊天機器人 → 任務助理 → 具備專業領域能力的智慧體。傳統 Prompt 有三類痛點：每次對話重複描述複雜流程；無關規則占滿上下文視窗；團隊經驗無法跨專案沉澱。
Agent Skill 把「如何做一件事」封裝成可複用模組：按需載入、節省 Token、跨對話與跨團隊共享。Anthropic 在 2025 年底推動 agentskills.io 開放標準後，Cursor、Claude Code、OpenAI Codex、Gemini CLI 均已相容同一套 SKILL.md 目錄結構。
一句話定義：Skill 是給 AI Agent 寫的操作手冊，讓它在正確時機做正確的事——而不是每次從零推理。
重複勞動：部署、測試、PR 描述每次手寫 Prompt，平均多消耗 2k–8k Token/次。
上下文污染：把 500 行規範塞進 Rules，無關檔案編輯也帶著整包規則。
不可版本化：口頭約定無法 PR Review，新人 onboarding 靠複製貼上聊天紀錄。
平台割裂：同一套部署流程在 Cursor 與 Claude Code 各寫一遍——Skill 標準後可 Git 共享。
| 對比維度 | Rule（規則） | Skill（技能） |
|---|---|---|
| 載入時機 | 始終載入 | 按需 / 相關時載入 |
| 適用場景 | 持久約定（命名、風格） | 複雜工作流（部署、稽核） |
| 上下文占用 | 固定占用 | 動態高效 |
| 觸發方式 | 自動注入系統提示 | Agent 路由 + /skill-name |
| 類比 | 新人入職須知 | 專項操作手冊 |
Skill 還能做什麼？自訂 / 命令（如 /deploy）、多步驟工作流打包、領域知識注入、內嵌 Bash/Python/Node 腳本，以及與 Hooks、MCP 聯動。站內OpenClaw 技能市場實戰講的是產品內外掛；本文講的是跨編輯器通用的 Skill 檔案格式，二者概念相近但生態不同。
標準目錄如下（資料夾名 = skill 名稱）：
.cursor/skills/
└── deploy-app/
├── SKILL.md # 必須
├── scripts/ # 可選：可執行腳本
│ ├── deploy.sh
│ └── validate.py
├── references/ # 可選：按需載入的參考文件
└── assets/ # 可選：範本與靜態資源相容路徑還包括 .agents/skills/（Claude Code、Codex、Gemini CLI）、~/.cursor/skills/（使用者全域）、~/.agents/skills/（跨工具全域）。
--- name: deploy-app description: >- 當使用者需要部署應用到 staging 或 production 時使用。 關鍵字：部署、發布、上線、環境切換。 paths: - "apps/web/**" disable-model-invocation: false --- # 部署應用 ## 執行步驟 1. 執行 `scripts/validate.py` 檢查環境變數完整性 2. 執行 `scripts/deploy.sh <environment>` 3. 驗證健康檢查端點回傳 200
| 欄位 | 必填 | 說明 |
|---|---|---|
| name | 是 | 小寫+連字號，必須與資料夾名一致 |
| description | 是 | 路由鍵：寫觸發條件，不是摘要 |
| paths | 否 | Glob 限定生效檔案範圍 |
| disable-model-invocation | 否 | true 時僅手動 /skill-name 觸發 |
Agent Skills 採用漸進披露（Progressive Disclosure），官方文件與 agentskills.io 均描述為三個階段：
發現階段（啟動時）：只讀每個 Skill 的 name + description，判斷是否與目前任務相關。
啟用階段（匹配時）：讀取完整 SKILL.md 指令本體，按步驟執行。
按需載入（執行中）：讀取 references/ 詳細文件；執行 scripts/ 時只把腳本輸出回傳上下文，腳本本體不占 Token。
觸發方式：自動觸發（Agent 判斷相關，預設）；手動 /skill-name；附加上下文 @skill-name。若 Skill 含危險操作，設 disable-model-invocation: true 強制人工確認後再載入。
可引用資料：社群統計 2026 年初可用 Skill 已超 31,000 個；若全部塞進 Rules，單次對話上下文可能膨脹 10 倍以上——漸進載入讓 Agent「知道有很多手冊，但只翻開目前那一本」。
最快路徑：在 Cursor Agent 對話框輸入 /create-skill，描述你想要的 Skill，Agent 產生目錄與 SKILL.md。
手動建立：在 .cursor/skills/your-skill-name/ 新建 SKILL.md，填寫 frontmatter 與步驟。
可選腳本：把可重複命令放進 scripts/，在正文中用相對路徑引用。
驗證識別：Cursor Settings → Rules，或重啟 Agent 工作階段，確認 Skill 出現在可用清單。
遷移舊規則：Cursor 2.4+ 可用 /migrate-to-skills 將 dynamic rules 與 slash commands 轉成 Skill 資料夾。
Windows 主力機使用者在 Cursor 裡寫好 Skill 後，若 scripts/ 含 bash、xcodebuild 或 notarytool，本機無法真實執行。推薦流程：Git 同步到租用遠端 Mac → VNC 打開 Cursor 或終端 → 觸發 Skill → 核對腳本 exit code 與日誌。涉及鑰匙串、公證、TCC 權限的步驟必須 VNC，與站內遠端 Mac 權限清單一致。
① description 是路由鍵，不是摘要。錯誤寫法：「這個 skill 包含部署相關指令」。正確寫法：「當使用者提到部署、上線、切換 staging/production 時使用」。
② 漸進披露：SKILL.md 控制在 500 行內；細節放 references/；執行邏輯放 scripts/。
③ 單一職責：一個 Skill 聚焦一個領域；「部署 + 安全稽核 + 寫測試」應拆成三個 Skill 組合使用。
④ 解釋為什麼：寫「部署前執行 validate.py，避免缺失環境變數導致服務啟動失敗」，而非只寫「執行 validate.py」。
⑤ Gather → Act → Verify：先收集資訊、再執行、最後驗證——Agent 遇到異常時能舉一反三。
⑥ 術語一致、路徑用正斜線、錯誤處理寫清楚：腳本失敗時是重試、回滾還是中止，須在正文中明確。
| 類別 | 代表 Skill | 用途 |
|---|---|---|
| 開發效率 | Prompt Lookup、Skill Installer、Ralph 編碼循環 | 提升指令品質、安裝其他 Skill、測試驅動自主迭代 |
| 前端 / Web | React Best Practices、Web Design Audit、Next.js Cache Optimizer | Vercel 出品的效能與可及性稽核 |
| 工作流 | PR Skill、TDD Skill、Skill Writer | 提交→推送→開 PR、測試驅動、 meta 技能 |
| 創意 | Remotion Video Editor | 用 React 描述影片並產生剪輯 |
生態要點（2026）：agentskills.io 跨平台通用；Cursor Marketplace 支援一鍵安裝 Rules + Skills + MCP 組合包；Monorepo 下可用巢狀目錄 .cursor/skills/shipping/deploy-staging/SKILL.md 做作用域隔離。
與 MCP 的關係：MCP 連接外部 API（資料庫、瀏覽器、GitHub）；Skill 編排「何時、按什麼順序」呼叫這些工具。例如 PR Skill 可寫：先 git status，再調 GitHub MCP 建立 PR——兩者互補而非替代。
場景：每次發布都要提交 → 推送 → 建立 PR → 寫描述。Skill 指令：提交所有修改 → 推送到新分支 → 用 gh pr create 開 PR → 按範本填描述。一個 /pr 完成全流程。
場景：反覆改程式直到測試通過。Skill 邏輯：執行測試 → 失敗則 Agent 修改 → 重跑 → 循環至通過。配合 Hooks 可在 CI 失敗時自動喚醒 Agent。
場景：Windows 開發者維護含 xcodebuild archive、notarytool submit 的 Skill。本機 Cursor 只能編輯 Markdown；真實驗收在 VNCMac 遠端 Mac：VNC 連線 → 觸發 Skill → Agent 執行腳本 → 圖形介面點鑰匙串「始終允許」。這與公證 staple 驗收清單同一類「SSH 不夠、須 VNC」剛需。
| 驗收項 | 本機 Windows | 遠端 Mac + VNC |
|---|---|---|
| 編輯 SKILL.md | 可以 | 可以 |
| 跑 bash 部署腳本 | WSL 部分可 | 完整 macOS 環境 |
| xcodebuild / 公證 | 不可 | 必須 |
| 鑰匙串 / TCC 彈窗 | 不可 | VNC 圖形點擊 |
Skill 是結構化指導，不是強制執行。Model 仍自主決策；description 與步驟越清晰，一致性越高。安裝社群 Skill 前建議閱讀 scripts/ 內容。
用真實任務測試 description 中的觸發詞；未自動載入時可手動 /skill-name；仍失敗則補充同義詞到 description 首段。
通用工作流（提交程式碼、寫測試）放 ~/.cursor/skills/；專案特有邏輯（本儲存庫部署路徑、內部 API）放儲存庫內 .cursor/skills/ 並提交 Git。
格式理念相似（可複用能力模組），但 OpenClaw 技能市場走 ClawHub 安裝與 Gateway 外掛體系；Cursor Agent Skill 走 SKILL.md + agentskills.io 標準。可並存：OpenClaw 跑 7×24 Gateway，Cursor Skill 管日常編碼工作流。
Agent Skill 把團隊裡「只有資深同事知道」的操作流程，變成可版本化、可 Review、可跨平台共享的 SKILL.md。description 寫觸發條件、正文寫 Gather-Act-Verify、腳本放 scripts/ 省 Token——這三條做到，Agent 就從「每次重新教」變成「翻開手冊就能幹」。
局限也很現實：含 macOS 編譯、公證、鑰匙串的 Skill，在 Windows 本機只能寫不能驗；純 SSH 遠端 Mac 又點不了系統彈窗。自購 Mac mini 適合已全年跑 Agent 的團隊；仍在搭建 Skill 庫、或只需按月驗收 iOS/macOS 腳本的使用者，租用 VNC 遠端 Mac把「寫 Skill」與「跑 Skill」拆到兩台機器——主力機 Cursor 編輯，雲端 Mac 圖形驗收——比為 occasional 需求買斷硬體更划算。
Skill 的價值在複用，複用的前提是環境跑得通。下方進入遠端 Mac 套餐，為 macOS 專屬 Skill 準備一台可 VNC 驗收的節點。