2026 年 Cursor Agent Skills 完全指南：從 agentskills.io 到 SKILL.md 實戰

在 Mac 上用 Cursor 寫程式，你是否每次都要把「部署 staging → 跑測試 → 開 PR」整段流程重新講一遍？傳統 Prompt 與 Rules 會佔滿上下文，且無法跨專案複用。Agent Skill 把「如何做一件事」封裝成帶 SKILL.md 的資料夾，由 Agent 依任務按需載入——Anthropic 2025 年底發布的 agentskills.io 開放標準已被 Cursor、Claude Code、Gemini CLI 等 16+ 工具採納。本文給 Mac 開發者一份 2026 實戰指南：Skill vs Rule、三級漸進載入、目錄規範、/create-skill 與遠端 Mac 7×24 工作流。結論：把操作性知識從 Rules 遷到 Skills，description 寫觸發條件而非摘要，專案級放 .cursor/skills/，通用流程放 ~/.cursor/skills/。 下文含痛點 — 概念對照 — 檔案結構 — 五步建立 — 矩陣 — 案例 — 驗收清單。

1. 痛點拆解：為什麼 2026 年還要學 Skill？

1）Prompt 不可複用：每次對話重複 800 字部署說明，Token 浪費且易漏步驟。2）Rule 始終佔上下文：命名規範可以常駐，但「發布 Runbook」不該與每行補全搶視窗。3）跨工具碎片化：`.cursorrules` 只服務 Cursor，Claude Code 另一套設定。4）與 MCP 混淆：MCP 連外部 API，Skill 教 Agent「按什麼順序做」——二者互補。社群規模上，2026 年初已有超過 31,000 個公開 Skill（第三方統計），Cursor Marketplace 可一鍵安裝 Rules + Skills + MCP 組合包。

2. Skill vs Rule：一張表分清職責

維度	Rule（規則）	Skill（技能）
載入時機	會話內持續生效	任務相關時啟用
適用場景	程式碼風格、命名、安全底線	部署、PR、稽核、領域 Runbook
上下文成本	固定佔用	漸進披露，平均更低
類比	新人入職須知	專項操作手冊
Mac 推薦位置	`.cursor/rules/`	`.cursor/skills/` 或 `~/.cursor/skills/`

3. 目錄結構與 SKILL.md 規範

一個 Skill 至少包含 SKILL.md（YAML frontmatter + Markdown 正文），可選 scripts/、references/、assets/：

.cursor/skills/deploy-app/
├── SKILL.md          # 必填：name、description、步驟
├── scripts/
│   ├── validate.py   # 可執行，輸出進上下文，腳本本體不佔 Token
│   └── deploy.sh
├── references/
│   └── REFERENCE.md  # 按需載入的長文件
└── assets/
    └── config-template.json

Frontmatter 範例（description 必須寫何時觸發）：

---
name: deploy-app
description: >-
  當使用者需要部署應用、提到「上線」「發布到正式環境」、
  切換 staging/production 時使用。也適用於 CI/CD 設定問題。
paths:
  - "apps/web/**"
---

# 部署應用

## 執行步驟
1. 部署前執行 `scripts/validate.py` 檢查環境變數完整性
2. 執行 `scripts/deploy.sh <environment>`
3. production 需二次確認；失敗時自動回滾

4. 三級漸進式載入（Progressive Disclosure）

Level 1 — 發現：啟動時只讀所有 Skill 的 name + description（約百級 Token/Skill）。Level 2 — 啟用：任務匹配後載入完整 SKILL.md（建議 <5000 Token）。Level 3 — 執行：按需讀 references/、跑 scripts/（腳本輸出進入上下文，原始碼不佔視窗）。觸發方式：自動（Agent 判斷相關）、手動（輸入 /skill-name）、附加（@skill-name）。

5. Mac 上的發現路徑

路徑	作用域	典型用途
`.cursor/skills/`	專案級	本儲存庫部署、領域 Schema
`~/.cursor/skills/`	使用者全域	提交程式碼、寫測試、開 PR
`.agents/skills/`	跨工具專案級	Claude Code / Gemini CLI 共用
`~/.agents/skills/`	跨工具全域	團隊標準 Runbook

6. 五步建立你的第一個 Skill

Step 1 — 用 Cursor 內建精靈

在 Agent 對話框輸入 /create-skill，用自然語言描述流程（如「Mac 上提交 → 推送 → gh 建立 PR」）。

Step 2 — 校驗 name 與資料夾一致

name 僅小寫字母、數字、連字號，最長 64 字元，且與目錄名一致。

Step 3 — 重寫 description 為觸發條件

❌「本 Skill 包含部署指令」→ ✅「當使用者提到部署、上線、staging 切換時使用」。

Step 4 — 腳本放進 scripts/

