一、Rules

官方学习文档：https://cursor.com/cn/docs/context/rules

🧩 什么是 Cursor Rules？

Rules（规则） 是 Cursor IDE 中一种 让 AI 更懂你项目上下文和编码规范 的机制。

你可以把它理解为：给 AI 助手的“操作手册”或“领域知识库”。

✅ 目标：让 AI 在生成、修改或解释代码时，自动遵守你的项目约定、安全规范、硬件限制等。

🔁 Rules vs Skills（关键区别）

特性	Rules	Skills
触发方式	自动（基于文件路径 + 上下文）	手动（/skill-name）或自动（若未禁用）
主要用途	约束/指导 AI 行为（“应该怎么做”）	执行具体任务（“帮我做某事”）
文件扩展名	.mdc	SKILL.md
是否需配置路径	是（通过 globs）	否（通过关键词或显式调用）
适合内容	规范、原则、限制	模板、脚本、自动化流程

🎯 简单记：

• Rules = “规矩”（AI 必须遵守的纪律）

• Skills = “技能”（AI 能帮你完成的任务）

二、Agent Skills

AI Coding 实践分享——skills使用

Skills 将特定领域的知识和工作流封装起来，智能体可以调用这些 Skills 来执行特定任务。

Cursor 启动时，会自动从技能目录中发现并加载技能，并将它们提供给 Agent 使用。Agent 会看到所有可用技能，并根据当前上下文决定何时调用它们。

你也可以在 Agent 对话中输入 / 并搜索技能名称来手动调用技能。

官方学习文档：https://cursor.com/cn/docs/context/skills

1、什么内容适合创建 Skill？

🎯 核心原则：重复性 + 结构化 + 可复用

✅ 适合创建 Skill 的场景（你的领域举例）：

场景	说明
1. 固定代码模板生成	- 生成 ROS 2 节点骨架（含 rclcpp、QoS 配置） - 创建 UDP 多播接收器模板 - RTSP 推流器（基于 live555 / FFmpeg）
2. 设备协议解析/封装	- 自动解析 Pelco-D、雷达私有协议帧 - 生成 CRC 校验 + 打包函数 - 将二进制协议转为 JSON 用于调试
3. 调试辅助任务	- “插入日志：记录 PTZ 当前角度” - “添加断言：检查 UDP 缓冲区是否溢出” - “生成 GDB 调试脚本”
4. 文档与注释生成	- 为 C++ 类自动生成 Doxygen 注释 - 为 ROS 2 Topic/Service 添加接口说明
5. 安全与合规检查	- 检查 malloc 是否配对 free - 禁止使用 strcpy，建议 strncpy

❌ 不适合创建 Skill 的场景：

• 一次性任务（如“今天修复这个 bug”）

• 高度动态、无固定模式的需求

• 涉及敏感密钥或内部 IP 的操作（除非用本地模型）

---

2、怎么创建一个 Skill？（零代码 + 代码两种方式）

方式 1️⃣：零代码创建（推荐初学者）

利用 Cursor 内置的 skill-creator 元技能

步骤：

1. 打开 Cursor 聊天窗口（Cmd/Ctrl + K）

2. 输入创建意图，例如：

我想创建一个 Skill，当我选中一段 C++ 代码时，能自动为其生成 Google Test 单元测试。

1. 回答 AI 的追问（关键！）：

   1. Q: “输入是什么？” → A: “用户选中的 C++ 函数或类”

   2. Q: “输出格式？” → A: “完整的 .cc 测试文件，包含 TEST_F 宏”

   3. Q: “质量标准？” → A: “覆盖主要分支，使用 Mock 对象”

2. AI 自动生成 .skill 文件包

3. 下载并激活：

   1. 解压后放入 .cursor/skills/

   2. 或直接在 Settings > Skills 中上传

💡 优势：无需写 YAML，适合快速原型

---

方式 2️⃣：手动编写 Skill（推荐开发者）

Skill 本质是一个带元数据的目录，结构如下：

my-rtsp-skill/
├── SKILL.md               # 主说明文档（必需）
├── rules/                 # 可选：旧版规则迁移
└── assets/                # 可选：参考文档、示例

最小化 SKILL.md 示例（用于生成 ROS 2 节点）：

---
name: ros2-node-generator
description: Generate a C++ ROS 2 node with publisher/subscriber
disable-model-invocation: false
trigger:
  keywords: ["ros2", "create node", "rclcpp"]
---

When the user asks to create a ROS 2 node in C++, generate a complete file with:

- Proper includes (`rclcpp`, `std_msgs`)
- Class-based node structure
- Configurable topic name and QoS
- CMakeLists.txt snippet

Example input: "Create a ROS 2 node that publishes radar tracks"
Example output: Full C++ code + build instructions

部署：

1. 创建目录：.cursor/skills/ros2-node-generator/

2. 放入 SKILL.md

3. 重启 Cursor 或刷新 Skills

🔧 提示：可在 SKILL.md 中引用 assets/ 下的协议文档，让 AI 更懂你的私有格式。

3、从 GitHub 安装技能

可以从 GitHub 仓库导入技能：

1. 打开 Cursor Settings → Rules

