Cursor Skills 快速上手指南

本文档帮助你快速了解和上手 Cursor 最新版本中的 Skills 功能

📚 目录

1. 什么是 Skill
2. Skill 的核心优势
3. Skill 适用场景
4. 🚀 如何启用和使用 Skills 功能（⭐ 新手必读）
5. 实战案例：创建你的第一个 Skill
6. 最佳实践与建议

---

⚡ 5 分钟快速上手

如果你是第一次使用 Skills，按照以下步骤快速开始：

第 1 步：确认版本（30 秒）

Cursor → 设置 → About → 检查版本 ≥ 0.44.0

💡 详细说明：查看 Cursor_Skills_启用指南.md 了解如何检查和更新版本

第 2 步：启用功能（1 分钟）

Cursor → 设置 → 搜索 "agent" → ✅ 启用
Cursor → 设置 → 搜索 "skills" → ✅ 启用

💡 遇到问题？ Cursor_Skills_启用指南.md 提供了详细的截图和故障排查

第 3 步：测试 Skill（2 分钟）

1. 打开本项目的 skill_practice 目录
2. 在 Agent 中输入："帮我生成 API 文档"
3. 观察 Agent 是否执行了文档生成流程

第 4 步：查看结果（1 分钟）

检查 docs/api/README.md 是否生成

✅ 如果看到生成的文档，恭喜你已经成功使用 Skills！

📚 完整指南：本文档提供概念和最佳实践，启用指南 提供详细的配置步骤

---

什么是 Skill

Agent Skills（技能）是 Cursor 中用于扩展 AI Agent 专业能力的模块化系统。它将特定领域的知识、工作流程和脚本打包成独立模块，让 AI Agent 能够根据任务上下文自动调用相应的技能。

核心特点

• 模块化设计：每个 Skill 是独立的功能单元，包含定义文件、脚本、参考文档等
• 智能触发：Agent 会根据任务内容自动判断是否需要加载某个 Skill
• 可复用性：Skill 可以跨项目、跨团队共享和复用
• 版本控制友好：以文件形式存储，便于 Git 管理和团队协作

Skills vs Rules

特性	Skills	Rules
应用方式	按需动态加载	持续应用于所有任务
上下文占用	仅在相关任务时加载	始终占用上下文
适用场景	特定领域任务	全局编码规范
可移植性	高（独立模块）	中（项目绑定）

---

Skill 的核心优势

1. 🎯 减少重复工作

将标准化流程（如代码审查、API 设计、测试生成）封装为 Skill，Agent 自动执行，无需每次重新描述需求。

2. 🔄 保持项目一致性

团队共享统一的 Skill 集，确保代码风格、工作流程、命名规范等保持一致。

3. ⚡ 提升开发效率

• 自动化流程：一键触发复杂的多步骤任务
• 上下文优化：仅加载相关 Skill，保持上下文清晰
• 减少错误：标准化流程降低人为失误

4. 📦 易于维护和扩展

• 文件化管理，支持版本控制
• 独立模块，便于更新和迭代
• 可通过仓库链接安装和分享

5. 👥 降低团队协作成本

• 新成员快速上手项目规范
• 统一的工作流程减少沟通成本
• 知识沉淀和传承

---

Skill 适用场景

场景 1：标准化流程

适用情况：团队内部有固定的工作流程

示例：

• 代码审查流程（检查点、审查标准）
• PR 模板生成
• 部署前检查清单
• 测试用例生成

场景 2：领域知识集中

适用情况：需要专业领域知识支持

示例：

• 金融系统开发（合规要求、风控规则）
• 医疗应用开发（HIPAA 合规、数据隐私）
• 机器学习项目（模型训练流程、数据预处理）

场景 3：自动化脚本任务

适用情况：需要执行特定的自动化任务

示例：

• 静态代码分析
• 依赖包更新检查
• 性能测试执行
• 文档自动生成

场景 4：团队协作与新人培训

适用情况：需要快速让新成员上手

示例：

• 项目初始化模板
• 开发环境配置指南
• 常见问题解决方案
• 编码规范说明

场景 5：复杂任务拆解

