---
title: "Skills"
description: "基於 Cursor 官方 Skills 文件解釋 skill directories、SKILL.md、frontmatter、paths、scripts 和遷移到 skills。"
verifiedAt: "2026-05-09"
---

Skills 是讓 Cursor Agent 學會特定任務的可複用能力包。官方文件說明，Agent Skills 是開放標準，可以包含 domain-specific knowledge、workflows、scripts、templates 和 references，並按需 progressive 載入資源。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼時候用 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. 最小結構

```text
.agents/
└── skills/
    └── my-skill/
        └── SKILL.md
```

可選目錄：

```text
.agents/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   ├── deploy.sh
        │   └── validate.py
        ├── references/
        │   └── REFERENCE.md
        └── assets/
            └── config-template.json
```

```mermaid
flowchart 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。

```markdown
---
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：測試、構建、部署、健康檢查” |

<details>
<summary>深讀：為什麼 scripts 要寫成可執行黑盒</summary>

Skill 可以帶 `scripts/`，Agent 會根據 `SKILL.md` 說明執行它們。指令碼越清晰，Agent 越不需要讀大量原始碼猜怎麼用。

因此指令碼應自包含、錯誤資訊清楚、引數明確，最好支援 `--help`。這樣 Skill 才是可複用能力包，而不是一堆只能作者自己看懂的檔案。
</details>

## 6. 遷移 Rules 和 Commands 到 Skills

官方文件說明 Cursor 2.4 有內建 `/migrate-to-skills` skill，可以把已有 dynamic rules 和 slash commands 轉成 skills。

會轉換：

- Dynamic rules：`alwaysApply: false` 或未定義，且沒有 `globs` patterns。
- Slash commands：使用者級和 workspace 級 commands，保留顯式呼叫行為。

不會遷移：

- `alwaysApply: true` 的 rules。
- 帶特定 `globs` 的 rules。
- User rules，因為它們不存檔案系統。

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Skill 的 `description` 和 `paths` 分別控制什麼？
2. 為什麼多步部署流程更適合 Skill，而不是 Rule？
3. `/migrate-to-skills` 會遷移哪些規則和命令，哪些不會？

透過標準：你能建立一個 `.cursor/skills/<name>/SKILL.md`，並寫出清晰 description、適當 paths 和指令碼使用說明。

## 官方來源

- [Cursor Skills](https://cursor.com/docs/skills.md) —— 官方說明 Skill 標準、目錄、frontmatter、paths、scripts、optional directories、檢視和遷移。
- [Cursor Skills Help](https://cursor.com/help/customization/skills.md) —— Help Center 解釋建立、使用、scope、Rules 對比和遷移到 skills。
- [Agent Skills Open Standard](https://agentskills.io) —— 官方引用的 Agent Skills 開放標準入口。

## 接下來去哪

<Cards>
  <Card title="Subagents" description="繼續理解專門角色如何在獨立上下文中處理任務。" href="/zh-Hant/docs/cursor/official/02-context-customization/23-subagents" />
  <Card title="Plugins" description="如果要把 Skill 和 MCP 打包分發，回到外掛章節。" href="/zh-Hant/docs/cursor/official/00-getting-started/04-plugins-marketplace" />
</Cards>
