Cursor Skill 概念、编写与接入指南

Cursor Skill 概念、编写与接入指南

第一步：Skill 是什么

一句话定义：Skill（技能）是一份 Markdown 文件，教会 Cursor AI 如何执行特定任务——代码审查、生成提交信息、查询数据库等任何专业化工作流。

类比理解：把 Skill 想象成岗位操作手册：

• 没有手册时，新员工只能靠通用常识做事
• 有了手册后，新员工也能按标准流程高质量完成工作

Skill 就是给 AI 的"操作手册"——让它掌握你团队特有的知识、流程和标准。

与 Rules 和 MCP 的区别：

┌─────────────────────────────────────────────────────────────┐ │ Cursor AI Agent │ ├──────────┬──────────────────┬───────────────────────────────┤ │ Rules │ Skills │ MCP │ │ "守则" │ "操作手册" │ "工具箱" │ │ │ │ │ │ 始终生效的 │ 按需加载的 │ 连接外部系统的 │ │ 简短约束 │ 详细操作指南 │ 标准协议 │ └──────────┴──────────────────┴───────────────────────────────┘

• Rules：简短的约束条件，始终或按文件类型生效（< 50 行）
• Skills：详细的操作指南，AI 判断场景后按需加载（< 500 行）
• MCP：连接外部系统的协议，赋予 AI 调用外部工具的能力

第二步：Skill 编写流程

2.1 确定目录结构

skill-name/ ├── SKILL.md # 必须 - 主文件，AI 会读取 ├── reference.md # 可选 - 详细参考文档 ├── examples.md # 可选 - 使用示例 └── scripts/ # 可选 - 工具脚本 └── validate.py

2.2 编写 SKILL.md

文件由两部分组成：YAML 头部+Markdown 正文。

--- name: code-review description: >- 审查代码的质量、安全性和可维护性。 当用户提交 Pull Request、要求代码审查或提到"review"时使用。 --- # 代码审查 ## 快速开始 审查代码时按以下顺序检查： 1. 逻辑正确性和潜在 Bug 2. 安全最佳实践 3. 代码可读性 4. 测试是否充分 ## 审查清单 - [ ] 逻辑正确，边界情况已处理 - [ ] 无安全漏洞（SQL 注入、XSS 等） - [ ] 代码符合项目规范 - [ ] 错误处理完善 - [ ] 测试覆盖了变更内容 ## 反馈格式 - **严重**：合并前必须修复 - **建议**：建议改进 - **锦上添花**：可选优化 ## 补充资料 - 详细编码标准见 [STANDARDS.md](STANDARDS.md)

2.3 头部字段说明

2.4 编写关键原则

description 决定一切——AI 靠描述来决定是否加载你的 Skill：

• 用第三人称写："Generates commit messages by analyzing diffs"
• 同时说明 WHAT（做什么）和 WHEN（什么时候用）
• 包含触发关键词，如"pull request","code review","PDF"

正文要精简——上下文窗口是共享的，每个 token 都有成本：

• SKILL.md 控制在 500 行以内
• 只写 AI 不知道的专有知识，不要教它基础常识
• 详细内容放到reference.md等附属文件中（渐进式展开）

第三步：接入方式

3.1 存放位置

两种作用域，放到对应目录即可生效：

注意：不要放到~/.cursor/skills-cursor/，该目录是 Cursor 内置 Skill 专用。

3.2 示例：在项目中添加一个 Skill

your-project/ └── .cursor/ └── skills/ └── code-review/ ├── SKILL.md └── STANDARDS.md

不需要任何配置文件，放到目录里即可自动识别。

3.3 接入后的效果

1. Cursor 启动时自动扫描 Skill 目录
2. 当用户对话匹配 Skill 描述中的关键词时，AI 自动加载对应 Skill
3. AI 按照 SKILL.md 中的指引执行任务

总结