2. 在 Project Rules 部分，点击 Add Rule

3. 选择 Remote Rule (Github)

4. 输入 GitHub 仓库的 URL

4、将规则和命令迁移到技能

执行 /migrate-to-skills 后会发生什么？（逐步演示）

假设你的项目中有以下内容：

.cursor/
├── rules/
│   ├── add-logging.yaml       # alwaysApply: false, 无 globs → ✅ 会被迁移
│   └── format-cpp.yaml        # globs: ["*.cpp"] → ❌ 不迁移
└── commands/
    └── generate-test.yaml     # /generate-test 命令 → ✅ 会被迁移

步骤 1：在 Agent 聊天框输入

/migrate-to-skills

步骤 2：Agent 分析并转换

• 扫描 .cursor/rules/ 和 .cursor/commands/

• 找出符合迁移条件的文件

• 自动生成对应的 Skill 文件

步骤 3：生成 .cursor/skills/ 目录

结果可能如下：

.cursor/
├── skills/
│   ├── add-logging.skill.yaml      # 由 add-logging.yaml 转换而来
│   └── generate-test.skill.yaml    # 由 generate-test.yaml 转换而来，含 disable-model-invocation: true
├── rules/          # 原文件保留（不会删除！）
└── commands/       # 原文件保留

步骤 4：新 Skill 生效

• 你现在可以：

  • 继续用 /generate-test 调用命令（行为不变）

  • 让 AI 在合适场景自动建议 “add logging”（如果上下文匹配）

• 同时，你可以在 .cursor/skills/ 中 编辑、增强、分享 这些技能

附录：最值得使用的通用型 Cursor Rules / Skills

1. steipete/agent-rules

⭐ 这是目前 GitHub 上质量最高、生态最完善的 Rules 体系，被 CSDN、稀土掘金等多次推荐。

• 适用性：✅ 极高（支持 C/C++、嵌入式、ROS、Git 规范）

• 核心功能：

  • commit.mdc：Conventional Commits 提交规范（你刚问过！）

  • check.mdc：代码质量检查（支持 C/C++ 静态分析规则）

  • five.mdc：五问法 Bug 根本原因分析（适合调试雷达通信异常）

  • mermaid.mdc：自动生成架构图（画数据流：比如雷达 → PTZ → RTSP）

• 安装：

# Cursor 用户
mkdir -p ~/.cursor/rules
cp agent-rules/project-rules/*.mdc ~/.cursor/rules/

• 为什么适合你： 它提供 结构化工程思维，而不仅是代码片段——这对高可靠性嵌入式系统至关重要。

ME: 已安装的 Rules (来自 steipete/agent-rules)

规则	用途	适合嵌入式应用场景
commit	Conventional Commits 提交规范 + Emoji	✅ Git 提交
commit-fast	快速提交（跳过检查）	✅ 紧急修复
five	五问法根因分析	✅ 调试雷达/PTZ 问题
check	代码质量检查	✅ C++ 静态分析
mermaid	自动生成架构图	✅ 画数据流图
bug-fix	Bug 修复流程	✅ 问题排查
analyze-issue	问题分析	✅ 复杂 Bug
code-analysis	代码分析	✅ 代码审查
pr-review	PR 审查	✅ 代码评审
create-docs	创建文档	✅ 协议文档
update-docs	更新文档	✅ README 维护
implement-task	任务实现	✅ 新功能开发
clean	代码清理	✅ 重构
context-prime	上下文准备	✅ 大项目导航
add-to-changelog	更新变更日志	版本发布
create-command	创建命令工具	CLI 开发
continuous-improvement	持续改进	流程优化
cursor-rules-meta-guide	Rules 编写指南	创建自定义规则
modern-swift	Swift 开发	❌ 不适用
safari-automation	Safari 自动化	❌ 不适用
screenshot-automation	截图自动化	❌ 不适用
mcp-*	MCP 相关	高级功能

已创建的中文版 Rules（8个）

规则	用途	适用场景
commit-cn	Git 提交规范	每次提交代码时
five-cn	五问法根因分析	调试复杂 Bug
check-cn	C++/ROS2 代码检查	代码质量检查
mermaid-cn	Mermaid 图表生成	画架构图/数据流图
bug-fix-cn	Bug 修复流程	修复问题时
embedded-cpp-cn	嵌入式 C++ 规范	编写 C++ 代码时
ros2-node-cn	ROS2 节点最佳实践	开发 ROS2 节点时
code-review-cn	代码审查检查清单	审查代码时

文件位置

~/.cursor/rules/

├── commit-cn.mdc # 提交规范

├── five-cn.mdc # 五问法

├── check-cn.mdc # 代码检查

├── mermaid-cn.mdc # 图表生成

├── bug-fix-cn.mdc # Bug 修复

├── embedded-cpp-cn.mdc # 嵌入式 C++ 规范

├── ros2-node-cn.mdc # ROS2 最佳实践

├── code-review-cn.mdc # 代码审查

└── ... (英文版 24 个)

总计已安装

• 英文版：24 个（来自 steipete/agent-rules）

• 中文版：8 个（针对你的 C++/嵌入式/ROS2 场景优化）