适用情况：多步骤、需要迭代的复杂任务

示例：

• 功能模块开发（设计 → 实现 → 测试 → 文档）
• Bug 修复流程（定位 → 修复 → 测试 → 回归）
• 重构任务（分析 → 计划 → 执行 → 验证）

---

实战案例：创建你的第一个 Skill

本项目在 skill_practice/api_doc_generator 目录下提供了一个完整的 Skill 示例。

案例背景

创建一个 API 文档生成器 Skill，用于：

1. 自动从代码注释生成 API 文档
2. 验证文档完整性
3. 确保所有公开接口都有文档说明

目录结构

skill_practice/
└── api_doc_generator/
    ├── SKILL.md              # Skill 定义文件（核心）
    ├── scripts/
    │   ├── generate_docs.sh  # 文档生成脚本
    │   └── generate_docs.ps1 # Windows PowerShell 版本
    ├── tests/
    │   └── validate_docs.js  # 文档验证测试
    └── references/
        └── api_guidelines.md # API 设计规范参考

工作流程图

┌─────────────────────────────────────────────────────────────┐
│                    Skill 工作流程                            │
└─────────────────────────────────────────────────────────────┘

1. 触发阶段
   ┌──────────────────────────────────────┐
   │ 用户：修改了 API 接口代码            │
   │ 输入：需要更新 API 文档              │
   └──────────────┬───────────────────────┘
                  │
                  ▼
   ┌──────────────────────────────────────┐
   │ Agent 识别关键词：                   │
   │ "API 文档"、"接口文档"、"生成文档"  │
   └──────────────┬───────────────────────┘
                  │
                  ▼
2. 加载阶段
   ┌──────────────────────────────────────┐
   │ Agent 自动加载 api_doc_generator     │
   │ 读取 SKILL.md 中的指令               │
   └──────────────┬───────────────────────┘
                  │
                  ▼
3. 执行阶段
   ┌──────────────────────────────────────┐
   │ 步骤 1：扫描代码中的 API 定义        │
   │ - 识别路由、参数、返回值             │
   │ - 提取注释和文档字符串               │
   └──────────────┬───────────────────────┘
                  │
                  ▼
   ┌──────────────────────────────────────┐
   │ 步骤 2：运行文档生成脚本             │
   │ - 执行 scripts/generate_docs.sh      │
   │ - 生成 Markdown/HTML 格式文档        │
   └──────────────┬───────────────────────┘
                  │
                  ▼
   ┌──────────────────────────────────────┐
   │ 步骤 3：验证文档完整性               │
   │ - 运行 tests/validate_docs.js        │
   │ - 检查所有接口是否有文档             │
   │ - 验证参数说明是否完整               │
   └──────────────┬───────────────────────┘
                  │
                  ▼
4. 反馈阶段
   ┌──────────────────────────────────────┐
   │ 验证通过？                           │
   └──────┬───────────────────────┬───────┘
          │ 是                    │ 否
          ▼                       ▼
   ┌─────────────┐         ┌──────────────┐
   │ 生成成功报告 │         │ 列出缺失项   │
   │ 显示文档路径 │         │ 提供修复建议 │
   └──────┬──────┘         └──────┬───────┘
          │                       │
          ▼                       ▼
   ┌──────────────────────────────────────┐
   │ 用户审查并确认                       │
   └──────────────┬───────────────────────┘
                  │
                  ▼
5. 完成阶段
   ┌──────────────────────────────────────┐
   │ 提交文档更新                         │
   │ 在 PR 中说明使用了 Skill             │
   └──────────────────────────────────────┘

使用方法

方式 1：自动触发

在 Cursor Chat 中输入：

我修改了用户登录接口，请帮我更新 API 文档

Agent 会自动识别并加载 api_doc_generator Skill。

方式 2：显式调用（如果支持）

使用 api_doc_generator Skill 生成最新的 API 文档

预期输出

✅ API 文档生成完成

📄 生成的文档：
- docs/api/authentication.md
- docs/api/user_management.md
- docs/api/data_operations.md

