Cursor Skills 是可移植的技能包，让 AI Agent 获得特定领域的专业能力：每个 Skill 是一个包含 SKILL.md 的目录，可以附带可执行脚本、参考文档和静态资源。放进 .agents/skills/（项目级）或 ~/.agents/skills/（用户级）后，Agent 会在合适的场景自动调用，或通过 /技能名 显式触发。本文介绍 Skills 的目录结构、SKILL.md 格式，以及如何从旧版 rules 迁移。

Cursor Skills：让 Agent 获得可复用专业能力

不同项目都会遇到类似任务——部署代码、生成测试、处理数据库迁移。Cursor Skills 把这些能力打包成可复用的技能模块，放进项目或个人目录后，Agent 每次遇到相关任务都能调用，不用重复在对话里解释"部署怎么操作"。

---

Skill 目录结构

.agents/
└── skills/
    └── deploy-app/           # 技能名（目录名）
        ├── SKILL.md          # 必须：技能说明（AI 读取）
        ├── scripts/          # 可选：可执行脚本
        │   ├── deploy.sh
        │   └── validate.py
        ├── references/       # 可选：参考文档
        │   └── api-docs.md
        └── assets/           # 可选：模板、图片等资源

放置位置：

• 项目级：.agents/skills/（提交到 Git，团队共享）
• 用户级：~/.agents/skills/（所有项目通用，个人私有）

---

SKILL.md 格式

每个 Skill 的核心是 SKILL.md，用 YAML frontmatter 定义基本信息：

---
name: deploy-app
description: 将应用部署到生产环境。当用户提到部署、发布、上线时自动触发。
---

## 部署步骤

1. 运行 `./scripts/validate.py` 检查配置
2. 执行 `./scripts/deploy.sh [环境名]`
3. 验证部署结果

## 注意事项

- 生产环境部署前必须先在 staging 测试
- 如果 validate.py 失败，中止部署

frontmatter 字段：

• name：技能标识符，用于 /技能名 调用
• description：触发条件和功能说明（这是 Agent 决定"什么时候调用我"的依据，要写清楚）

---

调用方式

自动调用：Agent 根据 description 字段判断当前任务是否匹配，匹配时自动加载技能上下文。

显式调用：在输入框输入 / 然后搜索技能名，如 /deploy-app。

查看已安装技能：Cursor Settings > Skills，可以查看、启用/禁用技能，也可以从 GitHub 导入他人的技能包。

---

三层加载机制

Skills 采用渐进式加载，节省 token：

1. 元数据（name + description）：始终在上下文中（~100 词）
2. SKILL.md 正文：技能触发时加载
3. scripts/ references/ assets/：按需加载，脚本可直接执行无需全部读入

这意味着你可以在 Skill 里附带大型参考文档，只有真正需要时才会消耗上下文。

---

从旧版 Rules 迁移

如果之前用 .cursorrules 文件或旧版 Rules/Commands，在对话里运行：

/migrate-to-skills

Agent 会帮你把现有规则和命令迁移成 Skills 格式。

---

与 Claude Code Skills 的对比

	Cursor Skills	Claude Code Skills
目录	.agents/skills/	.claude/skills/
触发方式	自动 + /技能名	自动 + /技能名
文件格式	SKILL.md（YAML frontmatter）	SKILL.md（YAML frontmatter）
版本控制	可提交到 Git	可提交到 Git
导入来源	GitHub 仓库	本地或 Claude.ai 插件

两者几乎同源——Cursor Skills 和 Claude Code Skills 的 SKILL.md 格式高度兼容，核心设计思路完全相同。

---

常见问题

Q: Skill 里的脚本（Python/Shell）会自动执行吗？

不会自动执行，需要 Agent 在任务中主动调用这些脚本（作为终端命令）。执行仍然遵守 Cursor 的权限审批规则。

Q: 从 GitHub 导入的技能安全吗？

和使用任何开源工具一样，需要自己审查 SKILL.md 和脚本内容。Cursor 每次脚本执行都需要你批准，但还是建议先读懂再用。

Q: Skill 的 description 应该怎么写才能触发得准确？

写触发条件而不是功能描述。例如，不写"部署脚本"，而写"当用户提到 deploy、发布、上线、部署到生产时使用此技能"——让 Agent 知道什么情景下该调用你。