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 开放标准入口。