你清楚Skills和Rules吗：Cursor Agent 的 SKILL.md 与 Rules 配置拆解

1. 为什么你的 Cursor Agent 总在“乱干活”Skills 与 Rules 的职责边界很多人第一次接触 Cursor 的持久化指导机制时会把 Skills 和 Rules 当成同一种东西反正都是 Markdown都是写给 Agent 看的放哪儿不是放。结果就是两种典型翻车现场——要么把发版检查清单、数据库迁移步骤、代码评审模板全塞进 Always Apply 的 Rule 里导致每次改个错别字都要带着整本手册跑要么把“必须用中文回复”这种红线写进某个很少触发的 SkillAgent 转头就忘。我试过在一个中型前端仓库里同时维护 6 条 Rules 和 3 个 Skills踩过的最大坑就是没搞清“何时进上下文”这件事配置写得再漂亮也没用。先把结论摆出来维度RulesSkills本质持久约束 / 项目惯例按需加载的专项工作流进上下文方式常驻或按文件 glob 匹配自动带上Agent 根据 description 决定是否读取适合写什么编码规范、沟通偏好、文件级约定复杂流程、模板、脚本、领域手册体量建议短一条一事50 行内更佳主文件 500 行细节外挂一句话Rules 管“默认怎么做人、怎么写代码”Skills 管“碰到某类任务时按哪本操作手册做”。为什么要分成两套因为 Agent 的上下文窗口是共享资源。对话历史、打开的文件、Rules、Skills、工具说明都在抢 token。Rules 被设计成轻量、可预测——Always Apply 或匹配当前文件时注入保证风格和红线不会丢。Skills 被设计成按需、可渐进披露——平时只暴露 name description真相关时再读完整 SKILL.md 以及它链出去的参考文档和脚本。这个分工不是产品炫技而是上下文预算与触发时机的工程选择。你如果只记一件事就记这个删掉它会导致日常产出风格立刻跑偏的放 Rule只在某类任务里才需要的 SOP放 Skill。接下来我会按“原问题 → 前置准备 → 可复制配置 → 验证对比 → 排错 → 下一步”的顺序把.cursor/rules和SKILL.md的目录结构、配置片段、以及一次 Agent 任务的启用前后行为差异全部拆开讲。你可以直接照着建目录、贴配置、跑验证。2. 前置准备TaoToken 接入 Cursor Agent 的 Base URL 与 Key 配置在拆 Skills 和 Rules 之前得先让 Cursor Agent 能正常跑起来。如果你用的是自带模型额度可以跳过这节但如果你希望通过统一入口管理模型调用、方便在多个项目间切换那这一步值得花五分钟配好。TaoToken 在这里的角色是提供一个兼容 OpenAI 协议的 API 入口Cursor 的自定义模型配置可以直接对接。你需要准备三样东西Base URL、API Key、Model ID。Base URL填https://taotoken.net/api注意不要带任何多余路径。API Key在控制台的 API Keys 页面生成格式通常是一串以sk-开头的字符串。Model ID根据你实际要用的模型填比如claude-sonnet-4-20250514这类标识。在 Cursor 里的操作路径是打开 Settings → Models → 找到 OpenAI API Key 区域 → 填入你的 Key → 在 Override OpenAI Base URL 里填https://taotoken.net/api→ 点 Verify 验证。如果你用的是 Claude Code 或者 Codex 这类需要auth.json的工具配置逻辑类似核心三件套不变{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: claude-sonnet-4-20250514 }注意auth.json的路径要和你实际使用的工具要求一致不要自己造路径。Cursor 本身不走auth.json它走的是 Settings 里的 UI 配置但如果你同时用 Cline、CC Switch 这类工具它们的配置文件里同样需要 Base URL Key Model ID 三件套齐全缺一个都会报 401。配好之后建议先在 Cursor 的 Chat 里发一句“你好请用一句话确认你在线”确认模型能正常返回。这一步过了再往下做 Skills 和 Rules 的配置否则后面出问题你分不清是模型没通还是配置写错。另外提醒一点Cursor 的 Rules 和 Skills 是本地文件系统层面的机制和模型走哪个 API 入口无关。也就是说你换不换 Base URLRules 和 Skills 的生效逻辑都一样。所以先把模型通道打通再专心调 Agent 行为排错时变量更少。如果你还没有 Key可以去控制台创建一个记得创建后立刻复制保存页面刷新后就看不到了。接入文档里有各工具的详细配置截图对着填不容易错。3. 可复制配置.cursor/rules 与 SKILL.md 的目录结构与片段这一节是全文最核心的部分我会给出可以直接复制粘贴的目录结构和配置片段。你照着建五分钟内能跑起来。3.1 Rules 的目录结构与 .mdc 配置项目规则放在.cursor/rules/下文件扩展名是.mdc带 YAML frontmatter。先建目录mkdir -p .cursor/rules mkdir -p .cursor/skills/code-review mkdir -p .cursor/skills/db-migrate然后创建第一条 Always Apply 的 Rule文件路径.cursor/rules/git-safety.mdc--- description: 本仓库 Git 与安全底线 alwaysApply: true --- # Git 与安全 - 只有用户明确要求时才创建 commit / PR - 不要改 git config不要 force push main - 不要提交 .env、密钥、凭证文件 - 提交信息遵循 Conventional Commitstype(scope): subject再创建一条按 glob 匹配的 Rule文件路径.cursor/rules/typescript.mdc--- description: TypeScript 编码约定 globs: **/*.{ts,tsx} alwaysApply: false --- # TypeScript - 优先用 unknown 再收窄避免随意 any - 错误要带上下文再抛出禁止空 catch - 导出函数必须有显式返回类型 - 禁止在循环里做同步 I/OFrontmatter 三个字段的作用对照字段作用description说明这条规则干什么规则选择器里也会用到globs匹配到这些文件时应用文件级规则的核心alwaysApplytrue 则几乎每轮对话都带上除了项目级 Rules还有用户级 Rules在 Cursor Settings 里配置和仓库根目录的AGENTS.md。思路相同写成 Agent 应遵守的持续指导。团队共享优先放项目 Rule纯个人口味放用户级。3.2 SKILL.md 的目录结构与配置Skill 是一个目录里面至少有SKILL.md。完整结构长这样.cursor/skills/code-review/ ├── SKILL.md # 必需说明 步骤 ├── reference.md # 可选详细参考 ├── examples.md # 可选范例 └── scripts/ # 可选可执行脚本 └── validate.py个人 Skill 放~/.cursor/skills/skill-name/所有项目可用项目 Skill 放.cursor/skills/skill-name/跟仓库共享给同事。注意不要往~/.cursor/skills-cursor/里塞自己的 Skill那是 Cursor 内置技能目录由系统管理。SKILL.md的 frontmatter 和正文结构如下文件路径.cursor/skills/code-review/SKILL.md--- name: code-review description: 按团队标准做代码评审。在用户要求 review PR、检查改动或做 code review 时使用。 --- # Code Review ## 步骤 1. 读取 diff按文件分组 2. 检查命名、错误处理、边界条件 3. 检查是否有测试覆盖新增逻辑 4. 按反馈格式输出 ## 反馈格式 - 必须修阻塞合并的问题 - 建议不阻塞但值得改 - 可选风格偏好 ## 参考 详细检查清单见 [reference.md](reference.md)元数据字段要求字段要求作用name小写、数字、连字符≤64技能标识description非空≤1024发现与自动选用的关键写清 WHAT WHENdisable-model-invocation可选true 时偏“点名才用”description 写砸了等于 Skill 不存在。要用第三人称、具体能力、明确场景。对比一下好的从 PDF 提取文本与表格、填表、合并。在处理 PDF、表单或文档抽取时使用。差的帮忙处理文档3.3 组合配置Rule 指路 Skill 干活推荐的做法是短 Rule 指路深 Skill 干活。比如在.cursor/rules/git-safety.mdc里加一句--- description: 本仓库 Git 与安全底线 alwaysApply: true --- # Git 与安全 - 用户要求提交时遵循项目 commit 约定详见 code-review skill - 只有用户明确要求时才创建 commit / PR - 不要改 git config不要 force push main这样 Rule 负责提醒“要走约定”Skill 负责“约定的完整操作法”。文件级 Rule 挡住低级错误领域 Skill 在真做任务时展开全流程。4. 验证请求一次 Agent 任务对比启用前后的行为差异配置写完了怎么知道它真的生效这一节我用一个真实任务来对比让 Agent 评审一段有问题的 TypeScript 代码。4.1 准备测试代码新建src/utils/parse.ts故意留几个问题export function parseConfig(input: any) { try { const data JSON.parse(input) return data } catch (e) { return null } }这段代码有三个问题用了any、空catch吞掉错误、没有显式返回类型。正好对应我们前面写的typescript.mdc规则。4.2 启用前无 Rules 无 Skills先把.cursor/rules/和.cursor/skills/临时改名让配置不生效。然后在 Cursor Chat 里发帮我 review 一下 src/utils/parse.tsAgent 的典型回复会是泛泛的“这个函数看起来可以工作但建议增加错误处理。”它不会指出any违反约定也不会按“必须修/建议/可选”的格式输出。因为没有任何持久化指导告诉它这个项目的标准是什么。4.3 启用后Rules Skills 同时生效把目录改回来重新发同样的请求。这次 Agent 的行为会明显不同第一它会先读typescript.mdc因为当前文件匹配**/*.{ts,tsx}指出any应该换成unknown再收窄空catch违反“错误要带上下文再抛出”。第二它会识别到“review”这个触发词去读code-review/SKILL.md按里面的步骤走读 diff → 检查命名/错误处理/边界 → 检查测试覆盖 → 按反馈格式输出。第三输出会变成结构化的必须修 - parseConfig 的 input 参数用了 any违反 typescript.mdc建议改为 unknown 并做类型收窄 - catch 块为空错误被吞掉应带上上下文再抛出 建议 - 增加显式返回类型当前推断为 any | null 可选 - 考虑用 zod 做运行时校验4.4 优先级与生效范围验证再做一个对照实验把typescript.mdc的globs改成**/*.py重新 review 同一个.ts文件。你会发现 Agent 不再提any的问题因为文件级 Rule 没匹配上。但git-safety.mdc是 Always Apply它依然在上下文里——你可以让 Agent 提交代码它会拒绝未经明确要求的 commit。这说明两者的生效范围是正交的Rules 按 alwaysApply 或 globs 决定是否注入Skills 按 description 匹配决定是否读取。叠加时不存在“谁覆盖谁”而是各管各的维度。Rule 管红线Skill 管流程同时生效。如果你在验证时发现 Agent 没按预期读 Skill先检查 description 里有没有写清 WHEN。触发词要贴近用户的实际说法比如用户会说“帮我看看这个 PR”那 description 里就该有“review PR”这样的表述。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易卡住的不是 Rules 和 Skills 本身而是模型通道和工具链的报错。这一节把几个高频错误对照着讲。5.1 401 Unauthorized报错原文通常是Error: 401 Unauthorized - invalid api key原因几乎都是 Key 没填对或 Base URL 写错。检查三件套Base URL 是不是https://taotoken.net/api不要带/v1或尾部斜杠、Key 是不是完整复制创建后只显示一次、Model ID 是不是当前账号可用的。三个里错一个都会 401。5.2 local proxy failed报错原文local proxy failed: connection refused这个通常出现在你本地配了代理工具但没启动或者 Cursor 的网络设置指向了一个不存在的本地端口。处理方式是检查 Cursor Settings 里的 Proxy 配置清空自定义代理让它走系统默认。如果你在用 Cline 或 CC Switch检查它们的配置文件里有没有残留的 proxy 字段。5.3 reading choices 相关报错报错原文类似Error reading choices: unexpected end of JSON input这多半是模型返回了非预期格式常见于 Model ID 填错导致服务端返回了错误页而不是 JSON。确认 Model ID 拼写正确并且该模型在你的账号下有权限。如果换了 Model ID 就好了那就是模型标识的问题。5.4 OAuth 相关报错报错原文OAuth token expired, please re-authenticate如果你用的是 Claude Code 或 Codex 这类走 OAuth 的工具token 过期后需要重新走授权流程。但如果你是通过 API Key 接入的就不该出现 OAuth 报错——出现了说明工具还在走旧的认证方式去配置文件里把认证模式改成 API Key。5.5 Skills 不触发Agent 从不自动读你的 Skill检查两点description 里有没有具体的 WHAT 和 WHENdisable-model-invocation是不是被设成了 true。如果是 true只有你点名“按 xx skill 做”才会加载。5.6 Rules 和 Skills 内容冲突Agent 左右横跳一会儿按 Rule 一会儿按 Skill。处理原则Rule 只留红线与摘要细节以 Skill 为准删掉重复段落。比如 Rule 里写“遵循 commit 约定”Skill 里写完整的 commit 格式不要在 Rule 里也抄一遍格式细节。6. 下一步从一条 Rule 加一个 Skill 开始落地如果你准备在这个仓库里落一套我的建议是从最小可用组合开始一条 Always Apply 的 Rule 加一个最高频工作流的 Skill。Always Rule 就写三条红线比如“未经要求不 commit”“不提交密钥文件”“提交信息遵循 Conventional Commits”。Skill 就选你团队最高频的那个流程比如 code review 或者发版检查。先跑一周看 Agent 的行为有没有变稳再决定要不要加第二条 Rule 或第二个 Skill。一次性写十份空模板不如把一条 Rule 和一个 Skill 打磨到真正生效。上下文更干净行为也更可预测。如果你在配置过程中遇到模型通道的问题可以去接入文档对照排查想先验证模型是否正常用模型对话发一句话最快如果准备长期在多个项目里用 Agent 做编码Coding Plan 能省掉反复配 Key 的麻烦。