Skills
基於 Cursor 官方 Skills 文件解釋 skill directories、SKILL.md、frontmatter、paths、scripts 和遷移到 skills。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Skills | 技能 | 把重複流程打包成可觸發的能力。 |
| 觸發描述 | trigger desc | 決定 skill 何時被載入的描述。 |
| 分發 | distribution | skill 的儲存和團隊共享。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你在 Cursor 裡把一個重複流程做成可觸發的 Skill。
你是 Cursor Skill 建立顧問，幫我把一個重複流程做成結構清晰、能被準確觸發的 Skill。
【角色】
你熟悉 Cursor Skill 的結構、怎麼寫觸發描述、儲存位置和分發方式。
【輸入】
- 想沉澱成 skill 的重複流程：___
- 觸發時機和輸入：___
- 期望輸出：___
- 個人用還是團隊分發：___
【工作流程】
1. 判斷流程是否夠穩定、值得沉澱
2. 寫 skill 骨架（觸發 / 輸入 / 步驟 / 輸出 / 驗證 / 邊界）
3. 寫準確的觸發描述
4. 給儲存和分發建議
【輸出規範】
▌一、是否值得沉澱
▌二、skill 骨架
▌三、準確的觸發描述
▌四、儲存與分發
【硬約束】
- 流程沒跑穩幾次先別沉澱
- 觸發描述準確，防誤觸發或漏觸發
- 邊界寫清
- 指令碼類可審查
- 不確定的機制標註需查官方文件
- 給的骨架可直接用
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Skills 是讓 Cursor Agent 學會特定任務的可複用能力包。官方文件說明，Agent Skills 是開放標準，可以包含 domain-specific knowledge、workflows、scripts、templates 和 references，並按需 progressive 載入資源。
閱讀目標：讀完本章，你應該能判斷什麼時候用 Skill 而不是 Rule，並能寫出一個帶 SKILL.md、frontmatter 和可選 scripts 的最小 Skill。
1. Skill 的特性
官方文件用四個詞描述 Skills：
| 特性 | 含義 |
|---|---|
| Portable | 支援 Agent Skills standard 的 agent 都可用（跨 Cursor / Claude Code / Codex 等） |
| Version-controlled | Skills 是檔案，可放儲存庫或從 GitHub 安裝 |
| Actionable | 可包含 scripts、templates、references |
| Progressive | 按需載入資源，節省上下文（Agent 判斷目前任務匹配 SKILL.md 的 description 時才裝入） |
Skill 適合詳細、多步、可複用流程。Rule 更適合短約束。
2. 自動發現目錄
Cursor 自動從這些目錄載入 skills：
| Location | Scope |
|---|---|
.agents/skills/ | Project-level |
.cursor/skills/ | Project-level |
~/.agents/skills/ | User-level |
~/.cursor/skills/ | User-level |
相容目錄：
.claude/skills/.codex/skills/~/.claude/skills/~/.codex/skills/
Cursor 會遞迴查詢 SKILL.md。Monorepo 中 nested project directory 的 skills 會自動 scoped 到該目錄下檔案。
3. 最小結構
.agents/
└── skills/
└── my-skill/
└── SKILL.md可選目錄：
.agents/
└── skills/
└── deploy-app/
├── SKILL.md
├── scripts/
│ ├── deploy.sh
│ └── validate.py
├── references/
│ └── REFERENCE.md
└── assets/
└── config-template.jsonflowchart TD
Skill["Skill folder"] --> MD["SKILL.md"]
Skill --> Scripts["scripts/"]
Skill --> References["references/"]
Skill --> Assets["assets/"]
MD --> Agent["Agent decides relevance"]
Scripts --> Tools["Agent may execute scripts"]
References --> Context["Loaded on demand"]4. SKILL.md frontmatter
官方要求 SKILL.md 使用 YAML frontmatter。
---
name: react-component-patterns
description: Conventions for writing React components in this codebase.
paths:
- "**/*.tsx"
---
# React component patterns
...關鍵欄位：
| Field | Required | 說明 |
|---|---|---|
name | Yes | lowercase、numbers、hyphens；必須匹配 parent folder name |
description | Yes | agent 判斷相關性的核心 |
paths | No | 限定 skill 只在匹配檔案時 surfaced |
license | No | license 或 bundled license 引用 |
compatibility | No | 系統包、網路等環境要求 |
metadata | No | 任意 metadata |
disable-model-invocation | No | true 時只能透過 /skill-name 顯式呼叫 |
舊 globs 欄位仍可 fallback，但新 skills 應使用 paths。
5. 什麼時候用 Skill 而不是 Rule
官方 Help Center 給出清晰對比。
| 維度 | Rules | Skills |
|---|---|---|
| Purpose | 短編碼指導和約束 | 多步 workflow 和 procedure |
| Length | 幾行到幾百行 | 更長，包含詳細步驟 |
| How applied | 每次或匹配時 included | /skill-name 或 @skill-name 按需呼叫 |
| Example | “新檔案用 TypeScript” | “部署 staging：測試、構建、部署、健康檢查” |
深讀：為什麼 scripts 要寫成可執行黑盒
Skill 可以帶 scripts/，Agent 會根據 SKILL.md 說明執行它們。指令碼越清晰，Agent 越不需要讀大量原始碼猜怎麼用。
因此指令碼應自包含、錯誤資訊清楚、引數明確，最好支援 --help。這樣 Skill 才是可複用能力包，而不是一堆只能作者自己看懂的檔案。
6. 遷移 Rules 和 Commands 到 Skills
官方文件說明 Cursor 2.4 有內建 /migrate-to-skills skill，可以把已有 dynamic rules 和 slash commands 轉成 skills。
會轉換：
- Dynamic rules：
alwaysApply: false或未定義，且沒有globspatterns。 - Slash commands：使用者級和 workspace 級 commands，保留顯式呼叫行為。
不會遷移：
alwaysApply: true的 rules。- 帶特定
globs的 rules。 - User rules，因為它們不存檔案系統。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Skill 的
description和paths分別控制什麼？ - 為什麼多步部署流程更適合 Skill，而不是 Rule？
/migrate-to-skills會遷移哪些規則和命令，哪些不會？
透過標準：你能建立一個 .cursor/skills/<name>/SKILL.md，並寫出清晰 description、適當 paths 和指令碼使用說明。
官方來源
- Cursor Skills —— 官方說明 Skill 標準、目錄、frontmatter、paths、scripts、optional directories、檢視和遷移。
- Cursor Skills Help —— Help Center 解釋建立、使用、scope、Rules 對比和遷移到 skills。
- Agent Skills Open Standard —— 官方引用的 Agent Skills 開放標準入口。