在 Cursor 裡創建並使用 Skill
Skill 是什麼
Skill 是 Cursor 中一種教 Agent「怎麼做某件事」的說明文檔。它本質上是 Markdown 文件，不是插件，也不單獨運行；Agent 在合適的時候讀取它，按照其中的步驟和規則執行任務。
常見的用途包括：團隊 Code Review 標準、提交信息格式、某個 API 的調用流程、網絡連通性檢查等。與其每次在對話裡重複粘貼同一段 prompt，不如把這些說明固化成 Skill，Agent 可以自動發現並套用。
基本信息
| 項目 | 說明 |
|---|---|
| 主文件 | 每個 Skill 是一個目錄，內含至少一個 SKILL.md |
| 存儲位置 | 個人：~/.cursor/skills/技能名/；項目：.cursor/skills/技能名/ |
| 格式 | YAML frontmatter + Markdown 正文 |
| 作用範圍 | 個人 Skill 對本機所有項目可用；項目 Skill 隨倉庫共享 |
注意：不要把自定義 Skill 放在 ~/.cursor/skills-cursor/，那是 Cursor 內置 Skill 的保留目錄。
運作原理
- 發現：Cursor 會掃描項目裡的
.cursor/skills/和你個人目錄下的~/.cursor/skills/，收集所有 Skill。 - 匹配：當你在 Agent 對話裡描述需求時，Agent 會依據各 Skill 的
description字段判斷「這份 Skill 是否和當前問題相關」。description裡寫的觸發詞（如「網絡」「連通」「Code Review」）越具體，匹配越準。 - 執行：若匹配成功，Agent 會讀取對應的
SKILL.md，按正文中的步驟執行命令、生成輸出，並按 Skill 中定義的格式（如表格、清單）回覆你。
也就是說：你寫的是「說明書」，Agent 按說明書辦事。說明書寫得好，Agent 就執行得穩。
如何創建：以「網絡連通性檢查」為例
下面用一個簡單的 network-connectivity Skill 為例，說明從零創建一個 Skill 的完整流程。
1. 創建目錄結構
在項目根目錄下：
.cursor/skills/network-connectivity/
└── SKILL.md
項目級 Skill 放在 .cursor/skills/ 下，會隨倉庫一起分享給協作者。
2. 編寫 SKILL.md
主文件分兩部分：YAML 元數據和 Markdown 正文。
元數據（frontmatter）
---
name: network-connectivity
description: >-
Verifies outbound HTTPS and package-registry connectivity from the current
environment using curl and pnpm. Use when the user asks whether the network is
OK, to test internet connectivity, DNS, proxy issues, or registry reachability,
or when they mention 网络, 连通, 联网, ping, or connectivity checks.
---
- name：Skill 的唯一標識，用小寫字母、數字、連字符，最多 64 個字符。
- description：最重要的一欄。要寫清 WHAT（做什麼）和 WHEN（什麼情況下該用），並包含足夠多的觸發詞，方便 Agent 在對話中識別。建議用第三人稱（如 "Verifies..."），不要用 "I help you..." 這類口吻。
正文：步驟與輸出模板
正文裡寫明 Agent 要執行什麼、如何判斷成功/失敗、以及如何彙報結果：
# Network connectivity test
## Steps
### 1. General HTTPS
curl -sI --max-time 5 https://www.cloudflare.com
- Pass: 出现 HTTP 状态行（如 HTTP/2 200）
- Fail: 超时、连接失败或无状态行
### 2. pnpm registry
pnpm ping
- Pass: 退出码 0，显示延迟
- Fail: 非零退出码或超时
### 3. Optional（仅在 1 或 2 失败时）
检查 HTTPS_PROXY、HTTP_PROXY 等环境变量，或执行 nslookup / dig 排查 DNS。
## Report template
| Check | Result | Detail |
|-------------|--------|--------|
| HTTPS (curl)| OK/FAIL| ... |
| pnpm ping | OK/FAIL| ... |
**Conclusion:** [一行总结：OK / 部分失败 / 完全不可达，以及建议的下一步]
這樣 Agent 就知道：先跑 curl，再跑 pnpm ping，按表格輸出結論。需要時才會做可選步驟。
3. 可選：補充文檔
如果步驟較多或需要詳細說明，可以加 reference.md、examples.md 等，在 SKILL.md 裡用鏈接引用，保持主文件簡潔。
如何使用
方式一：自然語言觸發（推薦）
打開 Cursor Agent，用自然語言描述需求，例如：
- 「檢查一下網絡是不是通的」
- 「pnpm 源能不能連上」
- 「按 network connectivity skill 測一下網絡」
若描述裡包含「網絡」「連通」「registry」「代理」等詞，Agent 會根據 description 匹配到該 Skill，讀取 SKILL.md，執行步驟並輸出報告。
方式二：@ 引用文件
若 Agent 沒有自動選用該 Skill，可在輸入框輸入 @，選擇 Files，選中 .cursor/skills/network-connectivity/SKILL.md，再說：「請按這個 Skill 檢查網絡並輸出報告。」
這樣會把 Skill 全文放進上下文，行為最穩定。
方式三：手動執行
不經過 Agent 時，直接在終端執行 Skill 裡的命令，自行對照 Pass/Fail 說明判斷：
curl -sI --max-time 5 https://www.cloudflare.com
pnpm ping
Skill 把「你在對話裡會反覆交代的那段說明」固化成文檔，讓 Agent 在合適時機自動讀取並執行。先理解它是什麼、怎麼運作，再按「元數據 + 步驟 + 輸出模板」的結構去寫，就能在 Cursor 裡高效複用你的工作流程。