Skills
基於 Cursor 官方 Skills 文件解釋 skill directories、SKILL.md、frontmatter、paths、scripts 和遷移到 skills。
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 開放標準入口。