2026 Agent Skills 完全指南： 從 SKILL.md 到 Cursor 可複用工作流（含雲端 Mac）

根據 Cursor 官方文件，Skill 是便攜、可納入 Git 的能力包，可包含腳本、模板與參考文件，Agent 在判斷任務相關時自動選用，也可透過 /skill-name 手動觸發。Anthropic 在 2025 年底將同一格式發布為開放標準，規範儲存庫見 agentskills/agentskills，已被多家 Agent 產品採用。

• 每次重講流程：「先跑 lint → 再跑測試 → 再 commit → 再 gh pr create」寫進對話，換一個新工作階段就要重來，且容易漏步驟。
• Rule 始終占上下文：.cursor/rules 裡的命名規範、禁止註解等應持久生效，但若把 200 行部署手冊也塞進 Rule，會固定消耗 Token，無關任務也被載入。
• 無法團隊共享：口頭約定無法 PR Review；Skill 目錄可進儲存庫，新人 clone 即獲得同一套「專項操作手冊」。
• 與 MCP 混淆：MCP 連接外部 API（資料庫、Issue 系統）；Skill 告訴 Agent按什麼順序呼叫已有工具——二者互補，不是替代關係。

一句話：Rule 是入職須知（始終在場），Skill 是部署/稽核/開 PR 的專項手冊（相關時才翻開）。

Cursor 2.4+ 提供內建 /migrate-to-skills，可將部分 dynamic rules 與舊 slash command 遷移為 Skill，避免 Rule 目錄無限膨脹。遷移後建議：Rule 只保留 10 條以內的硬約束，其餘流程性內容進 Skill。

每個 Skill 至少是一個目錄 + SKILL.md（YAML frontmatter + Markdown 正文）。可選子目錄：scripts/（可執行腳本）、references/（長文件）、assets/（模板與設定）。跨工具常見路徑：

• Cursor 專案級：.cursor/skills/your-skill/SKILL.md
• 跨平台專案級：.agents/skills/your-skill/SKILL.md
• 使用者全域：~/.cursor/skills/ 或 ~/.agents/skills/

開放規範建議的漸進式載入分三級：啟動時僅讀所有 Skill 的 name + description（約百級 Token 量級）；任務匹配後再讀完整 SKILL.md 正文（建議控制在約 5000 Token 以內）；執行中才讀取 references/ 或執行 scripts/——腳本輸出進入對話，腳本原始碼不必占滿上下文。

---
name: deploy-staging
description: >-
  Use when the user deploys to staging or says "pre-prod release".
  Keywords: deploy, staging, pre-prod.
paths:
  - "apps/web/**"
---

# Deploy to staging

## Steps
1. Run `scripts/validate.py`
2. Run `scripts/deploy.sh staging`
3. curl health URL; stop if not 200

description 是路由鍵，不是摘要。 應寫「何時觸發、使用者會怎麼說」，而非「本 Skill 包含部署說明」。name 須與資料夾名一致，僅小寫字母、數字與連字號，最長 64 字元（見 agentskills 規範）。

1. 選定單一職責：例如「建立 PR」或「跑安全稽核」，避免一個 Skill 覆蓋「從編碼到部署到寫部落格」；複雜任務拆成多個 Skill 組合。
2. 用對話快速起稿：在 Cursor Agent 輸入 /create-skill，用自然語言描述觸發條件與步驟，讓 Agent 產生初版目錄結構。
3. 手工落盤與命名：在專案根建立 .cursor/skills/pr-release/，確認 name: pr-release 與資料夾名一致。
4. 編寫可驗證步驟：採用 Gather → Act → Verify：先讀 git status / 分支名，再執行 gh pr create，最後用 gh pr view 核對 URL；失敗分支寫清楚（如未登入 gh auth login）。
5. （可選）添加 scripts：把重複 bash 放進 scripts/，正文只寫「為何執行」——例如部署前校驗是為避免缺環境變數導致程序起不來。
6. 實測觸發與遷移：用真實任務語句測試 description 是否命中；在 Cursor Settings → Rules 確認 Skill 已被發現；舊 Rule 可用 /migrate-to-skills 批次轉換後人工刪冗餘。

高品質 Skill 還遵循：術語一致（全文統一「部署」不混用「發布/上線」）、路徑用正斜線、正文控制在約 500 行內，細節放進 references/。

• frontmatter 必填欄位：name（≤64 字元，小寫+連字號）、description（≤1024 字元，非空，用於 Agent 相關性判斷）——來源：Agent Skills Specification。
• 漸進載入量級建議：中繼資料層約百 Token；完整指令層建議 <5000 Token；scripts/ / references/ 僅在需要時載入——來源：同上規範「Progressive disclosure」章節。
• Cursor 可選欄位：paths（glob 限定檔案範圍）、disable-model-invocation: true（僅允許 /skill-name 手動觸發，禁止自動掛載）——來源：Cursor Skills 文件。
• 跨平台目錄：Claude Code 常讀 ~/.claude/skills，Codex CLI 常讀 ~/.codex/skills，Cursor 讀專案 .cursor/skills；同一 SKILL.md 可提交到 Git 供多工具共享（來源：agentskills.io 與各產品文件）。
• 熱門能力方向（2026）：工程向含 PR 自動化、TDD 迴圈、React/Next 效能稽核類 Skill；選型時優先官方或 Marketplace 簽名來源，避免未稽核腳本直接 chmod +x 執行。

FAQ 速答：Skill 不會覆蓋模型自主性，而是提高一致性；全域 Skill 放 ~/.cursor/skills/（通用提交流程），專案 Skill 放儲存庫（與本程式碼庫綁定的發布流程）。穩定支援版本：Cursor 2.4+。

Skill 再完善，也依賴一直線上的 macOS 環境：合蓋筆電會打斷長時間 Agent 迴圈；個人 Mac 關機後 Telegram/OpenClaw 類閘道會掉線；團隊在筆電上混跑 CI 與 Cursor 容易憑證與 Apple ID 衝突。

推薦拓撲：筆電負責日常編碼與 /create-skill 迭代；在租用 Mac 上 clone 同一儲存庫，用 launchd 保持 Cursor CLI / 閘道程序（可參考 OpenClaw launchd 排障文）；PR 類 Skill 在雲端執行 gh pr create，避免個人機睡眠導致半拉子提交。與 CI 混部時，繼續採用 混合 CI 指南 的 PR/Release 拆分，Skill 只管「怎麼做」，建置機只管「跑多快」。

超賣雲主機與「同事舊 Mac 借一台」的常見短板：① 建置與 Agent 搶磁碟 IO，Skill 裡寫的驗證腳本逾時；② 鄰居抖動導致 SSH 斷連、頻寬不穩，長時 Agent 迴圈中途失敗；③ 非裸金屬無法保證 Xcode 版本，Skill 中的 xcodebuild 步驟不可複現。

更穩妥的路徑：在 JEXCLOUD 多區域裸金屬 Mac 上按月開通節點，把專案級 .cursor/skills 與儲存庫一起部署——獨占 Apple Silicon、7×24 線上、可按 sprint 彈性租期。規格與 M4 檔位見 定價頁；區域與下單見 訂單頁。