Cursor Agent Skills 从入门到上手：概念、写法、用法（含 Java 示例）
一、6 个核心概念：LLM、Agent、Skill、Rule、MCP、模型
1️⃣ LLM 是什么？
LLM = Large Language Model = 大语言模型
- 简单说：用海量文本训练出来的、能「读懂人话并生成文字」的 AI 引擎
- 你常听的 Claude、GPT、Gemini 等，都是 LLM；Cursor 里选的「模型」就是在选用哪一家/哪一版的 LLM
- 关系：LLM 是技术名，模型是产品里的叫法，在 Cursor 里可以当作一回事
2️⃣ Agent 是什么？
Agent = 智能体 = 会自己思考干活的 AI
- 普通 AI：你说一句，它做一句
- Agent AI：你给目标，它自己查文件、改代码、拆步骤、自动完成
- 地位：整个 Cursor 的主角，所有功能都是给它用的
3️⃣ Skill 是什么？
Skill = 一套固定工作流（SOP= Standard Operating Procedure）
- 文件：
SKILL.md（必须大写） - 作用：让 AI 按你写的步骤专业干活
- 场景：代码审查、生成测试、接口文档、重构优化
- 触发：
/命令或自动匹配
4️⃣ Rule 是什么？
Rule = 全局规范 / 约束
- 文件：
.cursor/rules/xxx.mdc - 作用：每次对话都会注入，供 AI 尽量遵守（缩进、命名、架构、团队规范）
- 特点：每次对话都会生效
- 写法：在
.cursor/rules/下新建xxx.mdc，用自然语言写规范即可，对话时会自动注入
5️⃣ MCP 是什么？
MCP = Model Context Protocol 简单说：AI 连接外部工具的“通用接口”
- 让 AI 能读数据库、调 API、查浏览器、执行命令
- 相当于给 AI 加了手脚
- 使用：在 Cursor 设置 → MCP 中配置/启用 MCP 服务器，常见如 filesystem、浏览器、数据库等
6️⃣ 模型是什么？
模型 = Agent 的大脑 = 在 Cursor 里选的 LLM
- 决定：聪明程度、推理能力、代码质量、速度、价格
- 和 LLM 的关系：选「模型」就是在选用哪个 LLM 来当 Agent 的脑子
二、模型哪家强？（当前推荐，以你 Cursor 可用列表为准）
综合表现突出（编程 + Agent + 长上下文）
Claude 3.7 Sonnet
- 代码推理、重构、Debug 最稳（Java 开发首选）
- Agent 任务拆解、跨文件操作最强
- 适合：复杂 Java 项目、企业开发、Agent 主力
日常开发：速度快、体验顺
GPT-4o / GPT-4.5
- 速度快、体验顺
- 适合：快速 Java 开发、CRUD、日常写码
前端/看图/性价比
Gemini 3.1 Flash
- 看图转代码很强
- 便宜、量大划算
顶配（贵）
Claude 3.7 Opus
- 最强但最贵，只适合超复杂 Java 架构/疑难问题
Cursor 自带
Composer
- 快、便宜，但复杂任务不如上面三家
以上为 2026 年初实测结论，为主观体验与社区常见推荐，非正式基准测试。模型名称与可用性因地区/账号可能不同，请以你当前 Cursor 里的模型列表为准。
三、一张表分清：Skill vs Rule
| 对比 | Skill（技能） | Rule（规则） |
|---|---|---|
| 本质 | 工作流 / 步骤 | 规范 / 约束 |
| 文件 | SKILL.md | rules/*.mdc |
| 加载 | 按需触发 | 每次都注入 |
| 用途 | 做复杂任务 | 守规矩 |
| 例子 | Java 代码审查、生成测试 | Java 缩进、命名、架构 |
可以这样记：
- Rule = 家规
- Skill = 专项技能手册
四、一句话串起来
- LLM = 大语言模型（技术名）= 模型（在 Cursor 里的叫法）
- 模型 = Agent 的大脑
- MCP = 连接工具的协议（通过它 AI 能使用各种工具）
- Skill = 怎么用工具
- Rule = 不能乱用工具
- Agent = 拿模型（LLM）当脑子、拿工具干活的人
五、开启 Agent Skills（必做步骤）
以下以 Cursor 2.6.x 为例，具体菜单与快捷键以你当前 Cursor 版本为准。
- 打开 Cursor 设置（Settings） （如
Ctrl+Shift+J/Cmd+Shift+J） - 点击Rules, Skills, Subagents（或直接搜索 “Rules” / “Skills”） 3.Skills 区块：下方会列出已发现的技能（来自
~/.cursor/skills、.cursor/skills等）；可点 + New 或 New Skill 新建技能 4.可选：聊天框输入/reload-skills刷新技能列表
若需最新 Skill 支持：可进入 Beta → 切换 Nightly → 重启更新；部分版本在 Features 中即可开启相关能力。
六、Skill 放在哪里？（内置 / 个人 / 项目）
内置 Skill（不要动）
- 位置：
~/.cursor/skills-cursor/（Windows 下如C:\Users\你的用户名.cursor\skills-cursor） - 里面是啥：Cursor 自带的技能（如 create-skill、create-rule 等），由 Cursor 自动管理
- 讲究：不要在这里新建或修改；该目录专门给内置技能用，你放的技能可能被覆盖或识别不到
自己创建的 Skill（两个合法位置）
| 类型 | 路径 | 作用范围 | 适合场景 |
|---|---|---|---|
| 个人技能 | ~/.cursor/skills/技能名/ | 本机所有项目 | 个人通用（如代码审查、commit 规范） |
| 项目技能 | 项目根目录 .cursor/skills/技能名/ | 当前仓库 | 团队共享、随仓库进 Git |
- 技能名：一般与 YAML 里的
name一致，小写、连字符，如java-code-review - 文件夹里：必须有
SKILL.md（大写）；可选reference.md、examples.md、scripts/等
小结
内置只读（~/.cursor/skills-cursor/）；个人技能放 ~/.cursor/skills/技能名/（全项目可用）；项目技能放 .cursor/skills/技能名/（随仓库走）。禁止在 skills-cursor 下自建或修改。
七、写 Skill 的格式要求（从哪来、要不要遵守）
来源说明：以下格式来自 Cursor 内置的 create-skill 技能文档，并非单独对外的「官方规范」网页。要不要遵守？ Agent 按「目录有 SKILL.md、文件头为 YAML 且含 name/description」来识别；不按此写很可能无法被识别或自动匹配，故建议遵守。
建议满足的 3 点（不满足可能无法被识别）
| 要求 | 说明 |
|---|---|
| 文件名 | 必须是 SKILL.md（大写），放在技能目录下，如 .cursor/skills/java-code-review/SKILL.md |
| 开头格式 | 文件必须以 YAML 头开头，即第一行是 ---，接着写 name 和 description，再以 --- 结束，后面才是正文 Markdown |
| YAML 元数据 | 头里需有 name（技能唯一标识）、description（简短描述，用于 AI 判断何时用这个技能）；无则可能无法被识别 |
name / description 规则
-
name：最多 64 字符，只允许小写字母、数字、连字符，例如
java-code-review。用于唯一标识技能。 -
description：最多 1024 字符，不能为空。建议用第三人称写「做什么」+「什么时候用」，方便 AI 自动匹配。
- ✅ 好：
Review Java code for security and style. Use when the user asks for code review or mentions Java/SpringBoot. - ❌ 差：
我可以帮你审查代码（第一人称、太泛）
- ✅ 好：
目录结构（推荐）
.cursor/skills/你的技能名/
├── SKILL.md # 必选，主说明
├── reference.md # 可选，详细参考
├── examples.md # 可选，示例
└── scripts/ # 可选，脚本
- 主文件 SKILL.md 建议控制在 500 行以内，详细内容可放到
reference.md等，在 SKILL.md 里用链接引用。
八、推荐写法：SKILL.md 结构（按 create-skill 文档）
下面这段是 Cursor 内置 create-skill 文档里给出的 SKILL.md 结构：先 YAML 头，再标题，再 Instructions，最后可按需加 Examples 等。不按此写可能无法被识别，建议照此来。
最小可用模板（复制即用）
---
name: your-skill-name
description: Brief description of what this skill does and when to use it.
---
# Your Skill Name
## Instructions
Clear, step-by-step guidance for the agent.
- 第一行必须是
---，不能是# 标题。 name用英文、小写、连字符，如java-code-review。description用英文写「做什么 + 何时用」，AI 靠它自动选技能。
Java 专用完整示例（符合官方格式）
---
name: java-code-review
description: Review Java code for security, style, and Spring Boot best practices. Use when the user asks for code review, or when working with Java/SpringBoot files.
---
# Java 代码审查
## Instructions
1. 仅分析选中的 Java 代码。
2. 检查：SQL 注入、未处理异常、编码规范、性能问题、Spring Boot 最佳实践。
3. 标注风险等级：高危/中危/低危 + 行号。
4. 每条问题给出「修复前 + 修复后」代码片段。
5. 用 Markdown 列表输出，简洁无废话。
- 若你需要「命令」或「领域」等扩展信息，可在正文里自己加
## Commands、## Domain等小节。create-skill 文档里明确要求的只有：YAML 头（name + description）+ 正文里的 Instructions。
九、3 种创建 Skill 方式
方式1：一键创建（新手首选）
聊天框输入：
/create-skill
按提示填：名称、描述、指令，自动生成
方式2：手动创建（最常用）
mkdir -p .cursor/skills/java-code-review
在里面新建：SKILL.md（必须大写）
方式3：GitHub 直接装（现成技能）
npx skills add anthropics/skills --yes
npx skills add VoltAgent/awesome-agent-skills --yes
npx skills add vercel-labs/agent-skills --yes
第三方技能仓库若命令或地址有变动，请以 Cursor 及对应仓库官方文档为准。
十、如何使用 Skill（显式 + 自动两种）
不必每次显式引用。 AI 会根据 Skill 的 description（尤其是「什么时候用」）自动判断，在合适场景下不输入命令也可能自动启用该技能；是否启用由 Cursor 当前实现与对话上下文决定。
两种用法
| 方式 | 说明 | 示例 |
|---|---|---|
| 显式调用 | 你主动指定用哪个技能 | 输入 /java-review，或 @Java代码审查 + 需求 |
| 自动匹配 | AI 根据当前对话/选中内容与 description 匹配，自动选用 | 你说「帮我审一下这段 Java 代码」、或打开/选中 Java 文件并提问，AI 可能自动套用「Java 代码审查」技能 |
想让 AI「不提示也会用」？
自动匹配依赖 description 写清「何时用」和关键词，写法要点见第七节。
操作小结
- 显式用：选中代码 →
/命令或@技能名+ 需求 - 自动用：正常对话即可，AI 按 description 匹配；希望常被用则写好「何时用」（见第七节）
- 有更新：输入
/reload-skills刷新
十一、编写 Skill 时建议遵循的 5 条
在满足第七节硬性要求（YAML 头、name、description）的前提下，再注意下面 5 条：
- 指令要具体：别写“优化代码”，写“输出可复制修复代码，遵循 Java 官方规范”
- 步骤要清晰：1/2/3 步写清楚
- 范围要明确：指定 Java、SpringBoot 等场景
- 加示例：AI 更懂你要什么
- 加 Knowledge：喂 Java 规范，AI 更专业
十二、常见问题速解
- Skill 不显示：检查① 文件名是否为
SKILL.md（大写）② 第一行是否为---（不能先写# 标题）。详见第七节。 - name 报错：
name只能小写字母、数字、连字符，且不超过 64 字符 - AI 不自动用我的技能：把
description写清「做什么」+「什么时候用」+ 第三人称，详见第七节 - AI 不听话：Instructions 太模糊，拆成 1/2/3 步骤
- 刷新不生效：输入
/reload-skills或重启 Cursor
十三、总结：一句话对应关系
- LLM：大语言模型，Claude/GPT/Gemini 都是 LLM；在 Cursor 里选「模型」即在选 LLM
- Agent：会自己干活的智能 AI
- Skill：它的专业技能（如 Java 代码审查）
- Rule：它必须守的规矩
- MCP：连接工具的协议，通过它使用外部能力
- 模型：Agent 的大脑（= 选用的 LLM，当前推荐主力 Claude 3.7 Sonnet 等，以你 Cursor 可用列表为准）
全文涉及界面、命令、模型推荐等，均以你当前 Cursor 版本与官方文档为准。
本文使用 markdown.com.cn 排版
