📋 本文目錄

01 · 為什麼需要 Agent Skill（而非重複 Prompt）

在 Cursor、Claude Code 這類 AI 程式助手裡，Agent Skill 是一套可被智慧代理按需發現、啟用並執行的指令包。與每次對話臨時貼上的長 Prompt 不同，Skill 以 SKILL.md 形式沉澱在倉庫或使用者目錄，由系統在合適任務場景自動掛載——等同給 Agent 一本「崗位手冊」，而不是每次 onboarding 都重新口述公司規章。

重複 Prompt 的典型問題是：無法納入 Git、難以在團隊間共用、無法被其他 Agent 執行環境複用。當你把「依我們公司的 PR 規範寫描述」「部署前要跑這三條指令」寫進 Skill，新成員 clone 同一倉庫就能獲得一致行為；聊天紀錄裡的 Prompt 卻會在換模型、清上下文或切專案後消失。2026 年起，Cursor 2.4+ 將 Skill 與 Rules、MCP 並列納入 Agent 能力棧：Skill 專門承載流程性、領域性、可重複的工作流知識。

若你已在 Mac 上跑 OpenClaw 與 OpenHuman 雙 Agent，可把 Skill 視為「只教 Agent 怎麼做某類事」的模組化擴充；與全域 Rules（始終生效的約束）和 MCP（對外部系統的即時呼叫）互補。下文對照表可避免三者混用導致上下文膨脹、拖慢無關對話。

02 · 三大痛點：重複 Prompt 的代價

在把團隊經驗沉澱為 Skill 之前，多數工程組織會先踩過下面三種低效模式：

上下文漂移：同一段「提交訊息用繁中、禁止 force push」的說明，在不同 session 被模型截斷或遺忘，導致偶發違規；長 Prompt 佔用 token，擠掉真正用來讀程式碼的視窗。
知識孤島：資深工程師腦中的部署 checklist 傳不到實習生用的 Agent；每人維護自己的「魔法 Prompt」文件，merge 時互相覆蓋，沒人負責 code review。
腳本型工作流不敢自動化：Skill 若含 bash、npm publish、fastlane 等命令，在主力開發機上讓 Agent 全自動執行風險過高；缺乏可丟棄的隔離環境試跑，團隊寧願繼續手動複製指令。

Agent Skill 透過版本控制的 Markdown + 可選 scripts 目錄解決前兩點；第三點建議搭配本文第十節「租用 Mac 五步隔離試跑」——在乾淨 macOS 節點驗證後再 merge 進 main。

03 · Skill 與 Rule 決策矩陣

Cursor 使用者常問：「這段說明該寫進 .cursor/rules 還是 Skill？」核心差異在是否始終注入與是否綁定特定任務類型。

維度	Agent Skill	Cursor Rule
載入時機	任務匹配時按需啟用	對話內持續生效
典型內容	PR 流程、發布檢查、SDK 整合步驟	程式風格、禁止 amend、語言偏好
存放位置	`.cursor/skills/` 或使用者級 skills	`.cursor/rules/` 或 `AGENTS.md`
對 token 影響	僅相關任務時佔用	每條 Rule 都可能常駐
適合誰維護	領域負責人（DevOps、SDK 組）	架構／工程規範負責人

簡單決策口訣：「希望 Agent 每次對話都遵守」→ Rule；「只有使用者提到某類任務才需要」→ Skill。 切勿把 500 行的部署手冊塞進 always-on Rule，否則連改 CSS 的對話都會被拖慢。

04 · 目錄結構與 SKILL.md 規範

專案級 Skill 建議放在倉庫根目錄 .cursor/skills/<skill-name>/SKILL.md；個人通用 Skill 可放在 ~/.cursor/skills-cursor/。每個 Skill 是一個資料夾，而非單檔散落。

                        # 建議目錄範例

.cursor/skills/deploy-staging/

├── SKILL.md          # 必填：frontmatter + 主流程

├── scripts/          # 可選：可執行腳本

│   └── smoke-test.sh

└── references/       # 可選：長文件，按需讀取

    └── rollback.md

SKILL.md 頂部必須使用 YAML frontmatter，其中 name 與 description 為必填。description 是路由鍵：Agent 在「發現階段」只讀所有 Skill 的 name + description，再決定是否進入「啟用階段」載入全文。因此 description 應寫清做什麼、何時用、排除條件，而不是行銷標語。

                        ---

name: deploy-staging

description: Staging 環境發布檢查清單。在使用者要求部署到 staging、預發布驗證或執行 smoke test 時使用。含 SSH 與 npm 步驟，不用於 production。

---

# Staging 發布

## 前置條件

...

05 · 三級漸進載入機制

為控制上下文成本，Cursor Agent Skill 採三級漸進載入：

第一級 · 發現（Discovery）：啟動或規劃任務時，系統掃描可用 Skill 列表，僅將每個 Skill 的 name + description 注入中繼資料層。
第二級 · 啟用（Activation）：使用者意圖與 description 匹配時，將整份 SKILL.md 正文載入上下文。
第三級 · 按需（On-demand）：scripts/、references/ 預設不載入；僅當正文指示「讀取 references/foo.md」或「執行 scripts/bar.sh」時才透過工具存取。

