装了 Cursor 还天天翻车？因为你少写了这个文件

这周刷 CSDN 和技术号，Skills 又被拎出来反复讲。模型越来越强，可不少人用 Cursor、Claude Code 照样翻车：改错目录、乱起组件名、测试也不跑就喊「做完了」。

问题不一定出在模型。很多人缺的是一个很不起眼的东西——项目里的 SKILL.md。

你可以把它理解成给 Agent 看的操作说明书：什么时候该用、步骤怎么走、哪些事能做、哪些事先问你。写清楚了，它少猜一轮；写糊了，它就发挥「创造力」。

---

为啥 Rules 不够用了

Rules 适合放短约束，比如「用 TypeScript」「别提交 .env」。真遇到多步流程——发版检查、按规范生成组件、改接口还要同步文档——Rules 要么塞不下，要么每次都灌进上下文，又贵又吵。

Skills 的套路不一样：平时只暴露名字和描述，真匹配到任务才把正文加载进来。所以它适合放「流程」，不适合当万能系统提示词垃圾桶。

我自己的划分很简单：

• 天天要守的底线 → Rules
• 偶尔才走的一套 SOP → Skill
• 要连外部系统 → MCP / CLI，那是另一层事

别把这三者揉成一锅。揉了之后 Agent 自己也分不清优先级。

---

最小能用的 Skill 长什么样

目录大概这样：

.cursor/skills/pr-checklist/
  SKILL.md

（有的工具认 .agents/skills/，以你用的客户端文档为准，别死磕路径名字。）

SKILL.md 顶部要有一段 frontmatter。name 最好和文件夹名一致，description 决定它会不会被自动唤起——这句比正文还关键。

下面这个例子，专门治「改完代码就想提 PR，但漏测、漏说明」：

---
name: pr-checklist
description: 在准备提交代码或创建 PR 前使用。用于自检改动范围、补测试说明、写清风险点，避免漏改和空 PR 描述。
---

# PR 提交前检查

## 什么时候用
用户说「帮我提 PR」「准备提交」「看看还能不能合」时启用。

## 步骤（按顺序做，别跳）
1. 看当前改动文件列表，用一句话概括「这次到底改了什么」。
2. 确认有没有动到配置、权限、数据库相关文件；有的话必须在总结里点名。
3. 检查是否包含测试，或至少说明「为什么这次可以不测」。
4. 起草 PR 描述，必须包含：改动说明、验证方式、风险与回滚。
5. 如果发现明显无关文件被改到，先停下来问用户，不要擅自还原。

## 可以做
- 阅读 diff、运行项目里已有的测试命令
- 生成/补全 PR 描述草稿

## 先问再做
- 强制 push、改远程保护分支
- 删除文件、改 CI 密钥相关配置

## 别做
- 为了「好看」去大范围格式化无关代码
- 编造「已通过测试」——没跑就写没跑

就这点内容，已经比空喊「写个 PR」稳得多。Agent 有步骤可跟，你也有地方骂它「第 3 步你跳了」。

---

description 怎么写才招得来

很多人正文写挺长，结果 Skill 从来不亮。多半是 description 太虚。

虚的：

description: 帮助处理代码相关任务

稍微能用的：

description: 在准备提交代码或创建 PR 前使用。用于自检改动范围、补测试说明、写清风险点。

写的时候我会塞两类词：触发场景（提 PR、发版、加组件）和它具体能干啥。别写广告词，写给「路由器」看的匹配条件。

---

再补一个前端向的短例子

假如你们组件有固定套路，别每次口头复述。丢一个 Skill 进去：

---
name: new-react-component
description: 在 src/components 下新增 React 组件时使用。按项目约定生成组件文件、样式入口和基础 props 类型，避免随意命名和裸写内联样式。
---

# 新建 React 组件

## 步骤
1. 让用户确认组件名（PascalCase）和存放目录。
2. 创建 `ComponentName.tsx`，默认导出函数组件。
3. 同目录补 `index.ts` 做导出。
4. props 用 `type` 定义；不要用 `any`。
5. 样式走已有 CSS Module / 设计 token，禁止新开一套颜色魔法数。
6. 不做路由注册，除非用户明确要求。

## 质检
- 文件名与导出名称一致
- 没有引入未使用的依赖
- 能在本地通过现有 lint（若仓库有脚本就跑一下）

你一对比就明白：这不是「提示词文学」，是把团队习惯钉死。AI 越强，越需要这种钉子，不然它会用「它认为优雅」的方式改造你的仓库。

---

我踩过的三个坑

1. 写太长。 一上来三千字圣经，Token 白烧，Agent 还抓不住重点。先能跑通 20～40 行，真不够再拆第二个 Skill。

2. 只写愿望，不写边界。 「生成高质量代码」没用。要写清：能改哪些目录、能不能动数据库、失败了是重试还是停手问人。

3. 和口头习惯打架。 你平时说「提个 MR」，description 却只写「Pull Request」，匹配率会飘。把团队黑话写进去。

---

今天就能试的做法

挑一件你每周至少重复两次的事——提 PR、加接口、写 changelog，都行。按上面的模板建一个 Skill，故意用一次，看它跟不跟步骤。

如果它还是跳步，别先骂模型。先改 Skill：把步骤改成编号，把「先问再做」写死。这比换一个更贵的模型便宜，也见效更快。

Skills 这事不神秘。说白了，就是承认 Agent 会执行流程，于是你把流程从聊天记录里挪进仓库。谁先写，谁少熬夜看 diff。

（不同工具对 Skills 目录和字段略有差异，接入前看一眼你正在用的客户端说明就行。别把示例里的边界条款当成可以放开权限的理由。）