✅ 验证结果：
- 检查了 15 个接口
- 所有接口都有完整文档
- 参数说明覆盖率：100%

💡 建议：
- 在 PR 描述中添加文档链接
- 通知前端团队接口变更

---

最佳实践与建议

1. 📝 清晰的 Skill 定义

SKILL.md 必须包含：

• 名称和描述：简洁明了地说明 Skill 的用途
• 触发条件：列出关键词和适用场景
• 执行步骤：详细的操作流程
• 示例用法：提供具体的使用案例

2. 🎯 单一职责原则

每个 Skill 应该专注于一个特定任务：

• ✅ 好：api_doc_generator（专注于 API 文档）
• ❌ 差：dev_helper（功能过于宽泛）

3. 🔧 提供可执行脚本

• 脚本应该是幂等的（可重复执行）
• 包含错误处理和日志输出
• 提供 Windows 和 Unix 两个版本

4. ✅ 完善的测试验证

• 编写自动化测试脚本
• 验证输出的正确性
• 提供清晰的错误信息

5. 📚 详细的参考文档

在 references/ 目录中提供：

• 相关规范和标准
• 最佳实践指南
• 常见问题解答

6. 🔄 版本控制

• 将 Skill 文件纳入 Git 管理
• 使用语义化版本号
• 记录变更日志

7. 👥 团队共享

• 在团队文档中说明可用的 Skills
• 定期审查和更新 Skills
• 收集使用反馈并改进

8. 🚀 性能优化

• 避免在 Skill 中包含大量数据
• 使用引用而非复制大文件
• 优化脚本执行速度

9. 🔒 安全考虑

• 不在 Skill 中硬编码敏感信息
• 使用环境变量管理配置
• 限制脚本的执行权限

10. 📊 监控和反馈

• 记录 Skill 的使用情况
• 收集执行时间和成功率
• 根据数据优化 Skill

---

🚀 如何启用和使用 Skills 功能

第一步：检查和更新 Cursor 版本

1.1 检查当前版本

Skills 功能在 Cursor 的较新版本中才支持，建议使用 0.44.0 或更高版本。

检查方法：

• 点击 Cursor 左下角的齿轮图标 ⚙️
• 选择 “About”（关于）
• 查看版本号

1.2 切换到 Nightly 版本（可选，获取最新特性）

如果你想体验最新的 Skills 功能：

1. 打开 Cursor 设置（快捷键：Ctrl/Cmd + ,）
2. 搜索 “update channel”
3. 选择 Nightly 更新渠道
4. 重启 Cursor 等待更新

提示：Nightly 版本包含最新功能，但可能不够稳定。如果你需要稳定版本，可以使用 Stable 渠道。

第二步：启用 Agent 和 Skills 功能

2.1 启用 Agent 模式

Skills 功能依赖于 Cursor 的 Agent 模式：

1. 打开 Cursor 设置（Ctrl/Cmd + ,）
2. 搜索 “agent”
3. 找到 “Enable Agent” 或 “Cursor Agent” 选项
4. ✅ 勾选启用

2.2 启用 Skills 功能

1. 在设置中搜索 “skills”
2. 找到 “Agent Skills” 或 “Enable Skills” 选项
3. ✅ 勾选启用

注意：不同版本的 Cursor 界面可能略有差异，如果找不到 Skills 选项，说明你的版本可能还不支持，请更新到最新版本。

第三步：验证 Skills 是否启用

方法 1：通过 Agent 聊天验证

1. 打开 Cursor 的 Agent 聊天窗口（快捷键：Ctrl/Cmd + K）
2. 输入：你支持 Skills 功能吗？
3. 如果 Agent 回复确认支持，说明功能已启用

方法 2：通过项目验证

1. 在项目中创建一个简单的 SKILL.md 文件
2. 在 Agent 中使用触发关键词
3. 观察 Agent 是否自动加载并执行 Skill

第四步：配置 Skills 目录

重要提示：Skill 文件位置非常灵活，你有多种选择：

选项 1：项目特定目录（推荐用于项目专用 Skill）

# 当前项目的做法
your-project/
└── skill_practice/
    └── api_doc_generator/
        └── SKILL.md