複雜邏輯用 Bash/Python，SKILL.md 只寫何時跑、失敗怎麼辦。

Step 5 — 用真實任務驗收

在 Settings → Rules 確認 Skill 已被發現；故意用同義詞觸發，觀察是否啟用。

已有大量 dynamic rules？Cursor 2.4+ 支援 /migrate-to-skills 自動遷移。

7. 2026 生態與 Mac 工作流選型矩陣

能力類型	推薦封裝	Mac 注意點
程式碼風格 / 安全底線	Rule	短、常駐
部署 / PR / 稽核 Runbook	Skill	配 scripts + launchd 遠端節點
呼叫 GitHub / 資料庫 API	MCP Server	Skill 內引用 MCP 工具名
OpenClaw 7×24 Agent	Skill + 遠端 Mac Gateway	見本站 OpenClaw 系列文
本機 MLX / Ollama 驗收	Skill references/	基準腳本放 scripts/

熱門方向包括：Vercel React Best Practices（40+ 效能規則）、PR Skill（gh 自動化）、TDD Skill、社群 Skill Installer。與 OpenClaw skillsSnapshot 排錯配合時，記得 Gateway 重啟後驗證技能快照是否刷新。

8. 最佳實踐速記

• 單一職責：一個 Skill 一個領域，大流程拆成 deploy + verify + rollback 三個 Skill。
• 漸進披露：SKILL.md <500 行，細節進 references/。
• 解釋為什麼：寫「部署前 validate 是為避免缺環境變數導致啟動失敗」，Agent 才能舉一反三。
• 術語一致：全文統一「部署」，勿混用「發布」「上線」「推送」。
• Gather → Act → Verify：先收集資訊，再執行，最後驗證。

9. 深度案例：Mac 租賃場景的 /mac-quote Skill

「一家 Mac GPU 租賃平台把客服重複問答封裝成三個 Skill：/mac-quote（型號+租期→報價單）、/contract-draft（標準合約草稿）、/device-check（歸還檢查清單）。客服在 Cursor 裡輸入斜線指令即可，複雜定價邏輯放在 scripts/quote.py，SKILL.md 僅 120 行。對比遷移前：平均處理時長從 18 分鐘降至 6 分鐘，且 Rules 體積從 12KB 降到 2KB，補全上下文更乾淨。」

對開發者而言，同類思路可用於：把「遠端 Mac 節點驗收」（SSH、連接埠、MLX 基準）做成 Skill，本機 Cursor 觸發，實際腳本在遠端 Mac 透過 SSH 執行——這與「筆電只編排、算力在機房」的分流一致。

10. FAQ 與可引用數字

Q：Skill 和 MCP？ MCP = 工具協定；Skill = 操作指南，可編排多個 MCP 呼叫。
Q：會強制 Agent 犯錯嗎？ 不會，Skill 是指導；寫越清晰，一致性越高。
Q：Cursor 從哪版支援？ 2.4+ 穩定，早期 Nightly 已預覽。

可引用：① 開放標準支援工具數 16+（2026-03）。② 社群 Skill 規模 31,000+（2026 年初估）。③ 案例客服時長 18min → 6min。④ SKILL.md 正文建議 <5000 Token（規範推薦）。

11. 從 Windows/Linux 編排到 Mac 算力節點

純雲端 IDE 或 Windows 也能寫 Skill，但在與 Xcode/FCP/ComfyUI 並行、launchd 常駐 Agent、Metal 側車推理 場景，macOS 仍更順暢。若 Skill 綁定的腳本需要長時間跑測試、批次轉檔或本機 MLX 對照，筆電統一記憶體容易被佔滿——這與只在本機堆 Prompt 不同：Skill 解決「怎麼做」，遠端 Mac 解決「在哪跑」。Windows 上驗證 OpenClaw 可以，但圖形/多媒體工具鏈與 7×24 Gateway 往往要遷到 Mac 或 Linux VPS；若你希望「本機 Cursor 編排 + 機房 Mac 執行」，可把重腳本放到遠端節點的 scripts/，Skill 裡寫 SSH 與驗收標準，本機保持輕量上下文。

若你已在用 Agent Skills 整理工作流，又需要穩定、可租用的 Apple Silicon 算力跑腳本與 Gateway，可考慮 MACGPU 遠端 Mac 節點：專跑 OpenClaw、批次任務與對照測試，筆電只保留 Cursor 與 Skill 編排——統一記憶體留給思考，不算力留給通宵佇列。機房節點通常具備更充裕的記憶體、頻寬與常駐伺服器環境，適合把 CI 腳本、渲染佇列與 Gateway 服務從筆電移出；本機只透過 SSH 觸發與讀取驗收輸出，上下文視窗留給 Agent 推理而非日誌洪流。