#规则与 Skills

规则把持久指令塞进 Agent 的上下文；Skills 把可移植的任务包（说明 + 可选脚本 / 参考）交给 Agent。二者都从 Customize 管理，也可落在仓库里给团队共用。权威页：Rules、Agent Skills。

#四种规则

规则在每次补全之间并不「记忆」——生效时，内容出现在模型上下文开头。官方明确：规则不影响 Tab；用户规则不影响 Ctrl+K / Cmd+K 行内编辑，只作用于 Agent（Chat）。

优先级（冲突时前者赢）：Team Rules → Project Rules → User Rules。能合并的会合并。

#Project Rules：.mdc 而不是随便一个 .md

.cursor/rules 里只有带 frontmatter 的 .mdc 会被识别。普通 .md 会被忽略（没有 description / globs / alwaysApply）。想写纯 Markdown 就用 AGENTS.md。

.cursor/rules/
  react-patterns.mdc
  api-guidelines.md          # 被忽略（扩展名不对）
  frontend/
    components.mdc

创建方式：

• Agent 里 /create-rule，描述你要的规则
• Customize → Rules → Add Rule

---
alwaysApply: true
---

- 不确定实现时，先读相关源码再改
- 不要修改 `dist/`、`build/` 里的生成文件

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- 使用 named export，不要 default export
- 组件超过 200 行就抽到同目录子组件

---
description: 后端 RPC 服务约定
alwaysApply: false
---

- 每个服务单独放在 `src/services/`
- 边界校验输入；错误返回 `{ code, message }`

多个 glob 用逗号：docs/**/*.md, docs/**/*.mdx。用 @filename.ts 引用仓库里的范例，而不是把整份风格指南贴进规则。

官方建议：单条规则少于约 500 行；拆成可组合的小规则；看到 Agent 反复犯同一错再加规则，不要预支一整本手册。规则要进 Git。

#用户规则与 AGENTS.md

用户规则适合跨项目的短偏好：

Reply in concise 中文. Do not add filler. Prefer existing libraries in the repo.

AGENTS.md 放在根目录即可，子目录的文件会叠加，更具体的优先：

# Project instructions

- TypeScript for new files
- Business logic stays in the service layer

Cursor 也能从 GitHub 导入远程 .mdc（Customize → Add Rule → Remote Rule），通常落到 .cursor/rules/imported/。

#Skills：目录 + SKILL.md

Skill 是符合 Agent Skills 标准的文件夹：一份 SKILL.md，可选 scripts/、references/、assets/。启动时 Cursor 会发现它们，Agent 按描述判断是否使用；你也可以在聊天里用 / 搜技能名。/ 调用默认只挂在这一条消息上；整段会话都要生效：macOS Opt+Enter、Windows Alt+Enter 当作 Custom Mode。

嵌套仓库里，更靠近子项目的 skill 会按目录收窄，类似 paths。

---
name: my-skill
description: Short description of what this skill does and when to use it.
---

# My Skill

When to use:

- ...

Instructions:

- ...

name 必须与父文件夹一致（小写、数字、连字符）。可选：paths（按文件收窄）、disable-model-invocation: true（只有输入 /skill-name 才带上）。

插件与 Marketplace 技能从 Customize 安装；团队可从 Dashboard 分发。内置技能随版本变，以 / 菜单为准，例如 /create-rule、/create-skill、/loop、/review。

#和 CLAUDE.md / AGENTS.md 对齐

若同事还用 Claude Code 或 Codex：

可共享的约定（测试命令、目录边界、禁止事项）放进根目录 AGENTS.md。只有 Cursor 需要的 glob / alwaysApply 放进 .mdc。Cursor 会读 Claude / Codex 的 skills 目录，反过来不保证完整对等——重复的「口头规范」只保留一份真相。

#最小可提交示例

# 在仓库根目录
New-Item -ItemType Directory -Force -Path .cursor\rules, .cursor\skills\pr-checklist | Out-Null

mkdir -p .cursor/rules .cursor/skills/pr-checklist

把上面的 alwaysApply 规则存成 .cursor/rules/repo.mdc，把 SKILL.md 放进 .cursor/skills/pr-checklist/（name: pr-checklist）。提交后再开 Agent：Follow the pr-checklist skill before you edit.

#下一步

• MCP 集成
• 与 CLI Agent 协作
• Agent 工作台