优势：

• 与项目代码紧密关联
• 便于版本控制和团队协作
• 自包含性强，易于移植

选项 2：.cursor/skills/ 目录（推荐用于全局共享 Skill）

mkdir -p .cursor/skills

优势：

• 统一管理多个 Skill
• 跨项目复用
• Cursor 优先扫描此目录

选项 3：任意目录

Cursor Agent 会递归扫描项目中的所有 SKILL.md 文件，所以你可以将 Skill 放在任何合适的位置。

关键点：无论放在哪里，Cursor 都能找到并根据上下文自动加载。

第五步：使用 Skills

5.1 三种使用方式

方式 1：自动触发（推荐）

当你的对话内容包含 Skill 的触发关键词时，Agent 会自动加载：

你：帮我生成 API 文档
↓
Agent 自动识别 "API 文档" 关键词
↓
加载 api_doc_generator Skill
↓
执行文档生成流程

方式 2：显式引用

使用 @ 符号显式引用 Skill：

你：@api_doc_generator 为用户模块生成文档
↓
Agent 直接加载指定的 Skill
↓
执行相应操作

方式 3：在 Composer 中使用

在 Cursor 的 Composer 模式中，Skills 会自动参与到多步骤任务中：

1. 打开 Composer（Ctrl/Cmd + I）
2. 描述你的任务
3. Agent 会自动选择合适的 Skills 来完成任务

5.2 验证 Skill 是否被加载

当 Skill 被成功加载时，你会看到：

• ✅ Agent 回复中提到了 Skill 的名称
• ✅ Agent 执行了 Skill 中定义的步骤
• ✅ 输出符合 Skill 中定义的格式

5.3 调试 Skills

如果 Skill 没有被触发，检查：

1. 关键词是否匹配：查看 SKILL.md 中的触发关键词
2. 文件位置：确保 SKILL.md 在项目目录中
3. 文件格式：确保文件名是 SKILL.md（大写）
4. Agent 是否启用：确认 Agent 模式已开启

快速测试：验证你的 Skills 设置

运行以下测试来验证一切正常：

测试 1：检查 Skill 文件

# 在项目根目录执行
find . -name "SKILL.md" -type f
# 或 Windows PowerShell
Get-ChildItem -Recurse -Filter "SKILL.md"

应该能看到你的 SKILL.md 文件路径。

测试 2：触发 Skill

在 Cursor Agent 中输入：

帮我生成 API 文档

如果配置正确，Agent 应该：

1. 识别到 api_doc_generator Skill
2. 执行文档生成脚本
3. 输出生成结果

测试 3：查看 Skill 详情

在 Agent 中询问：

我的项目中有哪些可用的 Skills？

Agent 应该能列出项目中的所有 Skills。

---

💡 常见问题解答（FAQ）

Q1: 我的 Cursor 版本找不到 Skills 设置选项？

A: 可能的原因和解决方案：

1. 版本太旧：更新到 0.44.0 或更高版本
2. 功能未发布：切换到 Nightly 渠道
3. 区域限制：某些功能可能分阶段推出

解决步骤：

1. Help → Check for Updates（检查更新）
2. Settings → Update Channel → Nightly
3. 重启 Cursor
4. 等待更新完成

Q2: Skills 功能已启用，但 Agent 不加载我的 Skill？

A: 检查清单：

• SKILL.md 文件名是否正确（必须是大写）
• 文件是否在项目目录中
• 触发关键词是否在 SKILL.md 中定义
• Agent 模式是否启用
• 输入的内容是否包含触发关键词

调试方法：

1. 在 Agent 中输入："显示我的项目中的所有 Skills"
2. 检查 Skill 是否被识别
3. 尝试使用 @skill_name 显式引用

Q3: 可以同时使用多个 Skills 吗？

A: 可以！Agent 会根据任务需求自动加载多个相关的 Skills。

示例：

你：重构用户认证模块，生成测试用例和 API 文档

Agent 可能会加载：
- @code_review Skill（代码审查）
- @test_generator Skill（测试生成）
- @api_doc_generator Skill（文档生成）

