Cursor Agent Skills 从入门到上手：概念、写法、用法（含 Java 示例）

Cursor Agent Skills 从入门到上手概念、写法、用法含 Java 示例一、6 个核心概念LLM、Agent、Skill、Rule、MCP、模型1️⃣ LLM 是什么LLM Large Language Model 大语言模型简单说用海量文本训练出来的、能「读懂人话并生成文字」的 AI 引擎你常听的Claude、GPT、Gemini等都是 LLMCursor 里选的「模型」就是在选用哪一家/哪一版的 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.mdrules/*.mdc加载按需触发每次都注入用途做复杂任务守规矩例子Java 代码审查、生成测试Java 缩进、命名、架构可以这样记Rule 家规Skill 专项技能手册四、一句话串起来LLM 大语言模型技术名 模型在 Cursor 里的叫法模型 Agent 的大脑MCP 连接工具的协议通过它 AI 能使用各种工具Skill 怎么用工具Rule 不能乱用工具Agent 拿模型LLM当脑子、拿工具干活的人五、开启 Agent Skills必做步骤以下以 Cursor 2.6.x 为例具体菜单与快捷键以你当前 Cursor 版本为准。打开 Cursor设置Settings如CtrlShiftJ/CmdShiftJ点击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再以---结束后面才是正文 MarkdownYAML 元数据头里需有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必须大写方式3GitHub 直接装现成技能npx skillsaddanthropics/skills--yesnpx skillsaddVoltAgent/awesome-agent-skills--yesnpx skillsaddvercel-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 里选「模型」即在选 LLMAgent会自己干活的智能 AISkill它的专业技能如 Java 代码审查Rule它必须守的规矩MCP连接工具的协议通过它使用外部能力模型Agent 的大脑 选用的 LLM当前推荐主力 Claude 3.7 Sonnet 等以你 Cursor 可用列表为准全文涉及界面、命令、模型推荐等均以你当前 Cursor 版本与官方文档为准。