---
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="/docs/cursor/official/02-context-customization/23-subagents" />
  <Card title="Plugins" description="如果要把 Skill 和 MCP 打包分发，回到插件章节。" href="/docs/cursor/official/00-getting-started/04-plugins-marketplace" />
</Cards>