Q4: Skills 和 Rules 有什么区别？什么时候用哪个？

A:

场景	使用 Rules	使用 Skills
全局编码规范	✅	❌
命名约定	✅	❌
特定任务流程	❌	✅
自动化脚本	❌	✅
领域知识	❌	✅

简单记忆：

• Rules = 始终遵守的规则
• Skills = 按需使用的工具

Q5: 如何分享我的 Skills 给团队？

A: 三种方式：

方式 1：通过 Git

# Skills 文件已在项目中，直接提交
git add skill_practice/
git commit -m "feat: 添加 API 文档生成 Skill"
git push

方式 2：导出为独立包

# 将 Skill 目录打包
tar -czf api_doc_generator.tar.gz skill_practice/api_doc_generator/
# 分享给团队成员

方式 3：发布到仓库

# 创建独立的 Skills 仓库
# 团队成员可以通过 git clone 获取

Q6: Skills 会占用多少上下文？

A: Skills 采用按需加载机制：

• 未触发时：0 tokens（不占用上下文）
• 触发后：仅加载相关的 SKILL.md 内容
• 智能管理：Agent 会在任务完成后释放 Skill 上下文

对比：

Rules: 始终占用上下文（约 500-2000 tokens）
Skills: 按需占用（仅在使用时，约 200-1000 tokens）

Q7: 可以创建私有的 Skills 吗？

A: 可以！Skills 完全在本地管理：

1. 在项目中创建 Skill
2. 不提交到公共仓库
3. 添加到 .gitignore（如果需要）

# .gitignore
private_skills/

Q8: Skills 支持哪些编程语言的脚本？

A: Skills 支持任何可执行的脚本：

• ✅ Bash/Shell（.sh）
• ✅ PowerShell（.ps1）
• ✅ Python（.py）
• ✅ Node.js（.js）
• ✅ 任何系统可执行的命令

关键：确保系统中已安装相应的运行时环境。

---

常见问题

Q1：Skill 什么时候会被触发？

A：Agent 会根据以下因素判断：

• 用户输入中的关键词
• 当前任务的上下文
• Skill 定义中的触发条件

Q2：可以手动指定使用某个 Skill 吗？

A：取决于 Cursor 版本，部分版本支持显式调用，如：

/use-skill api_doc_generator

Q3：Skill 会影响性能吗？

A：不会。Skills 是按需加载的，只有在相关任务时才会被加入上下文。

Q4：如何调试 Skill？

A：

1. 在 SKILL.md 中添加详细的日志说明
2. 单独测试脚本的执行
3. 查看 Agent 的执行日志

Q5：可以在多个项目间共享 Skill 吗？

A：可以。将 Skill 放在独立的 Git 仓库中，通过链接引用。

---

进阶主题

1. Skill 组合

多个 Skills 可以协同工作：

用户请求 → 触发 Skill A（代码生成）
         → 触发 Skill B（测试生成）
         → 触发 Skill C（文档生成）

2. 条件触发

在 SKILL.md 中定义更复杂的触发条件：

## Trigger Conditions

- 文件类型：*.js, *.ts
- 关键词：API, 接口, endpoint
- 上下文：修改了 routes/ 目录下的文件

3. 参数化 Skill

允许用户传递参数：

使用 api_doc_generator 生成文档，格式为 OpenAPI 3.0

---

资源链接

• Cursor 官方文档
• Agent Skills 指南
• 最佳实践博客
• 社区 Skills 仓库

---

总结

Cursor Skills 是一个强大的功能，它能够：

✅ 提升效率：自动化重复性任务
✅ 保证质量：标准化工作流程
✅ 促进协作：统一团队规范
✅ 降低门槛：帮助新人快速上手
✅ 知识沉淀：将最佳实践固化

通过本指南和 skill_practice 中的示例，你应该能够：

1. 理解 Skills 的概念和优势
2. 识别适合使用 Skills 的场景
3. 创建和使用自己的第一个 Skill
4. 遵循最佳实践优化 Skills

现在就开始创建你的第一个 Skill，让 AI Agent 成为你的得力助手！

---