理解這三級後，你會明白為何要把長 API 文件拆到 references/，以及為何主檔應維持在約 500 行以內——否則啟用階段會一次吃掉過多 token，在遠端 SSH 連線、頻寬有限時尤其明顯。

06 · 如何建立 Skill（六步流程）

建立方式分兩類：對話內引導與手動撰寫。

方式 A：使用 /create-skill

在 Cursor Agent 對話輸入 /create-skill 或「幫我建立一個 Skill」，會進入官方引導：收集用途、觸發場景、步驟與約束，並產生符合 frontmatter 的目錄結構。

方式 B：手動六步（適合團隊標準化）

定義單一職責：一個 Skill 只解決一類任務（例如「建立 GitHub PR」）。
撰寫可路由的 description：用第三人稱寫清觸發詞與排除場景。
mkdir 並建立 SKILL.md：在 .cursor/skills/your-skill/ 下新建檔案。
拆分附屬資源：超過 100 行的參考表、Shell 腳本放入 references/、scripts/。
本機對話驗證：用與 description 一致的說法請求 Agent，確認 Skill 被啟用。
提交 PR 並寫 README 索引：避免成員重複造輪子。

團隊亦可把 Skill 目錄納入 CI：檢查 frontmatter、禁止提交密鑰、對 scripts/*.sh 跑 shellcheck。

07 · 最佳實務與硬限制

📌 三條硬數據（2026 生態）：

開放技能目錄 agentskills.io 已索引超過 31,000 個社群 Skill；
Cursor 自 2.4+ 起在 IDE 內原生支援專案級與使用者級 Skill 發現；
官方建議 SKILL.md 正文控制在約 500 行以內，更長內容應拆至 references。

實務要點：

description 即路由鍵：寫「Use when…」式觸發條件；
單一職責：多個獨立流程應拆成多個 Skill；
腳本註明副作用：會改磁碟、調 API、發版的步驟必須加粗警告；
與 Rule 分工：全域「禁止」放 Rule，流程「怎麼做」放 Skill；
定期修剪：過時 Skill 會在錯誤任務上誤導 Agent。

08 · 2026 技能生態一覽

2026 年 Agent Skill 已從「Cursor 私有技巧」演進為跨工具 interchange 格式。agentskills.io 提供開放規範與搜尋；Cursor Marketplace 則分發經初步審核的 Skill 包。常見組合是：Skill 固化倉庫內工作流，MCP 連 Jira／資料庫，Rule 鎖安全紅線。

硬體方面，撰寫 Skill 本身對算力要求不高；若 Skill 含本地模型推理或 Xcode 建置，可參考 Mac 裸機算力定價頁，評估按日租用與自購哪個 TCO 更划算。機房節點通常提供穩定頻寬與獨立 記憶體 配置，適合在遠端 伺服器 上跑長時間 smoke test。

09 · FAQ：Skill、MCP 與作用域

Skill 和 MCP 有什麼差別？

Skill 是靜態／半靜態的 Markdown 指令與可選腳本；MCP 是執行時期協定，讓 Agent 呼叫外部工具。要即時讀 production 資料庫仍應配置 MCP；要統一「發版前檢查清單」則用 Skill。

全域 Skill 和專案 Skill 放哪裡？

專案級：<repo>/.cursor/skills/，隨 Git 共用。使用者級：~/.cursor/skills-cursor/。同名時一般以專案級為準（以 Cursor 當版文件為準）。

Skill 會被自動執行嗎？

Skill 指導 Agent 如何執行，但是否呼叫終端機仍受權限與使用者確認策略約束。含破壞性命令的 Skill 務必在 description 標註，並優先在隔離環境試跑。

可以從 agentskills.io 直接匯入嗎？

匯入後務必改寫 description以匹配你們的技術棧，並審查 scripts/，勿盲目信任第三方 shell。

遠端連線與計費細節：《按日租用 Mac 指南：SSH、VNC 與費用 FAQ》。

10 · 租用 Mac 隔離試跑腳本型 Skill（五步）

當 Skill 包含 npm test、docker compose、Xcode 簽章打包等命令時，不建議先在個人主力機上讓 Agent 全自動執行。更穩妥的是在可丟棄的租用 Mac 上驗證，再 merge 到 main。

租用節點：選 Apple Silicon、預裝 Xcode／Homebrew 的 macOS 映像（如 Mac mini M4），以 SSH 或 VNC 連線。
clone 倉庫到隔離機：使用唯讀 token 或臨時 fork，避免 Skill 腳本接觸 production 密鑰。
僅啟用待測 Skill：暫時停用其他實驗性 Skill，觀察 Agent 是否依 SKILL.md 逐步執行。
記錄命令與結束代碼：將終端機輸出存成驗收證據；失敗則改 SKILL.md 或 scripts，而非在正式機重試。
通過後合併並釋放環境：確認無誤後提交 Skill PR；釋放租用實例，避免持續計費。

Windows 雲主機或 Linux VPS 可跑部分 Node／Python Skill，但涉及 Xcode、iOS 簽章、Apple 公證、Keychain 的步驟仍依賴真實 macOS。按日租用 Mac 可在與 production 一致的系統上試跑 Skill，成本遠低於證書誤操作；算力單價可對照 M 系列租用與自購 TCO。